@mastra/mcp-docs-server 1.1.35-alpha.8 → 1.1.35

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -8,13 +8,11 @@ For setup instructions, see the [Metrics overview](https://mastra.ai/docs/observ
 
 Metrics are extracted from spans when they end. The observability layer inspects each completed span, calculates duration, and (for model generation spans) reads token usage data. No manual instrumentation is needed.
 
-Metrics are routed through an internal event bus to the `DefaultExporter`, which batches and flushes them to storage.
-
 ### What affects whether a metric is available
 
 Two conditions must be true for a metric to reach storage:
 
-1. `DefaultExporter` is configured as an exporter.
+1. `MastraStorageExporter` is configured as an exporter.
 2. The storage backend supports metrics (ClickHouse or DuckDB).
 
 If metrics aren't appearing, see [troubleshooting](#troubleshooting).
@@ -117,7 +115,7 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
 ### No metrics are appearing
 
 - **Observability is configured**: Verify that your `Mastra` instance has an `observability` config with at least one exporter.
-- **`DefaultExporter` is present**: Other exporters (Datadog, Langfuse, etc.) don't persist metrics to Mastra storage. `DefaultExporter` is required for the Studio dashboard.
+- **`MastraStorageExporter` or `MastraPlatformExporter` is present**: Other exporters (Datadog, Langfuse, etc.) don't surface metrics in Mastra. `MastraStorageExporter` is required for the local Studio dashboard, and `MastraPlatformExporter` is required to view metrics in Mastra Platform.
 - **Storage supports metrics**: Metrics require an OLAP-capable store (ClickHouse or DuckDB). Row-oriented databases (PostgreSQL, LibSQL, MSSQL) and document stores (MongoDB) are not supported for metrics.
 - **Sampling isn't 0%**: If sampling probability is `0` or strategy is `never`, all spans become no-ops and no metrics are extracted.
 

package/.docs/reference/observability/tracing/bridges/datadog.md

@@ -129,7 +129,7 @@ The bridge can be combined with non-Datadog exporters to send traces to addition
 
 ```typescript
 import { Mastra } from '@mastra/core'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 import { DatadogBridge } from '@mastra/datadog'
 
 const mastra = new Mastra({
@@ -141,7 +141,7 @@ const mastra = new Mastra({
           mlApp: process.env.DD_LLMOBS_ML_APP!,
         }),
         exporters: [
-          new DefaultExporter(), // Studio access
+          new MastraStorageExporter(), // Studio access
         ],
       },
     },

package/.docs/reference/observability/tracing/bridges/otel.md

@@ -2,7 +2,7 @@
 
 > **Warning:** The OpenTelemetry Bridge is currently **experimental**. APIs and configuration options may change in future releases.
 
-Enables bidirectional integration between Mastra tracing and OpenTelemetry infrastructure. Creates native OTEL spans for Mastra operations and inherits context from active OTEL spans.
+Enables bidirectional integration between Mastra tracing and OpenTelemetry infrastructure. Creates native OTEL spans for Mastra operations and inherits context from active OTEL spans. Also forwards Mastra log events to the globally-registered OTEL `LoggerProvider`, emitting each log under the OTEL context of the originating Mastra span so trace-log correlation works automatically.
 
 ## Constructor
 
@@ -32,7 +32,29 @@ Executes a synchronous function within the OTEL context of a Mastra span.
 
 **Returns:** `T` - The result of the function execution.
 
-### shutdown
+### `onLogEvent`
+
+```typescript
+async onLogEvent(event: LogEvent): Promise<void>
+```
+
+Forwards a Mastra log event to the globally-registered OTEL `LoggerProvider`. Trace correlation is resolved in this order:
+
+1. If the log carries a `spanId` the bridge has an OTEL span for, the log is emitted under that span's stored OTEL context.
+2. Otherwise, if the log carries `traceId` and `spanId`, those IDs are attached to the emitted log record's `SpanContext`.
+3. Otherwise, the log is emitted under whatever OTEL context is currently active.
+
+If no `LoggerProvider` is registered globally, emission is a silent no-op.
+
+### `flush`
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes the global OTEL tracer provider and logger provider if they support `forceFlush`. Useful in serverless environments where you need to drain telemetry before the runtime terminates.
+
+### `shutdown`
 
 ```typescript
 async shutdown(): Promise<void>
@@ -68,7 +90,7 @@ The bridge can be used alongside exporters. The bridge handles OTEL context, whi
 
 ```typescript
 import { Mastra } from '@mastra/core'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 import { OtelBridge } from '@mastra/otel-bridge'
 import { LangfuseExporter } from '@mastra/langfuse'
 
@@ -79,7 +101,7 @@ const mastra = new Mastra({
         serviceName: 'my-service',
         bridge: new OtelBridge(), // Handles OTEL context
         exporters: [
-          new DefaultExporter(), // Studio access
+          new MastraStorageExporter(), // Studio access
           new LangfuseExporter({
             // Additional destination
             publicKey: process.env.LANGFUSE_PUBLIC_KEY,

package/.docs/reference/observability/tracing/configuration.md

@@ -7,15 +7,18 @@ interface ObservabilityRegistryConfig {
   default?: { enabled?: boolean }
   configs?: Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>
   configSelector?: ConfigSelector
+  sensitiveDataFilter?: boolean | SensitiveDataFilterOptions
 }
 ```
 
-**default** (`{ enabled?: boolean }`): Enable default configuration with DefaultExporter and CloudExporter
+**default** (`{ enabled?: boolean }`): Enable default configuration with MastraStorageExporter and MastraPlatformExporter
 
 **configs** (`Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>`): Named observability instance configurations or pre-instantiated instances
 
 **configSelector** (`ConfigSelector`): Runtime configuration selector function
 
+**sensitiveDataFilter** (`boolean | SensitiveDataFilterOptions`): Controls whether a \[SensitiveDataFilter]\(/reference/observability/tracing/processors/sensitive-data-filter) is auto-applied to every configured instance. Defaults to \`true\`. Pass \`false\` to opt out, or pass a \`SensitiveDataFilterOptions\` object to customize fields, redaction token, or redaction style. If a config already includes a \`SensitiveDataFilter\` in \`spanOutputProcessors\`, it is not duplicated. Pre-instantiated instances are not modified.
+
 ## `ObservabilityInstanceConfig`
 
 ```typescript
@@ -201,8 +204,8 @@ Shuts down all observability instances and clears the registry.
 
 ### Exporters
 
-- [DefaultExporter](https://mastra.ai/reference/observability/tracing/exporters/default-exporter): Storage configuration
-- [CloudExporter](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter): Cloud setup
+- [MastraStorageExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter): Persists observability events to Mastra Storage
+- [MastraPlatformExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter): Sends observability events to Mastra Platform
 - [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust): Braintrust integration
 - [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse): Langfuse integration
 - [LangSmith](https://mastra.ai/reference/observability/tracing/exporters/langsmith): LangSmith integration

package/.docs/reference/observability/tracing/exporters/arize.md

@@ -77,7 +77,7 @@ Flushes pending data and shuts down the client.
 ```typescript
 import { ArizeExporter } from '@mastra/arize'
 
-// For Phoenix: Set PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
+// For Phoenix: Set PHOENIX_COLLECTOR_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
 // For Arize AX: Set ARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME
 const exporter = new ArizeExporter()
 ```

package/.docs/reference/observability/tracing/exporters/braintrust.md

@@ -15,6 +15,8 @@ interface BraintrustExporterConfig extends BaseExporterConfig {
   apiKey?: string
   endpoint?: string
   projectName?: string
+  braintrustLogger?: Logger<true>
+  currentSpan?: () => Span | undefined
   tuningParameters?: Record<string, any>
 }
 ```

package/.docs/reference/observability/tracing/exporters/cloud-exporter.md

@@ -1,6 +1,8 @@
 # CloudExporter
 
-**Added in:** `@mastra/observability@1.8.0`
+**Added in:** `@mastra/observability@1.8.0`. **Deprecated in `1.12.0`** in favor of [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter).
+
+> **Deprecated:** `CloudExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for new projects. The two classes share the same constructor, environment variables, and runtime behavior; `CloudExporter` keeps its original `mastra-cloud-observability-exporter` exporter `name` and `CLOUD_EXPORTER_*` error IDs so monitoring rules built against it keep working.
 
 Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.
 

package/.docs/reference/observability/tracing/exporters/console-exporter.md

@@ -124,8 +124,8 @@ const exporterWithLogger = new ConsoleExporter({
 
 ### Other Exporters
 
-- [DefaultExporter](https://mastra.ai/reference/observability/tracing/exporters/default-exporter): Storage persistence
-- [CloudExporter](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter): Mastra platform
+- [MastraStorageExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter): Storage persistence
+- [MastraPlatformExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter): Mastra platform
 - [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse): Langfuse integration
 - [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust): Braintrust integration
 

package/.docs/reference/observability/tracing/exporters/default-exporter.md

@@ -1,6 +1,10 @@
 # DefaultExporter
 
-Persists traces to Mastra's configured storage with automatic batching and retry logic.
+**Deprecated in `@mastra/observability@1.12.0`** in favor of [`MastraStorageExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter).
+
+> **Deprecated:** `DefaultExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraStorageExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter) for new projects. The two classes share the same constructor, configuration, and runtime behavior; `DefaultExporter` keeps its original `mastra-default-observability-exporter` exporter `name` so monitoring rules built against it keep working.
+
+Persists observability events to Mastra Storage with automatic batching and retry logic.
 
 ## Constructor
 
@@ -128,6 +132,8 @@ Failed flushes are retried with exponential backoff:
 - Maximum attempts: `maxRetries`
 - Batch is dropped after all retries fail
 
+When storage does not support a signal or retries are exhausted, `DefaultExporter` emits an `ObservabilityDropEvent` through `onDroppedEvent` handlers registered on exporters and bridges. The drop event includes the signal, reason, count, exporter name, storage name when known, and sanitized error details.
+
 ### Out-of-Order Handling
 
 For `batch-with-updates` strategy:

package/.docs/reference/observability/tracing/exporters/mastra-platform-exporter.md

@@ -0,0 +1,263 @@
+# MastraPlatformExporter
+
+**Added in:** `@mastra/observability@1.12.0`. Earlier releases (`@mastra/observability@1.8.0` through `1.11.x`) export the same exporter as the deprecated `CloudExporter`.
+
+Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.
+
+> **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` class is still exported from `@mastra/observability` so existing imports keep working, but it is deprecated and will be removed in a future major version. New code should use `MastraPlatformExporter`.
+
+## Constructor
+
+```typescript
+new MastraPlatformExporter(config?: MastraPlatformExporterConfig)
+```
+
+## `MastraPlatformExporterConfig`
+
+```typescript
+interface MastraPlatformExporterConfig extends BaseExporterConfig {
+  /** Maximum number of buffered events per batch (spans, logs, metrics, scores, feedback). Default: 1000 */
+  maxBatchSize?: number
+
+  /** Maximum wait time before flushing in milliseconds. Default: 5000 */
+  maxBatchWaitMs?: number
+
+  /** Maximum retry attempts. Default: 3 */
+  maxRetries?: number
+
+  /** Mastra Observability access token (from env or config) */
+  accessToken?: string
+
+  /** Project ID for project-scoped collector routes (letters, numbers, hyphens, underscores) */
+  projectId?: string
+
+  /** Base observability endpoint */
+  endpoint?: string
+
+  /** Explicit traces endpoint override */
+  tracesEndpoint?: string
+
+  /** Explicit logs endpoint override */
+  logsEndpoint?: string
+
+  /** Explicit metrics endpoint override */
+  metricsEndpoint?: string
+
+  /** Explicit scores endpoint override */
+  scoresEndpoint?: string
+
+  /** Explicit feedback endpoint override */
+  feedbackEndpoint?: string
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+## Environment variables
+
+The exporter reads these environment variables if not provided in config:
+
+- `MASTRA_CLOUD_ACCESS_TOKEN` - Authentication token for `MastraPlatformExporter` requests
+- `MASTRA_PROJECT_ID` - Project ID to use when deriving project-scoped collector routes such as `/projects/:projectId/ai/spans/publish`
+- `MASTRA_CLOUD_TRACES_ENDPOINT` - Traces endpoint override. Pass either a base origin or a full traces publish URL. Defaults to `https://observability.mastra.ai` in `@mastra/observability@1.9.2` and later
+
+## Properties
+
+```typescript
+readonly name = 'mastra-platform-exporter';
+```
+
+The deprecated `CloudExporter` class continues to use `'mastra-cloud-observability-exporter'` as its `name` for backward compatibility.
+
+## Methods
+
+### `exportTracingEvent`
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Processes tracing events for export to the Mastra platform.
+
+Only `SPAN_ENDED` tracing events are exported. `SPAN_STARTED` and `SPAN_UPDATED` are ignored. Matching spans are buffered and uploaded to the traces endpoint on the next flush.
+
+**Returns:** `Promise<void>` after the tracing event has been accepted for buffering or ignored.
+
+### `onLogEvent`
+
+```typescript
+async onLogEvent(event: LogEvent): Promise<void>
+```
+
+Processes log signals for export.
+
+Every `LogEvent` passed to this handler is buffered and exported to the logs endpoint derived from the configured base endpoint. Unlike tracing, there is no additional event-status filtering at the `MastraPlatformExporter` level. If the exporter is disabled, this method becomes a no-op.
+
+**Returns:** `Promise<void>` after the log event has been accepted for buffering.
+
+### `onMetricEvent`
+
+```typescript
+async onMetricEvent(event: MetricEvent): Promise<void>
+```
+
+Processes metric signals for export.
+
+Every `MetricEvent` passed to this handler is buffered and exported to the metrics endpoint derived from the configured base endpoint. There is no additional filtering by metric subtype or status inside `MastraPlatformExporter`; the exporter forwards every metric event it receives unless it is disabled.
+
+**Returns:** `Promise<void>` after the metric event has been accepted for buffering.
+
+### `onScoreEvent`
+
+```typescript
+async onScoreEvent(event: ScoreEvent): Promise<void>
+```
+
+Processes score signals for export.
+
+Every `ScoreEvent` passed to this handler is buffered and exported to the scores endpoint derived from the configured base endpoint. There is no extra filtering at the exporter layer beyond the disabled-exporter check, so all score events received by this method are forwarded.
+
+**Returns:** `Promise<void>` after the score event has been accepted for buffering.
+
+### `onFeedbackEvent`
+
+```typescript
+async onFeedbackEvent(event: FeedbackEvent): Promise<void>
+```
+
+Processes feedback signals for export.
+
+Every `FeedbackEvent` passed to this handler is buffered and exported to the feedback endpoint derived from the configured base endpoint. There is no feedback-type filtering inside `MastraPlatformExporter`; all feedback events received here are forwarded unless the exporter is disabled.
+
+**Returns:** `Promise<void>` after the feedback event has been accepted for buffering.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered events to the Mastra platform without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes remaining events and performs cleanup.
+
+## Behavior
+
+### Authentication
+
+If no access token is provided via config or environment variable, the exporter:
+
+- Logs a warning with sign-up information
+- Operates as a no-op (discards all events)
+
+### Batching
+
+The exporter batches tracing spans, logs, metrics, scores, and feedback for efficient network usage:
+
+- Flushes when total buffered event count reaches `maxBatchSize`
+- Flushes when `maxBatchWaitMs` elapsed since the first buffered signal in the batch
+- Flushes on `shutdown()`
+
+### Error handling
+
+- Uses exponential backoff retry with `maxRetries` attempts
+- Drops batches after all retries fail
+- Logs errors but continues processing new events
+
+Errors raised by `MastraPlatformExporter` use the `MASTRA_PLATFORM_EXPORTER_*` `id` prefix. The deprecated `CloudExporter` continues to emit `CLOUD_EXPORTER_*` `id`s.
+
+### Endpoint routing
+
+- Base origins derive signal endpoints automatically
+- Without `projectId`, derived routes use `/ai/{signal}/publish`
+- With `projectId` or `MASTRA_PROJECT_ID`, derived routes use `/projects/:projectId/ai/{signal}/publish`
+- Explicit full publish URLs are used as-is, even when `projectId` is configured
+
+### Signal Processing
+
+- `exportTracingEvent()` only exports `SPAN_ENDED` tracing events
+- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for their respective signal type
+- All supported signal batches are uploaded to their matching publish endpoints during `flush()` and `shutdown()`
+
+## Span wire format
+
+The shape of each span sent to Mastra Platform is documented here for reference only — it is not exported from `@mastra/observability` and should not be imported. The exporter spreads the original `AnyExportedSpan` (so the source field names are preserved) and layers a small set of platform-friendly aliases on top:
+
+```typescript
+type MastraPlatformSpanRecord = AnyExportedSpan & {
+  // Aliases derived from the source span
+  spanId: string // alias for span.id
+  spanType: string // alias for span.type
+  startedAt: Date // alias for span.startTime
+  endedAt: Date | null // alias for span.endTime ?? null
+  error: AnyExportedSpan['errorInfo'] | null
+
+  // Stamped at export time
+  createdAt: Date
+  updatedAt: Date | null
+}
+```
+
+The spread `AnyExportedSpan` also carries the original `id`, `type`, `name`, `traceId`, `parentSpanId`, `isRootSpan`, `isEvent`, `startTime`, `endTime`, `entityType`, `entityId`, `entityName`, `tags`, `attributes`, `metadata`, `input`, `output`, and `errorInfo`. See [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces) for `AnyExportedSpan`.
+
+## Usage
+
+```typescript
+import { MastraPlatformExporter } from '@mastra/observability'
+
+// Uses environment variable for token
+const exporter = new MastraPlatformExporter()
+
+// Explicit configuration
+const customExporter = new MastraPlatformExporter({
+  accessToken: 'your-token',
+  projectId: 'project_123',
+  maxBatchSize: 500,
+  maxBatchWaitMs: 2000,
+  logLevel: 'debug',
+})
+```
+
+## Migrating from `CloudExporter`
+
+The two classes share the same constructor signature, environment variables, and behavior. To migrate, replace the import and constructor:
+
+```typescript
+// Before
+import { CloudExporter } from '@mastra/observability'
+const exporter = new CloudExporter()
+
+// After
+import { MastraPlatformExporter } from '@mastra/observability'
+const exporter = new MastraPlatformExporter()
+```
+
+The original `CloudExporter` is preserved unchanged so dashboards or alert rules that match the previous `CLOUD_EXPORTER_*` error IDs or `mastra-cloud-observability-exporter` exporter name keep working until you migrate.
+
+## See also
+
+### Documentation
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): Complete guide
+- [Exporters](https://mastra.ai/docs/observability/tracing/overview): Exporter concepts
+
+### Other Exporters
+
+- [MastraStorageExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter): Storage persistence
+- [ConsoleExporter](https://mastra.ai/reference/observability/tracing/exporters/console-exporter): Debug output
+- [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse): Langfuse integration
+- [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust): Braintrust integration
+
+### Reference
+
+- [Configuration](https://mastra.ai/reference/observability/tracing/configuration): Configuration options
+- [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces): Type definitions

package/.docs/reference/observability/tracing/exporters/mastra-storage-exporter.md

@@ -0,0 +1,194 @@
+# MastraStorageExporter
+
+Persists traces to Mastra's configured storage with automatic batching and retry logic.
+
+> **Note:** `MastraStorageExporter` was previously called `DefaultExporter`. The original `DefaultExporter` class is still exported from `@mastra/observability` so existing imports keep working, but it is deprecated and will be removed in a future major version. New code should use `MastraStorageExporter`.
+
+## Constructor
+
+```typescript
+new MastraStorageExporter(config?: MastraStorageExporterConfig)
+```
+
+## `MastraStorageExporterConfig`
+
+```typescript
+interface MastraStorageExporterConfig extends BaseExporterConfig {
+  /** Maximum number of spans per batch. Default: 1000 */
+  maxBatchSize?: number
+
+  /** Maximum total buffer size before emergency flush. Default: 10000 */
+  maxBufferSize?: number
+
+  /** Maximum time to wait before flushing batch in milliseconds. Default: 5000 */
+  maxBatchWaitMs?: number
+
+  /** Maximum number of retry attempts. Default: 4 */
+  maxRetries?: number
+
+  /** Base retry delay in milliseconds (uses exponential backoff). Default: 500 */
+  retryDelayMs?: number
+
+  /** Tracing storage strategy or 'auto' for automatic selection. Default: 'auto' */
+  strategy?: TracingStorageStrategy | 'auto'
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+## `TracingStorageStrategy`
+
+```typescript
+type TracingStorageStrategy = 'realtime' | 'batch-with-updates' | 'insert-only'
+```
+
+### Strategy Behaviors
+
+- **realtime**: Immediately persists each event to storage
+- **batch-with-updates**: Batches creates and updates separately, applies in order
+- **insert-only**: Only processes SPAN\_ENDED events, ignores updates
+
+## Properties
+
+```typescript
+readonly name = 'mastra-storage-exporter';
+```
+
+The deprecated `DefaultExporter` class continues to use `'mastra-default-observability-exporter'` as its `name` for backward compatibility.
+
+## Methods
+
+### init
+
+```typescript
+init(options: InitExporterOptions): void
+```
+
+Initializes the exporter after dependencies are ready. Resolves tracing strategy based on storage capabilities.
+
+### `exportTracingEvent`
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Processes a tracing event according to the resolved strategy.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered events to storage without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes remaining buffered events and performs cleanup.
+
+## Automatic strategy selection
+
+When `strategy: 'auto'` (default), the exporter queries the storage adapter for its capabilities:
+
+```typescript
+interface TracingStrategy {
+  /** Strategies supported by this adapter */
+  supported: TracingStorageStrategy[]
+
+  /** Preferred strategy for optimal performance */
+  preferred: TracingStorageStrategy
+}
+```
+
+The exporter will:
+
+1. Use the storage adapter's preferred strategy if available
+2. Fall back to the first supported strategy if preferred isn't available
+3. Log a warning if a user-specified strategy isn't supported
+
+## Batching behavior
+
+### Flush Triggers
+
+The buffer flushes when any of these conditions are met:
+
+- Buffer size reaches `maxBatchSize`
+- Time since first buffered event exceeds `maxBatchWaitMs`
+- Buffer size reaches `maxBufferSize` (emergency flush)
+- `shutdown()` is called
+
+### Retry Logic
+
+Failed flushes are retried with exponential backoff:
+
+- Retry delay: `retryDelayMs * 2^attempt`
+- Maximum attempts: `maxRetries`
+- Batch is dropped after all retries fail
+
+### Out-of-Order Handling
+
+For `batch-with-updates` strategy:
+
+- Tracks which spans have been created
+- Rejects updates/ends for spans not yet created
+- Logs warnings for out-of-order events
+- Maintains sequence numbers for ordered updates
+
+## Usage
+
+```typescript
+import { MastraStorageExporter } from '@mastra/observability'
+
+// Default configuration
+const exporter = new MastraStorageExporter()
+
+// Custom batching configuration
+const customExporter = new MastraStorageExporter({
+  maxBatchSize: 500,
+  maxBatchWaitMs: 2000,
+  strategy: 'batch-with-updates',
+  logLevel: 'debug',
+})
+```
+
+## Migrating from `DefaultExporter`
+
+The two classes share the same constructor signature and behavior. To migrate, replace the import and constructor:
+
+```typescript
+// Before
+import { DefaultExporter } from '@mastra/observability'
+const exporter = new DefaultExporter()
+
+// After
+import { MastraStorageExporter } from '@mastra/observability'
+const exporter = new MastraStorageExporter()
+```
+
+The original `DefaultExporter` is preserved unchanged so dashboards or alert rules that match the previous `mastra-default-observability-exporter` exporter name keep working until you migrate.
+
+## See also
+
+### Documentation
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): Complete guide
+- [Exporters](https://mastra.ai/docs/observability/tracing/overview): Exporter concepts
+
+### Other Exporters
+
+- [MastraPlatformExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter): Mastra platform
+- [ConsoleExporter](https://mastra.ai/reference/observability/tracing/exporters/console-exporter): Debug output
+- [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse): Langfuse integration
+- [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust): Braintrust integration
+
+### Reference
+
+- [Configuration](https://mastra.ai/reference/observability/tracing/configuration): Configuration options
+- [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces): Type definitions