Add requestContext snapshot to tracing spans (#14020)

## Description

This PR adds automatic capture of `RequestContext` snapshots to tracing
spans. Each span now stores a serialized snapshot of the active
`RequestContext` at the time of span creation, making request-scoped
values (user IDs, tenant IDs, feature flags, etc.) available when
viewing traces.

### Key Changes

- **Span Enhancement**: Added `requestContext` field to `BaseSpan` that
captures a snapshot of the `RequestContext` when a span is created
- **Serialization**: Request context values are serialized using
`deepClean` to handle non-serializable values (functions are replaced
with `'[Function]'`)
- **Empty Context Handling**: Empty request contexts are not stored
(undefined if no data)
- **Child Span Support**: Child spans can optionally capture their own
request context snapshots, allowing different context states at
different span levels
- **Database Schema Updates**: Added `requestContext` column to spans
table across all storage backends (ClickHouse, LibSQL, MSSQL,
PostgreSQL) with backwards compatibility via `alterTable` with
`ifNotExists`
- **Exporter Updates**: Updated exporters (Cloud, Default) to include
`requestContext` in exported span records
- **Type Updates**: Updated TypeScript interfaces and Zod schemas to
include the new field

### Testing

Added comprehensive test coverage including:
- Root span request context capture
- Exported span serialization
- Child span context snapshots (with independent state capture)
- Child spans without explicit context
- Empty context handling
- Non-serializable value filtering

Integration tests verify request context propagation through agent
generation with multiple span types.

## Type of Change

- [x] New feature (non-breaking change that adds functionality)
- [x] Documentation update
- [x] Test update

## Checklist

- [x] I have made corresponding changes to the documentation
- [x] I have added tests that prove my feature works
- [x] All existing tests pass

https://claude.ai/code/session_01QaSLa999aBbRDenrGqtgic

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

## Release Notes

* **New Features**
* Request context snapshot is now captured in tracing spans, making
request-scoped values (user IDs, tenant IDs, feature flags) available
for enhanced observability.

* **Documentation**
  * Updated tracing spans reference documentation.

* **Tests**
* Added comprehensive tests verifying request context propagation and
serialization across traces.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: epinzur

.changeset/blue-carrots-count.md

@@ -0,0 +1,6 @@
+---
+'@mastra/core': minor
+'@mastra/observability': minor
+---
+
+Added `requestContext` field to tracing spans. Each span now automatically captures a snapshot of the active `RequestContext`, making request-scoped values like user IDs, tenant IDs, and feature flags available when viewing traces.

.changeset/slick-swans-train.md

@@ -0,0 +1,8 @@
+---
+'@mastra/clickhouse': minor
+'@mastra/libsql': minor
+'@mastra/mssql': minor
+'@mastra/pg': minor
+---
+
+Added `requestContext` column to the spans table. Request context data from tracing is now persisted alongside other span data.

docs/src/content/en/reference/observability/tracing/spans.mdx

@@ -54,6 +54,8 @@ interface BaseSpan<TType extends SpanType> {
     details?: Record<string, any>
   }
 
+  /** Snapshot of the RequestContext */
+  requestContext?: Record<string, any>
   /** Is an event span? (occurs at startTime, has no endTime) */
   isEvent: boolean
 }

observability/mastra/src/exporters/cloud.ts

@@ -30,6 +30,7 @@ interface MastraCloudSpanRecord {
   spanType: string;
   attributes: Record<string, any> | null;
   metadata: Record<string, any> | null;
+  requestContext: Record<string, any> | null;
   startedAt: Date;
   endedAt: Date | null;
   input: any;
@@ -119,6 +120,7 @@ export class CloudExporter extends BaseExporter {
       spanType: span.type,
       attributes: span.attributes ?? null,
       metadata: span.metadata ?? null,
+      requestContext: span.requestContext ?? null,
       startedAt: span.startTime,
       endedAt: span.endTime ?? null,
       input: span.input ?? null,

observability/mastra/src/exporters/default.ts

@@ -444,6 +444,7 @@ export class DefaultExporter extends BaseExporter {
       input: span.input ?? null,
       output: span.output ?? null,
       error: span.errorInfo ?? null,
+      requestContext: span.requestContext ?? null,
       isEvent: span.isEvent,
 
       // Timestamps
@@ -463,6 +464,7 @@ export class DefaultExporter extends BaseExporter {
       input: span.input,
       output: span.output,
       error: span.errorInfo ?? null,
+      requestContext: span.requestContext ?? null,
     };
   }
 

observability/mastra/src/instances/base.ts

@@ -204,6 +204,7 @@ export abstract class BaseObservabilityInstance extends MastraBase implements Ob
       metadata: enrichedMetadata,
       traceState,
       tags,
+      requestContext,
     });
 
     if (span.isEvent) {

observability/mastra/src/integration-tests.test.ts

@@ -2,6 +2,7 @@ import { MockLanguageModelV2, convertArrayToReadableStream } from '@internal/ai-
 import { Agent } from '@mastra/core/agent';
 import type { StructuredOutputOptions } from '@mastra/core/agent';
 import type { MastraDBMessage } from '@mastra/core/agent/message-list';
+import { RequestContext } from '@mastra/core/di';
 import { Mastra } from '@mastra/core/mastra';
 import { SpanType } from '@mastra/core/observability';
 import type { TracingContext } from '@mastra/core/observability';
@@ -1792,4 +1793,49 @@ describe('Tracing Integration Tests', () => {
       await testExporter.assertMatchesSnapshot('tags-from-stream-default-options-trace.json');
     });
   });
