@mastra/mcp-docs-server 1.1.45 → 1.1.46-alpha.0

package/.docs/docs/observability/config.md

@@ -0,0 +1,139 @@
+# Configuration
+
+Observability is configured once on your Mastra instance and applies across traces, logs, and metrics.
+
+## When to use configuration
+
+- Set up a default observability pipeline for local development.
+- Route different environments or request types to different observability configs.
+- Keep Mastra Studio and Mastra platform access enabled while also sending data to external providers.
+
+## Quickstart
+
+The following example demonstrates the standard starter setup: composite storage with DuckDB for the observability domain, plus Mastra storage, Mastra platform, and sensitive-data redaction.
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { DuckDBStore } from '@mastra/duckdb'
+import { LibSQLStore } from '@mastra/libsql'
+import {
+  Observability,
+  MastraStorageExporter,
+  MastraPlatformExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability'
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite-storage',
+    default: new LibSQLStore({
+      id: 'mastra-storage',
+      url: 'file:./mastra.db',
+    }),
+    domains: {
+      observability: await new DuckDBStore().getStore('observability'),
+    },
+  }),
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
+        spanOutputProcessors: [new SensitiveDataFilter()],
+        logging: {
+          enabled: true,
+          level: 'info',
+        },
+      },
+    },
+  }),
+})
+```
+
+## Basic config
+
+An observability config usually contains:
+
+- `serviceName`: The service identifier attached to exported observability data.
+- `exporters`: One or more destinations for traces, logs, and derived metrics.
+- `spanOutputProcessors`: Transformations that run before spans are exported.
+- `logging`: Log forwarding settings for observability storage.
+
+For destinations and processors, see [Integrations overview](https://mastra.ai/docs/observability/integrations/overview).
+
+## Maintaining Studio access
+
+When you add external exporters, keep `MastraStorageExporter` for Studio observability and/or `MastraPlatformExporter` for hosted Mastra platform observability.
+
+This example shows only the observability config. Configure storage separately.
+
+```ts
+import { Observability, MastraStorageExporter, MastraPlatformExporter } from '@mastra/observability'
+import { ArizeExporter } from '@mastra/arize'
+
+export const observability = new Observability({
+  configs: {
+    production: {
+      serviceName: 'my-service',
+      exporters: [
+        new ArizeExporter({
+          endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT,
+          apiKey: process.env.PHOENIX_API_KEY,
+        }),
+        new MastraStorageExporter(),
+        new MastraPlatformExporter(),
+      ],
+    },
+  },
+})
+```
+
+## Flushing in serverless environments
+
+In serverless environments, flush observability exporters before the runtime pauses or exits:
+
+```ts
+const observability = mastra.getObservability()
+await observability.flush()
+```
+
+Use external storage in serverless environments instead of local file storage. For storage selection and routing, see [Storage](https://mastra.ai/docs/observability/storage).
+
+## Multi-config setup
+
+Use multiple configs when different environments or request types need different exporters or sampling behavior. Select the active config at runtime with `configSelector`.
+
+```ts
+import { Mastra } from '@mastra/core'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
+import { LangfuseExporter } from '@mastra/langfuse'
+
+const storageExporter = new MastraStorageExporter()
+const langfuseExporter = new LangfuseExporter()
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      development: {
+        serviceName: 'my-service-dev',
+        exporters: [storageExporter],
+      },
+      production: {
+        serviceName: 'my-service-prod',
+        exporters: [storageExporter, langfuseExporter],
+      },
+    },
+    configSelector: () => process.env.NODE_ENV || 'development',
+  }),
+})
+```
+
+For trace sampling, see [Tracing](https://mastra.ai/docs/observability/tracing/overview).
+
+## Related
+
+- [Observability overview](https://mastra.ai/docs/observability/overview)
+- [Storage](https://mastra.ai/docs/observability/storage)
+- [Tracing](https://mastra.ai/docs/observability/tracing/overview)
+- [Integrations overview](https://mastra.ai/docs/observability/integrations/overview)

package/.docs/docs/observability/{tracing → integrations}/bridges/datadog.md

@@ -4,7 +4,7 @@
 
 The Datadog Bridge enables bidirectional integration between Mastra's tracing system and Datadog. Unlike exporters that send trace data after execution completes, the bridge creates native dd-trace spans in real time so that auto-instrumented APM operations (HTTP calls, database queries, etc.) inside your tools and processors are correctly nested under their parent Mastra spans.
 
-> **Not using dd-trace APM?:** If you only need to send LLM Observability data and don't use `dd-trace` APM auto-instrumentation, the [Datadog Exporter](https://mastra.ai/docs/observability/tracing/exporters/datadog) is simpler — it supports agentless mode and sends spans directly to Datadog without a local agent.
+> **Not using dd-trace APM?:** If you only need to send LLM Observability data and don't use `dd-trace` APM auto-instrumentation, the [Datadog Exporter](https://mastra.ai/docs/observability/integrations/exporters/datadog) is simpler — it supports agentless mode and sends spans directly to Datadog without a local agent.
 
 ## When to use the bridge
 
@@ -30,7 +30,7 @@ The DatadogBridge participates in two parts of the dd-trace pipeline:
 
 - Emits annotations (model info, token usage, input/output, errors) through `dd-trace`'s LLM Observability pipeline
 - Maintains parent-child relationships in Datadog LLM Observability using nested `llmobs.trace()` calls
-- Reuses the same data shape and span-kind mapping as the [Datadog Exporter](https://mastra.ai/docs/observability/tracing/exporters/datadog)
+- Reuses the same data shape and span-kind mapping as the [Datadog Exporter](https://mastra.ai/docs/observability/integrations/exporters/datadog)
 
 ## Why this matters
 
@@ -64,7 +64,7 @@ yarn add @mastra/datadog dd-trace
 bun add @mastra/datadog dd-trace
 ```
 
-The bridge requires `dd-trace` to be installed and a local Datadog Agent (or compatible OTLP receiver) to receive APM data. See the [APM prerequisites](https://mastra.ai/docs/observability/tracing/exporters/datadog) on the exporter page for agent setup details.
+The bridge requires `dd-trace` to be installed and a local Datadog Agent (or compatible OTLP receiver) to receive APM data. See the [APM prerequisites](https://mastra.ai/docs/observability/integrations/exporters/datadog) on the exporter page for agent setup details.
 
 ## Configuration
 
@@ -148,7 +148,7 @@ new DatadogBridge({
 })
 ```
 
-> **Note:** For most bridge users, agent mode is the right choice. APM data cannot be sent in agentless mode, so enabling agentless splits LLM Observability traffic away from APM traffic. If you want LLM Observability only without an agent, use the [Datadog Exporter](https://mastra.ai/docs/observability/tracing/exporters/datadog) instead.
+> **Note:** For most bridge users, agent mode is the right choice. APM data cannot be sent in agentless mode, so enabling agentless splits LLM Observability traffic away from APM traffic. If you want LLM Observability only without an agent, use the [Datadog Exporter](https://mastra.ai/docs/observability/integrations/exporters/datadog) instead.
 
 ## Trace hierarchy
 
@@ -168,7 +168,7 @@ In Datadog, the APM trace shows this full topology, and the LLM Observability pr
 
 ## Span type mapping
 
-The bridge uses the same span-kind mapping as the Datadog Exporter for LLM Observability. See [span type mapping](https://mastra.ai/docs/observability/tracing/exporters/datadog) on the exporter page.
+The bridge uses the same span-kind mapping as the Datadog Exporter for LLM Observability. See [span type mapping](https://mastra.ai/docs/observability/integrations/exporters/datadog) on the exporter page.
 
 ## Using tags
 
@@ -206,12 +206,12 @@ If APM spans aren't connecting to Mastra spans as expected:
 - Ensure the DatadogBridge is set as `bridge` (not as an entry in `exporters`) in your observability config
 - Confirm you haven't also added the `DatadogExporter` to `exporters` — using both will double-emit LLM Observability data
 
-For native-module compatibility issues with `dd-trace` and bundler externals, see the [Datadog exporter troubleshooting](https://mastra.ai/docs/observability/tracing/exporters/datadog) section.
+For native-module compatibility issues with `dd-trace` and bundler externals, see the [Datadog exporter troubleshooting](https://mastra.ai/docs/observability/integrations/exporters/datadog) section.
 
 ## Related
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [Datadog Exporter](https://mastra.ai/docs/observability/tracing/exporters/datadog) - LLM Observability only, no `dd-trace` APM
+- [Datadog Exporter](https://mastra.ai/docs/observability/integrations/exporters/datadog) - LLM Observability only, no `dd-trace` APM
 - [DatadogBridge Reference](https://mastra.ai/reference/observability/tracing/bridges/datadog) - API documentation
 - [Datadog APM documentation](https://docs.datadoghq.com/tracing/)
 - [Datadog LLM Observability documentation](https://docs.datadoghq.com/llm_observability/)

package/.docs/docs/observability/{tracing → integrations}/bridges/otel.md

@@ -4,7 +4,7 @@
 
 The OpenTelemetry (OTEL) Bridge enables bidirectional integration between Mastra's tracing system and existing OpenTelemetry infrastructure. Unlike exporters that send trace data to external platforms, the bridge creates native OTEL spans that participate in your distributed tracing context.
 
-> **Looking to send traces without existing OTEL infrastructure?:** If you don't have existing OpenTelemetry instrumentation, the [OpenTelemetry Exporter](https://mastra.ai/docs/observability/tracing/exporters/otel) may be simpler — it sends traces directly without requiring an OTEL SDK setup.
+> **Looking to send traces without existing OTEL infrastructure?:** If you don't have existing OpenTelemetry instrumentation, the [OpenTelemetry Exporter](https://mastra.ai/docs/observability/integrations/exporters/otel) may be simpler — it sends traces directly without requiring an OTEL SDK setup.
 
 ## When to use the bridge
 
@@ -167,7 +167,7 @@ tsx --import ./instrumentation.ts ./src/index.ts
 
 The OtelBridge exports Mastra spans using [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai). This includes standardized span names (`chat {model}`, `execute_tool {tool_name}`, etc.) and attributes (`gen_ai.usage.input_tokens`, `gen_ai.request.model`, etc.).
 
-For details on span naming and attributes, see the [OpenTelemetry Exporter semantic conventions](https://mastra.ai/docs/observability/tracing/exporters/otel).
+For details on span naming and attributes, see the [OpenTelemetry Exporter semantic conventions](https://mastra.ai/docs/observability/integrations/exporters/otel).
 
 ## Trace hierarchy
 
@@ -230,5 +230,5 @@ If traces aren't displaying or connecting as expected:
 ## Related
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [OpenTelemetry Exporter](https://mastra.ai/docs/observability/tracing/exporters/otel): For sending traces to OTEL backends
+- [OpenTelemetry Exporter](https://mastra.ai/docs/observability/integrations/exporters/otel): For sending traces to OTEL backends
 - [OtelBridge Reference](https://mastra.ai/reference/observability/tracing/bridges/otel): API documentation

package/.docs/docs/observability/{tracing → integrations}/exporters/datadog.md

@@ -2,7 +2,7 @@
 
 [Datadog](https://datadoghq.com/) is a comprehensive monitoring platform with dedicated LLM Observability features. The Datadog exporter sends your traces to Datadog's LLM Observability product, providing insights into model performance, token usage, and conversation flows.
 
-> **Also using dd-trace APM?:** If you also use `dd-trace` APM auto-instrumentation, consider the [Datadog Bridge](https://mastra.ai/docs/observability/tracing/bridges/datadog) instead. The bridge creates `dd-trace` spans in real time so HTTP and database calls inside tools and processors are correctly nested under their parent Mastra span. The exporter on its own sends LLM Observability data after execution completes, which means auto-instrumented APM spans fall back to the request handler.
+> **Also using dd-trace APM?:** If you also use `dd-trace` APM auto-instrumentation, consider the [Datadog Bridge](https://mastra.ai/docs/observability/integrations/bridges/datadog) instead. The bridge creates `dd-trace` spans in real time so HTTP and database calls inside tools and processors are correctly nested under their parent Mastra span. The exporter on its own sends LLM Observability data after execution completes, which means auto-instrumented APM spans fall back to the request handler.
 
 ## Installation
 

package/.docs/docs/observability/{tracing → integrations}/exporters/mastra-platform.md

@@ -198,4 +198,4 @@ When you deploy with Mastra Studio, set **Deployment → Service Name** to a sta
 ## Related
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [MastraStorageExporter](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage)
+- [MastraStorageExporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage)

package/.docs/docs/observability/{tracing → integrations}/exporters/mastra-storage.md

@@ -239,6 +239,6 @@ new MastraStorageExporter({
 ## Related
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [MastraPlatformExporter](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform)
+- [MastraPlatformExporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-platform)
 - [Composite Storage](https://mastra.ai/reference/storage/composite): Combine multiple storage providers
 - [Storage Configuration](https://mastra.ai/docs/memory/storage)

package/.docs/docs/observability/{tracing → integrations}/exporters/otel.md

@@ -2,7 +2,7 @@
 
 The OpenTelemetry (OTEL) exporter sends your traces and logs to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, MLflow, Dash0, Traceloop, Laminar, and more.
 
-> **Looking for bidirectional OTEL integration?:** If you have existing OpenTelemetry instrumentation and want Mastra traces to inherit context from active OTEL spans, see the [OpenTelemetry Bridge](https://mastra.ai/docs/observability/tracing/bridges/otel) instead.
+> **Looking for bidirectional OTEL integration?:** If you have existing OpenTelemetry instrumentation and want Mastra traces to inherit context from active OTEL spans, see the [OpenTelemetry Bridge](https://mastra.ai/docs/observability/integrations/bridges/otel) instead.
 
 ## Installation
 
@@ -313,7 +313,7 @@ new OtelExporter({
 })
 ```
 
-> **Laminar-Native Exporter:** For Laminar-specific features like native span paths, metadata, and tags rendering in the Laminar dashboard, consider using the dedicated [`@mastra/laminar`](https://mastra.ai/docs/observability/tracing/exporters/laminar) exporter instead. It provides optimized integration with Laminar's platform.
+> **Laminar-Native Exporter:** For Laminar-specific features like native span paths, metadata, and tags rendering in the Laminar dashboard, consider using the dedicated [`@mastra/laminar`](https://mastra.ai/docs/observability/integrations/exporters/laminar) exporter instead. It provides optimized integration with Laminar's platform.
 
 ### Datadog
 
@@ -369,7 +369,7 @@ export const mastra = new Mastra({
 
 > **Warning:** The explicit imports of `@grpc/grpc-js` and `@opentelemetry/exporter-trace-otlp-grpc` at the top of the file, along with the [`bundler.externals`](https://mastra.ai/reference/configuration) configuration, are required for the gRPC transport to work correctly. Without these, you may encounter connection issues.
 
-> **Datadog-Native Exporter:** For Datadog-specific features like automatic span type mapping, LLM span categorization, and simplified setup without gRPC configuration, consider using the dedicated [`@mastra/datadog`](https://mastra.ai/docs/observability/tracing/exporters/datadog) exporter instead. It provides optimized integration with Datadog's APM platform.
+> **Datadog-Native Exporter:** For Datadog-specific features like automatic span type mapping, LLM span categorization, and simplified setup without gRPC configuration, consider using the dedicated [`@mastra/datadog`](https://mastra.ai/docs/observability/integrations/exporters/datadog) exporter instead. It provides optimized integration with Datadog's APM platform.
 
 ### Custom/Generic OTEL Endpoints
 
@@ -548,6 +548,6 @@ Install the suggested package for your provider.
 ## Related
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [OpenTelemetry Bridge](https://mastra.ai/docs/observability/tracing/bridges/otel)
+- [OpenTelemetry Bridge](https://mastra.ai/docs/observability/integrations/bridges/otel)
 - [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)
 - [OTEL Exporter Reference](https://mastra.ai/reference/observability/tracing/exporters/otel)

package/.docs/docs/observability/{tracing → integrations}/exporters/posthog.md

@@ -142,6 +142,22 @@ new PosthogExporter({
 })
 ```
 
+### Group analytics
+
+To attach events to a [PostHog group](https://posthog.com/docs/product-analytics/group-analytics), add a `$groups` object to `tracingOptions.metadata`. The exporter sends those values as the top-level `groups` field on the PostHog capture call, so you can slice analytics such as LLM cost by group.
+
+```ts
+await agent.generate(input, {
+  tracingOptions: {
+    metadata: {
+      $groups: {
+        publication: 'publication-1',
+      },
+    },
+  },
+})
+```
+
 ## Related
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)

package/.docs/docs/observability/integrations/overview.md

@@ -0,0 +1,45 @@
+# Integrations overview
+
+Mastra observability integrations control where observability data goes and how it is transformed on the way out. Use integrations to store data in Mastra storage, send it to Mastra platform, connect to external observability providers, or redact exported span data.
+
+## When to use integrations
+
+- Keep observability available in Studio with `MastraStorageExporter`.
+- Send hosted observability data to Mastra platform with `MastraPlatformExporter`.
+- Forward traces to external providers such as Datadog, Langfuse, or OpenTelemetry backends.
+- Redact sensitive values before they leave the runtime.
+
+## Choose an integration path
+
+- Studio workflow: Start with [Mastra Storage](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage).
+- Hosted Mastra workflow: Add [Mastra platform](https://mastra.ai/docs/observability/integrations/exporters/mastra-platform).
+- External observability stack: Choose one or more exporter pages under the sidebar `Exporters` section.
+- Existing distributed trace context: Use a bridge, then add exporters as needed.
+
+## Exporters
+
+Exporters send observability data to a destination:
+
+- [Mastra Storage](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage): Persist observability data for Studio.
+- [Mastra platform](https://mastra.ai/docs/observability/integrations/exporters/mastra-platform): Send hosted observability data to Mastra platform.
+- External providers: Use exporter pages for Datadog, Langfuse, OpenTelemetry, and other supported platforms.
+
+## Bridges
+
+Bridges connect Mastra to an existing distributed tracing context:
+
+- [OpenTelemetry bridge](https://mastra.ai/docs/observability/integrations/bridges/otel): Integrate Mastra with an existing OpenTelemetry trace.
+- [Datadog bridge](https://mastra.ai/docs/observability/integrations/bridges/datadog): Integrate Mastra with Datadog tracing and LLM Observability flows.
+
+## Processors
+
+Processors transform or redact spans before export:
+
+- [Sensitive Data Filter](https://mastra.ai/docs/observability/integrations/processors/sensitive-data-filter): Redact sensitive fields before spans leave the runtime.
+
+## Next steps
+
+- [Configuration](https://mastra.ai/docs/observability/config)
+- [Tracing](https://mastra.ai/docs/observability/tracing/overview)
+- [Mastra Storage](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage)
+- [OpenTelemetry bridge](https://mastra.ai/docs/observability/integrations/bridges/otel)

package/.docs/docs/observability/metrics/overview.md

@@ -114,4 +114,4 @@ Before storage, all metric labels pass through a cardinality filter that blocks
 - [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
 - [Studio observability](https://mastra.ai/docs/studio/observability)
 - [Observability overview](https://mastra.ai/docs/observability/overview)
-- [MastraStorageExporter reference](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage)
+- [MastraStorageExporter reference](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage)

package/.docs/docs/observability/metrics/querying.md

@@ -241,6 +241,24 @@ curl -sS -X POST http://localhost:4111/api/observability/metrics/aggregate \
   -d '{"name":["mastra_tool_duration_ms"],"aggregation":"avg","filters":{"entityName":"weatherTool","labels":{"status":"error"}}}'
 ```
 
+### Always provide a time range
+
+`filters.timestamp` is optional, but you should treat it as required for any query that runs against a production store. Observability tables are typically partitioned (or chunked, for TimescaleDB) by event time. When you supply `timestamp.start` (and ideally `end`), the backend can prune to the partitions that overlap the range — usually one or two. Without a time range, the planner has to scan every partition, which can be hundreds of segments over a year of retention and is the most common cause of slow OLAP queries on Postgres-backed stores.
+
+A safe default for ad-hoc queries is the last 24 hours; alerts and dashboards should match their actual evaluation window:
+
+```typescript
+await observability!.getMetricAggregate({
+  name: ['mastra_agent_duration_ms'],
+  aggregation: 'p95',
+  filters: {
+    timestamp: { start: new Date(Date.now() - 24 * 60 * 60 * 1000) },
+  },
+})
+```
+
+This guidance applies to all backends (ClickHouse, Postgres v-next, DuckDB), but matters most for Postgres v-next where each missing time bound translates directly into one extra partition scan.
+
 ## Example: build a custom KPI tile
 
 The following tool returns input-token volume and estimated cost for the last hour. An agent or a dashboard can call it as `structuredContent` without re-implementing the query.

package/.docs/docs/observability/overview.md

@@ -2,9 +2,12 @@
 
 Mastra's observability system gives you visibility into every agent run, workflow step, tool call, and model interaction. Agent behavior depends on model responses, prompts, tools, memory, and workflow state, so observability helps you inspect runtime decisions from day one. It captures three complementary signals that work together to help you understand what your application is doing and why.
 
+- [**Configuration**](https://mastra.ai/docs/observability/config): Configure observability once for traces, logs, and metrics.
+- [**Storage**](https://mastra.ai/docs/observability/storage): Choose storage backends for persisted traces, logs, and metrics aggregation.
 - [**Tracing**](https://mastra.ai/docs/observability/tracing/overview): Records every operation as a hierarchical timeline of spans, capturing inputs, outputs, token usage, and timing.
 - [**Logging**](https://mastra.ai/docs/observability/logging): Forwards structured log entries from your application and Mastra internals to observability storage, correlated to traces automatically.
 - [**Metrics**](https://mastra.ai/docs/observability/metrics/overview): Extracts duration, token usage, and cost data from traces automatically, with no additional instrumentation required.
+- [**Integrations**](https://mastra.ai/docs/observability/integrations/overview): Choose exporters, bridges, and span processors for Studio, hosted, or external observability workflows.
 
 ## When to use observability
 
@@ -94,7 +97,7 @@ export const mastra = new Mastra({
 })
 ```
 
-This enables tracing, log forwarding, and metrics. Mastra also supports external tracing providers like Langfuse, Datadog, and any OpenTelemetry-compatible platform. See [Tracing](https://mastra.ai/docs/observability/tracing/overview) for configuration details.
+This enables tracing, log forwarding, and metrics. Mastra also supports external tracing providers like Langfuse, Datadog, and any OpenTelemetry-compatible platform. Use [Configuration](https://mastra.ai/docs/observability/config), [Storage](https://mastra.ai/docs/observability/storage), and [Integrations overview](https://mastra.ai/docs/observability/integrations/overview) to set up observability.
 
 ## Mastra platform
 
@@ -102,15 +105,16 @@ For hosted traces, logs, and metrics across projects and deploys, see [Observabi
 
 ## Storage
 
-Not all storage backends support every signal. Traces and logs work with most backends, but metrics require an OLAP-capable store like DuckDB (development) or ClickHouse (production). For the full compatibility list, see [storage provider support](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage).
-
-For production environments with high traffic, use composite storage to route the observability domain to a dedicated backend. See [production recommendations](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) for details.
+Not all storage backends support every signal. Traces work with most backends, but metrics and logs require an OLAP-capable store like DuckDB (development) or ClickHouse (production). For setup guidance, see [Storage](https://mastra.ai/docs/observability/storage).
 
 ## Next steps
 
 - [Tracing](https://mastra.ai/docs/observability/tracing/overview)
 - [Logging](https://mastra.ai/docs/observability/logging)
 - [Metrics](https://mastra.ai/docs/observability/metrics/overview)
+- [Configuration](https://mastra.ai/docs/observability/config)
+- [Storage](https://mastra.ai/docs/observability/storage)
+- [Integrations overview](https://mastra.ai/docs/observability/integrations/overview)
 - [Mastra Studio](https://mastra.ai/docs/studio/observability)
 - [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics)
 - [Mastra platform observability](https://mastra.ai/docs/mastra-platform/observability)

package/.docs/docs/observability/storage.md

@@ -0,0 +1,79 @@
+# Storage
+
+Storage determines which observability signals persist, which queries are available, and whether metrics aggregation works. Use a dedicated observability store instead of your primary application store.
+
+## When to use storage
+
+- Keep traces, logs, and metrics available in Mastra Studio during development.
+- Enable metrics with an OLAP-capable observability store.
+- Route the observability domain to a dedicated production backend.
+
+## Quickstart
+
+The following example demonstrates the recommended local testing setup: route observability data to DuckDB while keeping the rest of your application on LibSQL.
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+import { LibSQLStore } from '@mastra/libsql'
+import { DuckDBStore } from '@mastra/duckdb'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite-storage',
+    default: new LibSQLStore({
+      id: 'mastra-storage',
+      url: 'file:./mastra.db',
+    }),
+    domains: {
+      observability: await new DuckDBStore().getStore('observability'),
+    },
+  }),
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [new MastraStorageExporter()],
+      },
+    },
+  }),
+})
+```
+
+## Signal support
+
+Mastra storage-backed observability currently depends on an OLAP-capable backend for full signal support:
+
+- DuckDB: Recommended for local testing and development.
+- ClickHouse: Recommended for production observability.
+- Mastra platform: Use `MastraPlatformExporter` if you want hosted observability without managing the backend yourself.
+
+Primary application stores such as LibSQL or PostgreSQL should not be used as the observability store. Route the `observability` domain separately with composite storage when you use `MastraStorageExporter`.
+
+## Local development
+
+For local development, the recommended setup is:
+
+- `LibSQLStore` for primary application storage
+- `DuckDBStore` for the `observability` domain
+- `MastraStorageExporter` for local Studio access
+
+This setup is for local testing and development. It gives you persisted traces, logs, and metrics without introducing external infrastructure.
+
+## Production deployment
+
+Observability traffic is usually more write-heavy than the rest of the application. In production:
+
+- Use `MastraStorageExporter` with ClickHouse for the `observability` domain when you keep observability in your own storage.
+- Use `MastraPlatformExporter` if you want hosted Mastra platform observability instead of managing the backend yourself.
+- Do not route observability to your primary application store.
+
+For backend compatibility details and exporter batching behavior, see [Mastra Storage exporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage).
+
+## Next steps
+
+- [Configuration](https://mastra.ai/docs/observability/config)
+- [Logging](https://mastra.ai/docs/observability/logging)
+- [Metrics overview](https://mastra.ai/docs/observability/metrics/overview)
+- [Mastra Storage exporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage)