@mastra/mcp-docs-server 1.1.35-alpha.2 → 1.1.35-alpha.21

package/.docs/reference/configuration.md

@@ -175,20 +175,20 @@ Custom ID generator function for creating unique identifiers. Mastra passes opti
 > **Warning:** This is used internally by Mastra for creating IDs for workflow runs, agent conversations, and other resources. Most users won't need to configure this option.
 
 ```typescript
+import { v4 as uuid } from '@lukeed/uuid'
 import { Mastra } from '@mastra/core'
-import { nanoid } from 'nanoid'
 
 export const mastra = new Mastra({
   idGenerator: context => {
     if (context?.idType === 'message' && context?.threadId) {
-      return `msg-${context.threadId}-${nanoid(8)}`
+      return `msg-${context.threadId}-${uuid()}`
     }
 
     if (context?.idType === 'run' && context?.source && context?.entityId) {
-      return `${context.source}-run-${context.entityId}-${nanoid(6)}`
+      return `${context.source}-run-${context.entityId}-${uuid()}`
     }
 
-    return nanoid()
+    return uuid()
   },
 })
 ```
@@ -277,7 +277,7 @@ Visit the [Observability documentation](https://mastra.ai/docs/observability/ove
 ```typescript
 import { Mastra } from '@mastra/core'
 import { LibSQLStore } from '@mastra/libsql'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 
 export const mastra = new Mastra({
   storage: new LibSQLStore({
@@ -288,7 +288,7 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'my-app',
-        exporters: [new DefaultExporter()],
+        exporters: [new MastraStorageExporter()],
       },
     },
   }),

package/.docs/reference/editor/tool-provider.md

@@ -14,7 +14,7 @@ Tool providers implement these methods:
 
 **getToolSchema(slug)** (`(slug: string) => Promise<JSONSchema>`): Returns the JSON schema for a specific tool identified by its slug.
 
-**resolveTools(slugs, options?)** (`(slugs: string[], options?) => Promise<Record<string, ToolAction>>`): Resolves tool slugs into executable Mastra tool actions. The options object can include userId for per-user authentication.
+**resolveTools(slugs, options?)** (`(slugs: string[], options?) => Promise<Record<string, ToolAction>>`): Resolves tool slugs into executable Mastra tool actions. Built-in providers use resourceId from request context for per-user authentication.
 
 ***
 
@@ -47,7 +47,7 @@ Composio tools use uppercase slug format: `GITHUB_CREATE_ISSUE`, `SLACK_SEND_MES
 
 ### Authentication
 
-Tool execution is scoped to a `userId` passed through request context. Each user authenticates with the integration separately through Composio's auth flow.
+Tool execution is scoped to the `resourceId` passed through request context. The provider maps that value to the user identity required by Composio's auth flow.
 
 ***
 
@@ -82,4 +82,4 @@ Arcade tools use `Toolkit.ToolName` format: `Github.GetRepository`, `Slack.SendM
 
 ### Authentication
 
-Like Composio, tool execution requires a `userId` for per-user authorization through Arcade's auth flow.
+Like Composio, tool execution uses `resourceId` from request context for per-user authorization. The provider maps that value to the user identity required by Arcade's auth flow.

package/.docs/reference/harness/harness-class.md

@@ -3,6 +3,8 @@
 **Added in:** `@mastra/core@1.5.0`
 
 > **Warning:** The `Harness` class is in alpha stage and subject to change. It won't follow semantic versioning guarantees until it graduates from experimental status. Use with caution and expect breaking changes in minor versions.
+>
+> [Mastra Code](https://code.mastra.ai/) is the flagship implementation of the `Harness` class, showcasing how it can be used to build a powerful terminal-based coding agent with multi-model support, persistent conversations, and built-in tools.
 
 The `Harness` class orchestrates multiple agent modes, shared state, memory, and storage. It provides a control layer that a TUI or other UI can drive to manage threads, switch models and modes, send messages, handle tool approvals, and track events.
 
@@ -96,7 +98,7 @@ await harness.sendMessage({ content: 'Hello!' })
 
 **omConfig** (`HarnessOMConfig`): Default configuration for observational memory (observer/reflector model IDs and thresholds).
 
-**disableBuiltinTools** (`BuiltinToolId[]`): Built-in harness tool IDs to remove from the \`harnessBuiltIn\` toolset. Valid values are \`ask\_user\`, \`submit\_plan\`, \`task\_write\`, \`task\_check\`, and \`subagent\`.
+**disableBuiltinTools** (`BuiltinToolId[]`): Built-in harness tool IDs to remove from the \`harnessBuiltIn\` toolset. Valid values are \`ask\_user\`, \`submit\_plan\`, \`task\_write\`, \`task\_update\`, \`task\_complete\`, \`task\_check\`, and \`subagent\`.
 
 **heartbeatHandlers** (`HeartbeatHandler[]`): Periodic background tasks started during \`init()\`. Use for gateway sync, cache refresh, and similar tasks.
 
@@ -160,6 +162,17 @@ Return the current `HarnessDisplayState` snapshot for UI rendering.
 const displayState = harness.getDisplayState()
 ```
 
+#### `restoreDisplayTasks(tasks)`
+
+Restore the task portion of `HarnessDisplayState` after a UI replays persisted task tool history. This emits `display_state_changed` without emitting a live `task_updated` event.
+
+If later task tools should read the replayed tasks, persist the same task list with `setState({ tasks })` before calling `restoreDisplayTasks(tasks)`.
+
+```typescript
+await harness.setState({ tasks: replayedTasks })
+harness.restoreDisplayTasks(replayedTasks)
+```
+
 #### `setState(updates)`
 
 Update the harness state. Validates against `stateSchema` if provided, and emits a `state_changed` event with the new state and changed keys.
@@ -829,13 +842,15 @@ The harness emits events through registered listeners. The following table lists
 
 The harness provides built-in tools to agents in every mode:
 
-| Tool          | Description                                                                                                                                                                                          |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ask_user`    | Ask the user a question and wait for their response. Supports free text, single-select choices, and multi-select choices.                                                                            |
-| `submit_plan` | Submit a plan for user review and approval.                                                                                                                                                          |
-| `task_write`  | Create or update a structured task list for tracking progress.                                                                                                                                       |
-| `task_check`  | Check the completion status of the current task list.                                                                                                                                                |
-| `subagent`    | Spawn a focused subagent with constrained tools (only available when `subagents` is configured). Pass `forked: true` to inherit the parent conversation — see [Forked subagents](#forked-subagents). |
+| Tool            | Description                                                                                                                                                                                          |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ask_user`      | Ask the user a question and wait for their response. Supports free text, single-select choices, and multi-select choices.                                                                            |
+| `submit_plan`   | Submit a plan for user review and approval.                                                                                                                                                          |
+| `task_write`    | Create or replace a structured task list for tracking progress. Assigns task IDs when omitted and returns the structured task list snapshot.                                                         |
+| `task_update`   | Update one tracked task by ID and return the structured task list snapshot.                                                                                                                          |
+| `task_complete` | Mark one tracked task completed by ID and return the structured task list snapshot.                                                                                                                  |
+| `task_check`    | Check the completion status of the current task list and return `tasks`, `summary`, `incompleteTasks`, and `isError` fields.                                                                         |
+| `subagent`      | Spawn a focused subagent with constrained tools (only available when `subagents` is configured). Pass `forked: true` to inherit the parent conversation — see [Forked subagents](#forked-subagents). |
 
 ### `ask_user` selections
 

package/.docs/reference/index.md

@@ -168,7 +168,9 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [PrefillErrorHandler](https://mastra.ai/reference/processors/prefill-error-handler)
 - [Processor Interface](https://mastra.ai/reference/processors/processor-interface)
 - [PromptInjectionDetector](https://mastra.ai/reference/processors/prompt-injection-detector)
+- [ProviderHistoryCompat](https://mastra.ai/reference/processors/provider-history-compat)
 - [RegexFilterProcessor](https://mastra.ai/reference/processors/regex-filter-processor)
+- [ResponseCache](https://mastra.ai/reference/processors/response-cache)
 - [SemanticRecall](https://mastra.ai/reference/processors/semantic-recall-processor)
 - [SkillSearchProcessor](https://mastra.ai/reference/processors/skill-search-processor)
 - [StreamErrorRetryProcessor](https://mastra.ai/reference/processors/stream-error-retry-processor)
@@ -277,6 +279,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Run Class](https://mastra.ai/reference/workflows/run)
 - [Step Class](https://mastra.ai/reference/workflows/step)
 - [Workflow Class](https://mastra.ai/reference/workflows/workflow)
+- [Workflow State Reader](https://mastra.ai/reference/workflows/workflow-state-reader)
 - [.branch()](https://mastra.ai/reference/workflows/workflow-methods/branch)
 - [.commit()](https://mastra.ai/reference/workflows/workflow-methods/commit)
 - [.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)

package/.docs/reference/memory/observational-memory.md

@@ -36,7 +36,9 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **scope** (`'resource' | 'thread'`): Memory scope for observations. \`'thread'\` keeps observations per-thread. \`'resource'\` (experimental) shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
 
-**activateAfterIdle** (`number | string`): Time before buffered observations or buffered reflections are forced to activate after inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like \`300\_000\`, \`"5m"\`, or \`"1hr"\`. When the gap between the current time and the last assistant message part timestamp exceeds this value, buffered observational memory activates before the next prompt. Useful for aligning with prompt cache TTLs.
+**activateAfterIdle** (`number | string | false`): Time before buffered observations are forced to activate after inactivity, even before \`observation.messageTokens\` is reached. Accepts a numeric millisecond value such as \`300\_000\`, duration strings like \`"5m"\` or \`"1hr"\`, or \`false\` to disable inherited observation idle activation. Reflections do not inherit this setting. Use \`reflection.activateAfterIdle\` to opt reflections into idle activation.
+
+**activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. Reflections do not inherit this setting. Use \`reflection.activateOnProviderChange\` to opt reflections into provider-change activation. (Default: `false`)
 
 **shareTokenBudget** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. \`shareTokenBudget\` is not yet compatible with async buffering. You must set \`observation: { bufferTokens: false }\` when using this option (this is a temporary limitation). (Default: `false`)
 
@@ -66,6 +68,10 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.bufferActivation** (`number`): Controls how much of the message window to retain after activation. Accepts a ratio (0-1) or an absolute token count (≥ 1000). For example, \`0.8\` means: activate enough buffers to remove 80% of \`messageTokens\` and leave 20% as active message history. An absolute token count like \`4000\` targets a goal of keeping \~4k message tokens remaining after activation. Higher values remove more message history per activation when using a ratio. Higher values keep more message history when using a token count.
 
+**observation.activateAfterIdle** (`number | string | false`): Time before buffered observations are forced to activate after inactivity. Accepts milliseconds, a duration string, or \`false\`. If unset, the top-level \`activateAfterIdle\` value is used for observations. Set \`false\` to disable the top-level idle setting for observations.
+
+**observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level \`activateOnProviderChange\` value is used for observations.
+
 **observation.blockAfter** (`number`): Token threshold above which synchronous (blocking) observation is forced. Between \`messageTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous observation runs as a last resort, while buffered activation still preserves a minimum remaining context (min(1000, retention floor)). Accepts a multiplier (1 < value < 2, multiplied by \`messageTokens\`) or an absolute token count (≥ 2, must be greater than \`messageTokens\`). Only relevant when \`bufferTokens\` is set. Defaults to \`1.2\` when async buffering is enabled.
 
 **observation.previousObserverTokens** (`number | false`): Optional token budget for the observer's previous-observations context. When set to a number, the observations passed to the Observer agent are tail-truncated to fit within this budget while keeping the newest observations and preserving highlighted 🔴 items when possible. When a buffered reflection is pending, the already-reflected observation lines are automatically replaced with the reflection summary before truncation. Set to \`0\` to omit previous observations entirely, or \`false\` to disable truncation explicitly.
@@ -86,6 +92,10 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **reflection.bufferActivation** (`number`): Ratio (0-1) controlling when async reflection buffering starts. When observation tokens reach \`observationTokens \* bufferActivation\`, reflection runs in the background. On activation at the full threshold, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range.
 
+**reflection.activateAfterIdle** (`number | string | false`): Time before buffered reflections are forced to activate after inactivity. Accepts milliseconds, a duration string, or \`false\`. Reflections do not inherit top-level \`activateAfterIdle\`; set this explicitly to opt reflections into idle activation.
+
+**reflection.activateOnProviderChange** (`boolean`): Force buffered reflections to activate when the actor provider or model changes. Reflections do not inherit top-level \`activateOnProviderChange\`; set this explicitly to opt reflections into provider-change activation.
+
 **reflection.blockAfter** (`number`): Token threshold above which synchronous (blocking) reflection is forced. Between \`observationTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous reflection runs as a last resort. Accepts a multiplier (1 < value < 2, multiplied by \`observationTokens\`) or an absolute token count (≥ 2, must be greater than \`observationTokens\`). Only relevant when \`bufferActivation\` is set. Defaults to \`1.2\` when async reflection is enabled.
 
 ### Token estimate metadata cache

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: