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

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

@@ -1,166 +1,29 @@
 # Tracing
 
-Tracing provides specialized monitoring and debugging for the AI-related operations in your application. When enabled, Mastra automatically creates traces for agent runs, LLM generations, tool calls, and workflow steps with AI-specific context and metadata.
+Tracing is the observability signal that records how a request moves through agents, workflows, tools, and model calls. Mastra represents each operation as a span and groups related spans into a trace so you can inspect the full execution path.
 
-Unlike traditional application tracing, Tracing focuses specifically on understanding your AI pipeline — capturing token usage, model parameters, tool execution details, and conversation flows. This makes it easier to debug issues, optimize performance, and understand how your AI systems behave in production.
+This page focuses on trace-specific concepts: span hierarchy, sampling, metadata, filtering, trace IDs, and third-party trace context.
 
-## How it works
+## When to use tracing
 
-Traces are created by:
+- Debug unexpected agent or workflow behavior by inspecting the full execution path.
+- Follow model calls, tool calls, and workflow steps inside a single request.
+- Attach trace-specific metadata and tags for filtering and investigation.
+- Connect Mastra traces to a third-party tracing system.
 
-- **Configure exporters** → send trace data to observability platforms
-- **Set sampling strategies** → control which traces are collected
-- **Run agents and workflows** → Mastra auto-instruments them with Tracing
+## Get started
 
-## Configuration
+To get started with tracing, configure observability in your Mastra instance and run an agent or workflow. You can configure behavior through the following features:
 