+
+  describe('requestContext snapshot on spans', () => {
+    it('should propagate requestContext to all spans in agent generate', async () => {
+      const testAgent = new Agent({
+        id: 'test-agent-ctx',
+        name: 'Test Agent Ctx',
+        instructions: 'You are a test agent',
+        model: mockModelV2,
+        tools: { calculator: calculatorTool },
+      });
+
+      const mastra = new Mastra({
+        ...getBaseMastraConfig(testExporter),
+        agents: { testAgent },
+      });
+
+      const requestContext = new RequestContext();
+      requestContext.set('userId', 'user-123');
+      requestContext.set('tenantId', 'tenant-456');
+      requestContext.set('environment', 'production');
+
+      const agent = mastra.getAgent('testAgent');
+      const result = await agent.generate('Calculate 5 + 3', { requestContext });
+
+      expect(result.text).toBeDefined();
+      expect(result.traceId).toBeDefined();
+
+      // Root AGENT_RUN span should have requestContext snapshot
+      const agentRunSpans = testExporter.getSpansByType(SpanType.AGENT_RUN);
+      expect(agentRunSpans).toHaveLength(1);
+      expect(agentRunSpans[0]?.requestContext).toEqual({
+        userId: 'user-123',
+        tenantId: 'tenant-456',
+        environment: 'production',
+      });
+
+      // Child spans (TOOL_CALL, MODEL_GENERATION) should also have requestContext
+      // since the framework passes requestContext when creating child spans
+      const allSpans = testExporter.getAllSpans();
+      const spansWithContext = allSpans.filter(s => s.requestContext);
+      expect(spansWithContext.length).toBeGreaterThanOrEqual(1);
+
+      finalExpectations(testExporter);
+    });
+  });
 });

observability/mastra/src/spans/base.ts

@@ -130,6 +130,7 @@ export abstract class BaseSpan<TType extends SpanType = any> implements Span<TTy
     details?: Record<string, any>;
   };
   public metadata?: Record<string, any>;
+  public requestContext?: Record<string, any>;
   public tags?: string[];
   public traceState?: TraceState;
   /** Entity type that created the span (e.g., agent, workflow) */
@@ -152,6 +153,9 @@ export abstract class BaseSpan<TType extends SpanType = any> implements Span<TTy
     this.type = options.type;
     this.attributes = deepClean(options.attributes, this.deepCleanOptions) || ({} as SpanTypeMap[TType]);
     this.metadata = deepClean(options.metadata, this.deepCleanOptions);
+    if (options.requestContext && options.requestContext.size() > 0) {
+      this.requestContext = deepClean(options.requestContext.all, this.deepCleanOptions);
+    }
     this.parent = options.parent;
     this.startTime = options.startTime ?? new Date();
     this.observabilityInstance = observabilityInstance;
@@ -274,6 +278,7 @@ export abstract class BaseSpan<TType extends SpanType = any> implements Span<TTy
       input: hideInput ? undefined : this.input,
       output: hideOutput ? undefined : this.output,
       errorInfo: this.errorInfo,
+      requestContext: this.requestContext,
       isEvent: this.isEvent,
       isRootSpan: this.isRootSpan,
       parentSpanId: this.getParentSpanId(includeInternalSpans),

observability/mastra/src/tracing.test.ts

@@ -1797,6 +1797,180 @@ describe('Tracing', () => {
     });
   });
 
+  describe('RequestContext Snapshot on Spans', () => {
+    it('should store serialized requestContext on root span', () => {
+      const observability = new DefaultObservabilityInstance({
+        serviceName: 'test-service',
+        name: 'test',
+        exporters: [testExporter],
+      });
+
+      const requestContext = new RequestContext();
+      requestContext.set('userId', 'user-123');
+      requestContext.set('tenantId', 'tenant-456');
+
+      const span = observability.startSpan({
+        type: SpanType.AGENT_RUN,
+        name: 'test-agent',
+        attributes: {},
+        requestContext,
+      });
+
+      expect(span.requestContext).toEqual({
+        userId: 'user-123',
+        tenantId: 'tenant-456',
+      });
+
+      span.end();
+    });
+
+    it('should include requestContext in exported span', () => {
+      const observability = new DefaultObservabilityInstance({
+        serviceName: 'test-service',
+        name: 'test',
+        exporters: [testExporter],
+      });
+
+      const requestContext = new RequestContext();
+      requestContext.set('userId', 'user-123');
+
+      const span = observability.startSpan({
+        type: SpanType.AGENT_RUN,
+        name: 'test-agent',
+        attributes: {},
+        requestContext,
+      });
+
+      const exported = span.exportSpan();
+      expect(exported?.requestContext).toEqual({
+        userId: 'user-123',
+      });
+
+      span.end();
+    });
+
+    it('should store requestContext on child spans when passed', () => {
+      const observability = new DefaultObservabilityInstance({
+        serviceName: 'test-service',
+        name: 'test',
+        exporters: [testExporter],
+      });
+
+      const requestContext = new RequestContext();
+      requestContext.set('userId', 'user-123');
+
+      const rootSpan = observability.startSpan({
+        type: SpanType.AGENT_RUN,
+        name: 'test-agent',
+        attributes: {},
+        requestContext,
+      });
+
+      // Mutate requestContext before creating child
+      requestContext.set('stepData', 'step-specific');
+
+      const childSpan = rootSpan.createChildSpan({
+        type: SpanType.TOOL_CALL,
+        name: 'tool-call',
+        attributes: {},
+        requestContext,
+      });
+
+      // Child should capture the mutated state
+      expect(childSpan.requestContext).toEqual({
+        userId: 'user-123',
+        stepData: 'step-specific',
+      });
+
+      // Root should still have the original snapshot
+      expect(rootSpan.requestContext).toEqual({
+        userId: 'user-123',
+      });
+
+      rootSpan.end();
+    });
+
+    it('should not include requestContext on child spans when not passed', () => {
+      const observability = new DefaultObservabilityInstance({
+        serviceName: 'test-service',
+        name: 'test',
+        exporters: [testExporter],
+      });
+
+      const requestContext = new RequestContext();
+      requestContext.set('userId', 'user-123');
+
+      const rootSpan = observability.startSpan({
+        type: SpanType.AGENT_RUN,
+        name: 'test-agent',
+        attributes: {},
+        requestContext,
+      });
+
+      const childSpan = rootSpan.createChildSpan({
+        type: SpanType.MODEL_GENERATION,
+        name: 'llm-call',
+        attributes: {},
+        // No requestContext passed
+      });
+
+      expect(childSpan.requestContext).toBeUndefined();
+
+      rootSpan.end();
+    });
+
+    it('should not include requestContext when empty', () => {
+      const observability = new DefaultObservabilityInstance({
+        serviceName: 'test-service',
+        name: 'test',
+        exporters: [testExporter],
+      });
+
+      const requestContext = new RequestContext();
+      // Empty requestContext
+
+      const span = observability.startSpan({
+        type: SpanType.AGENT_RUN,
+        name: 'test-agent',
+        attributes: {},
+        requestContext,
+      });
+
+      expect(span.requestContext).toBeUndefined();
+
+      span.end();
+    });
+
+    it('should filter non-serializable values from requestContext', () => {
+      const observability = new DefaultObservabilityInstance({
+        serviceName: 'test-service',
+        name: 'test',
+        exporters: [testExporter],
+      });
+
+      const requestContext = new RequestContext();
+      requestContext.set('userId', 'user-123');
+      requestContext.set('callback', () => {});
+      requestContext.set('nested', { data: 'value' });
+
+      const span = observability.startSpan({
+        type: SpanType.AGENT_RUN,
+        name: 'test-agent',
+        attributes: {},
+        requestContext,
+      });
+
+      // Functions should be replaced with '[Function]' by deepClean
+      expect(span.requestContext).toEqual({
+        userId: 'user-123',
+        callback: '[Function]',
+        nested: { data: 'value' },
+      });
+
+      span.end();
+    });
+  });
+
   describe('hideInput/hideOutput Support', () => {
     it('should hide input from exported spans when hideInput is true', () => {
       const observability = new DefaultObservabilityInstance({

packages/core/src/evals/scoreTraces/runScorerOnTarget.test.ts

@@ -29,6 +29,7 @@ function createMockSpanRecord(overrides: Partial<SpanRecord> = {}): SpanRecord {
     metadata: {},
     links: null,
     error: null,
+    requestContext: null,
     isEvent: false,
     ...overrides,
   } as SpanRecord;