-### Basic Config
-
-```ts
-import { Mastra } from '@mastra/core'
-import { LibSQLStore } from '@mastra/libsql'
-import {
-  Observability,
-  MastraStorageExporter,
-  MastraPlatformExporter,
-  SensitiveDataFilter,
-} from '@mastra/observability'
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      default: {
-        serviceName: 'mastra',
-        exporters: [
-          new MastraStorageExporter(), // Persists observability events to Mastra Storage
-          new MastraPlatformExporter(), // Sends observability events to Mastra platform (if MASTRA_PLATFORM_ACCESS_TOKEN is set)
-        ],
-        spanOutputProcessors: [
-          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
-        ],
-      },
-    },
-  }),
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    url: 'file:./mastra.db', // Storage is required for tracing
-  }),
-})
-```
-
-This configuration includes:
-
-- **Service Name**: `"mastra"` - identifies your service in traces
-
-- **Sampling**: `"always"` by default (100% of traces)
-
-- **Exporters**:
-
-  - `MastraStorageExporter` - Persists observability events to Mastra Storage
-  - `MastraPlatformExporter` - Sends observability events to Mastra platform (requires `MASTRA_PLATFORM_ACCESS_TOKEN`)
-
-- **Span Output Processors**: `SensitiveDataFilter` - Redacts sensitive fields
-
-## Exporters
-
-Exporters determine where your trace data is sent and how it's stored. They integrate with your existing observability stack, support data residency requirements, and can be optimized for cost and performance. You can use multiple exporters simultaneously to send the same trace data to different destinations — for example, storing detailed traces locally for debugging while sending sampled data to a cloud provider for production monitoring.
-
-### Internal Exporters
-
-Mastra provides two built-in exporters:
-
-- **[Mastra Storage](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage)**: Persists observability events to Mastra Storage for viewing in Studio
-- **[Mastra platform](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform)**: Sends observability events to Mastra platform for production monitoring and collaboration
-
-### External Exporters
-
-In addition to the internal exporters, Mastra supports integration with popular observability platforms. These exporters allow you to leverage your existing monitoring infrastructure and take advantage of platform-specific features like alerting, dashboards, and correlation with other application metrics.
-
-- **[Arize](https://mastra.ai/docs/observability/tracing/exporters/arize)** - Exports traces to Arize Phoenix or Arize AX using OpenInference semantic conventions
-- **[Braintrust](https://mastra.ai/docs/observability/tracing/exporters/braintrust)** - Exports traces to Braintrust's eval and observability platform
-- **[Datadog](https://mastra.ai/docs/observability/tracing/exporters/datadog)** - Sends traces to Datadog APM via OTLP for full-stack observability with AI tracing
-- **[Laminar](https://mastra.ai/docs/observability/tracing/exporters/laminar)** - Sends traces to Laminar via OTLP/HTTP (protobuf) with Laminar-native span attributes + scorer support
-- **[Langfuse](https://mastra.ai/docs/observability/tracing/exporters/langfuse)** - Sends traces to the Langfuse open-source LLM engineering platform
-- **[LangSmith](https://mastra.ai/docs/observability/tracing/exporters/langsmith)** - Pushes traces into LangSmith's observability and evaluation toolkit
-- **[PostHog](https://mastra.ai/docs/observability/tracing/exporters/posthog)** - Sends traces to PostHog for AI analytics and product insights
-- **[Sentry](https://mastra.ai/docs/observability/tracing/exporters/sentry)** - Sends traces to Sentry for AI tracing and monitoring using OpenTelemetry semantic conventions
-- **[OpenTelemetry](https://mastra.ai/docs/observability/tracing/exporters/otel)** - Deliver traces to any OpenTelemetry-compatible observability system
-  - Supports: Dash0, MLflow, New Relic, SigNoz, Traceloop, Zipkin, and others!
-
-## Bridges
-
-Bridges provide bidirectional integration with external tracing systems. Unlike exporters that send trace data to external platforms, bridges create native spans in external systems and inherit context from them. This enables Mastra operations to participate in existing distributed traces.
-
-- **[OpenTelemetry Bridge](https://mastra.ai/docs/observability/tracing/bridges/otel)** - Integrate with existing OpenTelemetry infrastructure
-
-### Bridges vs Exporters
-
-| Feature                                  | Bridges                      | Exporters                 |
-| ---------------------------------------- | ---------------------------- | ------------------------- |
-| Creates native spans in external systems | Yes                          | No                        |
-| Inherits context from external systems   | Yes                          | No                        |
-| Sends data to backends                   | Via external SDK             | Directly                  |
-| Use case                                 | Existing distributed tracing | Standalone Mastra tracing |
-
-You can use both together — a bridge for context propagation and exporters to send traces to additional destinations.
+- [Configuration](https://mastra.ai/docs/observability/config): Base observability config, multiple configs, and serverless flushing
+- [Storage](https://mastra.ai/docs/observability/storage): Storage routing for traces, logs, and metrics
+- [Integrations overview](https://mastra.ai/docs/observability/integrations/overview): Exporters, bridges, and processors
 
 ## Sampling strategies
 
 Sampling allows you to control which traces are collected, helping you balance between observability needs and resource costs. In production environments with high traffic, collecting every trace can be expensive and unnecessary. Sampling strategies let you capture a representative subset of traces while ensuring you don't miss critical information about errors or important operations.
 
-Mastra supports four sampling strategies:
-
-### Always Sample
-
-Collects 100% of traces. Best for development, debugging, or low-traffic scenarios where you need complete visibility.
-
-```ts
-sampling: {
-  type: 'always'
-}
-```
-
-### Never Sample
-
-Disables tracing entirely. Useful for specific environments where tracing adds no value or when you need to temporarily disable tracing without removing configuration.
-
-```ts
-sampling: {
-  type: 'never'
-}
-```
-
-### Ratio-Based Sampling
-
-Randomly samples a percentage of traces. Ideal for production environments where you want statistical insights without the cost of full tracing. The probability value ranges from 0 (no traces) to 1 (all traces).
-
-```ts
-sampling: {
-  type: 'ratio',
-  probability: 0.1  // Sample 10% of traces
-}
-```
-
-### Custom Sampling
-
-Implements your own sampling logic based on request context, metadata, or business rules. Perfect for complex scenarios like sampling based on user tier, request type, or error conditions.
-
-```ts
-sampling: {
-  type: 'custom',
-  sampler: (options) => {
-    // Sample premium users at higher rate
-    if (options?.metadata?.userTier === 'premium') {
-      return Math.random() < 0.5; // 50% sampling
-    }
-
-    // Default 1% sampling for others
-    return Math.random() < 0.01;
-  }
-}
-```
-
-### Complete Example
+You can configure sampling at the observability config level:
 
 ```ts
 export const mastra = new Mastra({
@@ -180,139 +43,49 @@ export const mastra = new Mastra({
 })
 ```
 
-## Multi-config setup
-
-Complex applications often require different tracing configurations for different scenarios. You might want detailed traces with full sampling during development, sampled traces sent to external providers in production, and specialized configurations for specific features or customer segments. The `configSelector` function enables dynamic configuration selection at runtime, allowing you to route traces based on request context, environment variables, feature flags, or any custom logic.
-
-This approach is particularly valuable when:
-
-- Running A/B tests with different observability requirements
-- Providing enhanced debugging for specific customers or support cases
-- Gradually rolling out new tracing providers without affecting existing monitoring
-- Optimizing costs by using different sampling rates for different request types
-- Maintaining separate trace streams for compliance or data residency requirements
-
-> **Info:** Note that only a single config can be used for a specific execution. But a single config can send data to multiple exporters simultaneously.
-
-### Dynamic Configuration Selection
-
-Use `configSelector` to choose the appropriate tracing configuration based on request context:
-
-```ts
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      langfuse: {
-        serviceName: 'langfuse-service',
-        exporters: [langfuseExporter],
-      },
-      braintrust: {
-        serviceName: 'braintrust-service',
-        exporters: [braintrustExporter],
-      },
-      debug: {
-        serviceName: 'debug-service',
-        sampling: { type: 'always' },
-        exporters: [new MastraStorageExporter()],
-      },
-    },
-    configSelector: (context, availableTracers) => {
-      // Use debug config for support requests
-      if (context.requestContext?.get('supportMode')) {
-        return 'debug'
-      }
-
-      // Route specific customers to different providers
-      const customerId = context.requestContext?.get('customerId')
-      if (customerId && premiumCustomers.includes(customerId)) {
-        return 'braintrust'
-      }
-
-      // Route specific requests to langfuse
-      if (context.requestContext?.get('useExternalTracing')) {
-        return 'langfuse'
-      }
-
-      throw new Error('no config found')
-    },
-  }),
-})
-```
-
-### Environment-Based Configuration
+The `sampling` option allows you to control which traces are collected, helping you balance between observability needs and resource costs. Mastra supports four sampling strategies:
 
-A common pattern is to select configurations based on deployment environment:
+1. **Always Sample**: Collects 100% of traces. Best for development, debugging, or low-traffic scenarios where you need complete visibility.
 
-```ts
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      development: {
-        serviceName: 'my-service-dev',
-        sampling: { type: 'always' },
-        exporters: [new MastraStorageExporter()],
-      },
-      staging: {
-        serviceName: 'my-service-staging',
-        sampling: { type: 'ratio', probability: 0.5 },
-        exporters: [langfuseExporter],
-      },
-      production: {
-        serviceName: 'my-service-prod',
-        sampling: { type: 'ratio', probability: 0.01 },
-        exporters: [mastraObserveExporter, langfuseExporter],
-      },
-    },
-    configSelector: (context, availableTracers) => {
-      const env = process.env.NODE_ENV || 'development'
-      return env
-    },
-  }),
-})
-```
+   ```ts
+   sampling: {
+     type: 'always'
+   }
+   ```
 
-### Common Configuration Patterns & Troubleshooting
+2. **Never Sample**: Disables tracing entirely. Useful for specific environments where tracing adds no value or when you need to temporarily disable tracing without removing configuration.
 
-#### Maintaining Studio access
+   ```ts
+   sampling: {
+     type: 'never'
+   }
+   ```
 
-When adding external exporters, include `MastraStorageExporter` and `MastraPlatformExporter` to maintain access to Studio:
+3. **Ratio-Based Sampling**: Randomly samples a percentage of traces. Ideal for production environments where you want statistical insights without the cost of full tracing. The probability value ranges from 0 (no traces) to 1 (all traces).
 
-```ts
-import {
-  Observability,
-  MastraStorageExporter,
-  MastraPlatformExporter,
-  SensitiveDataFilter,
-} from '@mastra/observability'
-import { ArizeExporter } from '@mastra/arize'
+   ```ts
+   sampling: {
+     type: 'ratio',
+     probability: 0.1  // Sample 10% of traces
+   }
+   ```
 
-export const mastra = new Mastra({
-  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(), // Keep Studio access
-          new MastraPlatformExporter(), // Keep Cloud access
-        ],
-        spanOutputProcessors: [new SensitiveDataFilter()],
-      },
-    },
-  }),
-})
-```
-
-This configuration sends traces to all three destinations simultaneously:
+4. **Custom Sampling**: Implements your own sampling logic based on request context, metadata, or business rules. Perfect for complex scenarios like sampling based on user tier, request type, or error conditions.
 
-- **Arize Phoenix/AX** for external observability
-- **MastraStorageExporter** for Studio
-- **MastraPlatformExporter** for hosted Studio dashboard
+   ```ts
+   sampling: {
+     type: 'custom',
+     sampler: (options) => {
+       // Sample premium users at higher rate
+       if (options?.metadata?.userTier === 'premium') {
+         return Math.random() < 0.5; // 50% sampling
+       }
 
-> **Info:** Remember: A single trace can be sent to multiple exporters. You don't need separate configs for each exporter unless you want different sampling rates or processors.
+       // Default 1% sampling for others
+       return Math.random() < 0.01;
+     }
+   }
+   ```
 
 ## Adding custom metadata
 
@@ -362,13 +135,13 @@ export const mastra = new Mastra({
 
 If `environment` is not set, Mastra falls back to `process.env.NODE_ENV`. If neither is set, the field is left undefined rather than guessed.
 
-Per-call `tracingOptions.metadata.environment` always takes precedence, so individual calls can still override the value when needed.
+Per-call `tracingOptions.metadata.environment` always takes precedence, so individual calls can override the value when needed.
 
-### Automatic Metadata from `RequestContext`
+### Automatic metadata from `RequestContext`
 
 Instead of manually adding metadata to each span, you can configure Mastra to automatically extract values from RequestContext and attach them as metadata to all spans in a trace. This is useful for consistently tracking user identifiers, environment information, feature flags, or any request-scoped data across your entire trace.
 
-#### Configuration-Level Extraction
+#### Configuration-level extraction
 
 Define which RequestContext keys to extract in your tracing configuration. These keys will be automatically included as metadata for all spans created with this configuration:
 
@@ -400,7 +173,7 @@ const result = await agent.generate('Hello', {
 })
 ```
 
-#### Per-Request Additions
+#### Per-request additions
 
 You can add trace-specific keys using `tracingOptions.requestContextKeys`. These are merged with the configuration-level keys:
 
@@ -420,7 +193,7 @@ const result = await agent.generate('Hello', {
 // All spans now have: userId, environment, AND experimentId
 ```
 
-#### Nested Value Extraction
+#### Nested value extraction
 
 Use dot notation to extract nested values from RequestContext:
 
@@ -450,7 +223,7 @@ requestContext.set('session', { data: { experimentId: 'exp-999' } })
 3. **Child Span Extraction**: Child spans can also extract metadata if you pass `requestContext` when creating them
 4. **Metadata Precedence**: Explicit metadata passed to span options always takes precedence over extracted metadata
 
-### Adding Tags to Traces
+### Adding tags to traces
 
 Tags are string labels that help you categorize and filter traces. Unlike metadata (which contains structured key-value data), tags are plain strings designed for quick filtering and organization.
 
@@ -474,17 +247,17 @@ const result = await run.start({
 })
 ```
 
-#### How Tags Work
+#### How tags work
 
 - **Root span only**: Tags are applied only to the root span of a trace (the agent run or workflow run span)
 
 - **Widely supported**: Tags are supported by most exporters for filtering and searching traces:
 
-  - **Braintrust** - Native `tags` field
-  - **Langfuse** - Native `tags` field on traces
-  - **ArizeExporter** - `tag.tags` OpenInference attribute
-  - **OtelExporter** - `mastra.tags` span attribute
-  - **OtelBridge** - `mastra.tags` span attribute
+  - **Braintrust**: Native `tags` field
+  - **Langfuse**: Native `tags` field on traces
+  - **ArizeExporter**: `tag.tags` OpenInference attribute
+  - **OtelExporter**: `mastra.tags` span attribute
+  - **OtelBridge**: `mastra.tags` span attribute
 
 - **Combinable with metadata**: You can use both `tags` and `metadata` in the same `tracingOptions`
 
@@ -497,7 +270,7 @@ const result = await agent.generate([{ role: 'user', content: 'Analyze this' }],
 })
 ```
 
-#### Common Tag Patterns
+#### Common tag patterns
 
 - **Environment**: `"production"`, `"staging"`, `"development"`
 - **Feature flags**: `"feature-x-enabled"`, `"beta-user"`
@@ -505,7 +278,7 @@ const result = await agent.generate([{ role: 'user', content: 'Analyze this' }],
 - **Priority levels**: `"priority-high"`, `"priority-low"`
 - **Experiments**: `"experiment-v1"`, `"control-group"`, `"treatment-a"`
 
-### Hiding Sensitive Input/Output
+### Hiding sensitive input/output
 
 When processing sensitive data, you may want to prevent input and output values from being logged to your observability platforms. Use `hideInput` and `hideOutput` in `tracingOptions` to exclude this data from all spans in a trace:
 
@@ -536,7 +309,7 @@ const result = await agent.generate([{ role: 'user', content: 'Handle confidenti
 #### How it works
 
 - **Trace-wide effect**: When set on the root span, these options apply to all child spans in the trace (tool calls, model generations, etc.)
-- **Export-time filtering**: The data is still available internally during execution but is excluded when spans are exported to observability platforms
+- **Export-time filtering**: The data remains available internally during execution but is excluded when spans are exported to observability platforms
 - **Combinable with other options**: You can use `hideInput`/`hideOutput` alongside `tags`, `metadata`, and other `tracingOptions`
 
 ```ts
@@ -550,9 +323,9 @@ const result = await agent.generate([{ role: 'user', content: 'Sensitive operati
 })
 ```
 
-> **Tip:** For more granular control over sensitive data, consider using the [Sensitive Data Filter](https://mastra.ai/docs/observability/tracing/processors/sensitive-data-filter) processor, which can redact specific fields (like passwords, tokens, and keys) while preserving the rest of the input/output.
+> **Tip:** For more granular control over sensitive data, consider using the [Sensitive Data Filter](https://mastra.ai/docs/observability/integrations/processors/sensitive-data-filter) processor, which can redact specific fields (like passwords, tokens, and keys) while preserving the rest of the input/output.
 
-#### Child Spans and Metadata Extraction
+#### Child spans and metadata extraction
 
 When creating child spans within tools or workflow steps, you can pass the `requestContext` parameter to enable metadata extraction:
 
@@ -634,15 +407,15 @@ Mastra provides two ways to transform span data before it reaches your observabi
 
 Use **span processors** for synchronous transformations that should apply to all exporters (like redacting sensitive data). Use **custom span formatters** when different exporters need different representations of the same data (like plain text for one platform and structured data for another), or when you need to perform asynchronous operations like fetching data from external APIs.
 
-### Span Processors
+### Span processors
 
 Span processors transform, filter, or enrich trace data before it's exported. They act as a pipeline between span creation and export, enabling you to modify spans for security, compliance, or debugging purposes. Processors run once and affect all exporters.
 
-#### Built-in Processors
+#### Built-in processors
 
-- [Sensitive Data Filter](https://mastra.ai/docs/observability/tracing/processors/sensitive-data-filter) redacts sensitive information. It's enabled in the default observability config.
+- [Sensitive Data Filter](https://mastra.ai/docs/observability/integrations/processors/sensitive-data-filter) redacts sensitive information. It's enabled in the default observability config.
 
-#### Creating Custom Processors
+#### Creating custom processors
 
 You can create custom span processors by implementing the `SpanOutputProcessor` interface. Here's a basic example that converts all input text in spans to lowercase:
 
@@ -683,6 +456,8 @@ Processors are executed in the order they're defined, allowing you to chain mult
 - Normalizing data formats
 - Enriching spans with business context
 
+For the broader exporter, bridge, and processor model, see [Integrations overview](https://mastra.ai/docs/observability/integrations/overview).
+
 ## Span filtering
 
 Span filtering lets you reduce noise and per-span costs before data reaches your observability platform. Configure it per observability instance, so different exporters or environments can keep different levels of detail.
@@ -727,16 +502,16 @@ Filtering happens at export time in this order:
 
 If `spanFilter` throws, Mastra keeps the span and logs the error to avoid silent data loss. For the full span type list and more examples, see the [Span filtering reference](https://mastra.ai/reference/observability/tracing/span-filtering).
 
-### Custom Span Formatters
+### Custom span formatters
 
 Custom span formatters transform how spans appear in specific observability platforms. Unlike span processors, formatters are configured per-exporter, allowing different formatting for different destinations. Formatters support both synchronous and asynchronous operations.
 
 #### Use cases
 
-- **Extract plain text from AI SDK messages** - Convert structured message arrays to readable text
-- **Transform input/output formats** - Customize how data displays in specific platforms
-- **Platform-specific field mapping** - Add or remove fields based on platform requirements
-- **Async data enrichment** - Fetch additional context from external APIs or databases
+- **Extract plain text from AI SDK messages**: Convert structured message arrays to readable text
+- **Transform input/output formats**: Customize how data displays in specific platforms
+- **Platform-specific field mapping**: Add or remove fields based on platform requirements
+- **Async data enrichment**: Fetch additional context from external APIs or databases
 
 #### Configuration
 
@@ -779,7 +554,7 @@ export const mastra = new Mastra({
 })
 ```
 
-#### Chaining Multiple Formatters
+#### Chaining multiple formatters
 
 Use `chainFormatters` to combine multiple formatters. Chains support both sync and async formatters:
 
@@ -801,7 +576,7 @@ const exporter = new BraintrustExporter({
 })
 ```
 
-#### Async Formatters
+#### Async formatters
 
 Custom span formatters support asynchronous operations, enabling use cases like fetching data from external APIs or databases to enrich your spans:
 
@@ -888,7 +663,7 @@ export const mastra = new Mastra({
 })
 ```
 
-### Available Options
+### Available options
 
 | Option            | Default | Description                                                      |
 | ----------------- | ------- | ---------------------------------------------------------------- |
@@ -926,7 +701,7 @@ All options are optional — if not specified, they fall back to the defaults sh
 
 When you execute agents or workflows with tracing enabled, the response includes a `traceId` that you can use to look up the full trace in your observability platform. This is useful for debugging, customer support, or correlating traces with other events in your system.
 
-### Agent Trace IDs
+### Agent trace IDs
 
 Both `generate` and `stream` methods return the trace ID in their response:
 
@@ -942,7 +717,7 @@ const streamResult = await agent.stream('Tell me a story')
 console.log('Trace ID:', streamResult.traceId)
 ```
 
-### Workflow Trace IDs
+### Workflow trace IDs
 
 Workflow executions also return trace IDs:
 
@@ -967,7 +742,7 @@ const finalState = await getWorkflowState()
 console.log('Trace ID:', finalState.traceId)
 ```
 
-### Using Trace IDs
+### Using trace IDs
 
 Once you have a trace ID, you can:
 
@@ -982,7 +757,7 @@ The trace ID is only available when tracing is enabled. If tracing is disabled o
 
 When running Mastra agents or workflows within applications that have existing distributed tracing (OpenTelemetry, Datadog, etc.), you can connect Mastra traces to your parent trace context. This creates a unified view of your entire request flow, making it easier to understand how Mastra operations fit into the broader system.
 
-### Passing External Trace IDs
+### Passing external trace IDs
 
 Use the `tracingOptions` parameter to specify the trace context from your parent system:
 
@@ -1002,7 +777,7 @@ const result = await agent.generate('Analyze this data', {
 // The Mastra trace will now appear as a child in your distributed trace
 ```
 
-### OpenTelemetry Integration
+### OpenTelemetry integration
 
 Integration with OpenTelemetry allows Mastra traces to appear seamlessly in your existing observability platform:
 
@@ -1023,7 +798,7 @@ if (spanContext) {
 }
 ```
 
-### Workflow Integration
+### Workflow integration
 
 Workflows support the same pattern for trace propagation:
 
@@ -1040,7 +815,7 @@ const result = await run.start({
 })
 ```
 
-### ID Format Requirements
+### ID format requirements
 
 Mastra validates trace and span IDs to ensure compatibility:
 
@@ -1054,7 +829,7 @@ Invalid IDs are handled gracefully — Mastra logs an error and continues:
 
 This ensures tracing never crashes your application, even with malformed input.
 
-### Example: Express Middleware
+### Example: Express middleware
 
 Here's a complete example showing trace propagation in an Express application:
 
@@ -1084,97 +859,30 @@ app.post('/api/analyze', async (req, res) => {
 
 This creates a single distributed trace that includes both the HTTP request handling and the Mastra agent execution, viewable in your observability platform of choice.
 
-## Flushing traces in serverless environments
-
-In serverless environments like Vercel's fluid compute, AWS Lambda, or Cloudflare Workers, runtime instances can be reused across multiple requests. The `flush()` method allows you to ensure all buffered spans are exported before the runtime terminates, without shutting down the exporter (which would prevent future exports).
-
-> **Storage requirements:** Serverless environments have ephemeral filesystems. Use external storage instead of local file storage (`file:./mastra.db`). See the [Vercel deployment guide](https://mastra.ai/guides/deployment/vercel) for a complete setup example.
-
-### Using `flush()`
-
-Call `flush()` on the observability instance to flush all exporters:
-
-```ts
-// Get the observability instance from Mastra
-const observability = mastra.getObservability()
-
-// Flush all buffered spans to all exporters
-await observability.flush()
-```
-
-### When to Use `flush()`
-
-Use `flush()` in these scenarios:
-
-- **End of serverless function execution**: Ensure spans are exported before the runtime is paused or terminated
-- **Before long-running operations**: Flush accumulated spans before a potentially slow operation
-- **Periodic flushing**: In long-running processes, periodically flush to ensure timely data availability
-
-```ts
-// Example: Vercel serverless function
-export async function POST(req: Request) {
-  const result = await agent.generate([{ role: 'user', content: await req.text() }])
-
-  // Ensure spans are exported before function completes
-  const observability = mastra.getObservability()
-  await observability.flush()
-
-  return Response.json(result)
-}
-```
-
-### `flush()` vs `shutdown()`
-
-| Method       | Behavior                                      | Use Case                                   |
-| ------------ | --------------------------------------------- | ------------------------------------------ |
-| `flush()`    | Exports buffered spans, keeps exporter active | Serverless environments, periodic flushing |
-| `shutdown()` | Exports buffered spans, releases resources    | Application shutdown, graceful termination |
-
-Use `flush()` when you need to ensure data is exported but want to keep the exporter ready for future requests. Use `shutdown()` only when the application is terminating.
-
 ## What gets traced
 
 Mastra automatically creates spans for:
 
-### Agent Operations
+### Agent operations
 
-- **Agent runs** - Complete execution with instructions and tools
-- **LLM calls** - Model interactions with tokens and parameters
-- **Tool executions** - Function calls with inputs and outputs
-- **Memory operations** - Thread and semantic recall
+- **Agent runs**: Complete execution with instructions and tools
+- **LLM calls**: Model interactions with tokens and parameters
+- **Tool executions**: Function calls with inputs and outputs
+- **Memory operations**: Thread and semantic recall
 
-### Workflow Operations
+### Workflow operations
 
-- **Workflow runs** - Full execution from start to finish
-- **Individual steps** - Step processing with inputs/outputs
-- **Control flow** - Conditionals, loops, parallel execution
-- **Wait operations** - Delays and event waiting
+- **Workflow runs**: Full execution from start to finish
+- **Individual steps**: Step processing with inputs/outputs
+- **Control flow**: Conditionals, loops, parallel execution
+- **Wait operations**: Delays and event waiting
 
 ## See also
 
-### Reference Documentation
+### Reference documentation
 
 - [Configuration API](https://mastra.ai/reference/observability/tracing/configuration): ObservabilityConfig details
 - [Tracing Classes](https://mastra.ai/reference/observability/tracing/instances): Core classes and methods
 - [Span Interfaces](https://mastra.ai/reference/observability/tracing/spans): Span types and lifecycle
 - [Type Definitions](https://mastra.ai/reference/observability/tracing/interfaces): Complete interface reference
-- [Span filtering](https://mastra.ai/reference/observability/tracing/span-filtering): Filtering behavior, span types, and examples
-
-### Exporters
-
-- [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 integration
-- [ConsoleExporter](https://mastra.ai/reference/observability/tracing/exporters/console-exporter): Debug output
-- [Arize](https://mastra.ai/reference/observability/tracing/exporters/arize): Arize Phoenix and Arize AX integration
-- [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust): Braintrust integration
-- [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse): Langfuse integration
-- [MLflow](https://mastra.ai/docs/observability/tracing/exporters/otel): MLflow OTLP endpoint setup
-- [OpenTelemetry](https://mastra.ai/reference/observability/tracing/exporters/otel): OTEL-compatible platforms
-
-### Bridges
-
-- [OpenTelemetry Bridge](https://mastra.ai/reference/observability/tracing/bridges/otel): OTEL context integration
-
-### Processors
-
-- [Sensitive Data Filter](https://mastra.ai/docs/observability/tracing/processors/sensitive-data-filter): Data redaction
+- [Span filtering](https://mastra.ai/reference/observability/tracing/span-filtering): Filtering behavior, span types, and examples