@mastra/mcp-docs-server 0.13.24-alpha.3 → 0.13.25-alpha.0

package/.docs/raw/reference/observability/ai-tracing/processors/sensitive-data-filter.mdx

@@ -0,0 +1,178 @@
+---
+title: "SensitiveDataFilter | Processors | AI Tracing | Reference"
+description: API reference for the SensitiveDataFilter processor
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# SensitiveDataFilter
+
+An AISpanProcessor that redacts sensitive information from span fields.
+
+## Constructor
+
+```typescript
+new SensitiveDataFilter(options?: SensitiveDataFilterOptions)
+```
+
+## SensitiveDataFilterOptions
+
+```typescript
+interface SensitiveDataFilterOptions {
+  /** 
+   * List of sensitive field names to redact.
+   * Matching is case-insensitive and normalizes separators 
+   * (api-key, api_key, Api Key → apikey).
+   * Defaults include: password, token, secret, key, apikey, auth, 
+   * authorization, bearer, bearertoken, jwt, credential, 
+   * clientsecret, privatekey, refresh, ssn.
+   */
+  sensitiveFields?: string[];
+  
+  /** 
+   * The token used for full redaction.
+   * Default: "[REDACTED]"
+   */
+  redactionToken?: string;
+  
+  /** 
+   * Style of redaction to use:
+   * - "full": always replace with redactionToken
+   * - "partial": show 3 characters from the start and end, redact the middle
+   * Default: "full"
+   */
+  redactionStyle?: RedactionStyle;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "sensitiveFields",
+      type: "string[]",
+      description: "Field names to redact (case-insensitive, separator-agnostic)",
+      required: false,
+    },
+    {
+      name: "redactionToken",
+      type: "string",
+      description: "Replacement token for full redaction",
+      required: false,
+    },
+    {
+      name: "redactionStyle",
+      type: "'full' | 'partial'",
+      description: "Redaction style",
+      required: false,
+    },
+  ]}
+/>
+
+## RedactionStyle
+
+```typescript
+type RedactionStyle = 'full' | 'partial';
+```
+
+## Methods
+
+### process
+
+```typescript
+process(span: AnyAISpan): AnyAISpan
+```
+
+Process a span by filtering sensitive data across its key fields: attributes, metadata, input, output, and errorInfo.
+
+<PropertiesTable
+  props={[
+    {
+      name: "span",
+      type: "AnyAISpan",
+      description: "The input span to filter",
+      required: true,
+    },
+  ]}
+/>
+
+**Returns:** A new span with sensitive values redacted.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+No cleanup needed for this processor.
+
+## Properties
+
+```typescript
+readonly name = 'sensitive-data-filter';
+```
+
+## Default Sensitive Fields
+
+When no custom fields are provided:
+
+```typescript
+[
+  'password',
+  'token',
+  'secret',
+  'key',
+  'apikey',
+  'auth',
+  'authorization',
+  'bearer',
+  'bearertoken',
+  'jwt',
+  'credential',
+  'clientsecret',
+  'privatekey',
+  'refresh',
+  'ssn'
+]
+```
+
+## Processing Behavior
+
+### Field Matching
+
+- **Case-insensitive**: `APIKey`, `apikey`, `ApiKey` all match
+- **Separator-agnostic**: `api-key`, `api_key`, `apiKey` are treated identically  
+- **Exact matching**: After normalization, fields must match exactly
+  - `token` matches `token`, `Token`, `TOKEN`
+  - `token` does NOT match `promptTokens` or `tokenCount`
+
+### Redaction Styles
+
+#### Full Redaction (default)
+
+All matched values replaced with redactionToken.
+
+#### Partial Redaction
+
+- Shows first 3 and last 3 characters
+- Values ≤ 6 characters are fully redacted
+- Non-string values are converted to strings before partial redaction
+
+### Error Handling
+
+If filtering a field fails, the field is replaced with:
+
+```typescript
+{ error: { processor: "sensitive-data-filter" } }
+```
+
+### Processed Fields
+
+The filter recursively processes:
+
+- `span.attributes` - Span metadata and properties
+- `span.metadata` - Custom metadata
+- `span.input` - Input data
+- `span.output` - Output data  
+- `span.errorInfo` - Error information
+
+Handles nested objects, arrays, and circular references safely.

package/.docs/raw/reference/observability/ai-tracing/span.mdx

@@ -0,0 +1,371 @@
+---
+title: "Span | AI Tracing | Reference"
+description: Span interfaces, methods, and lifecycle events
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# Span
+
+## BaseSpan
+
+Base interface for all span types.
+
+```typescript
+interface BaseSpan<TType extends AISpanType> {
+  /** Unique span identifier */
+  id: string;
+  
+  /** OpenTelemetry-compatible trace ID (32 hex chars) */
+  traceId: string;
+  
+  /** Name of the span */
+  name: string;
+  
+  /** Type of the span */
+  type: TType;
+  
+  /** When span started */
+  startTime: Date;
+  
+  /** When span ended */
+  endTime?: Date;
+  
+  /** Type-specific attributes */
+  attributes?: AISpanTypeMap[TType];
+  
+  /** User-defined metadata */
+  metadata?: Record<string, any>;
+  
+  /** Input passed at the start of the span */
+  input?: any;
+  
+  /** Output generated at the end of the span */
+  output?: any;
+  
+  /** Error information if span failed */
+  errorInfo?: {
+    message: string;
+    id?: string;
+    domain?: string;
+    category?: string;
+    details?: Record<string, any>;
+  };
+  
+  /** Is an event span? (occurs at startTime, has no endTime) */
+  isEvent: boolean;
+}
+```
+
+## AISpan
+
+AI Span interface, used internally for tracing. Extends BaseSpan with lifecycle methods and properties.
+
+```typescript
+interface AISpan<TType extends AISpanType> extends BaseSpan<TType> {
+  /** Is an internal span? (spans internal to the operation of mastra) */
+  isInternal: boolean;
+  
+  /** Parent span reference (undefined for root spans) */
+  parent?: AnyAISpan;
+  
+  /** Pointer to the AITracing instance */
+  aiTracing: AITracing;
+}
+```
+
+### Properties
+
+```typescript
+/** Returns TRUE if the span is the root span of a trace */
+get isRootSpan(): boolean
+
+/** Returns TRUE if the span is a valid span (not a NO-OP Span) */
+get isValid(): boolean
+
+/** Get the closest parent spanId that isn't an internal span */
+getParentSpanId(includeInternalSpans?: boolean): string | undefined
+
+/** Returns a lightweight span ready for export */
+exportSpan(includeInternalSpans?: boolean): ExportedAISpan<TType> | undefined
+```
+
+### Methods
+
+#### end
+
+```typescript
+end(options?: EndSpanOptions<TType>): void
+```
+
+Ends the span and triggers export to configured exporters. Sets the `endTime` and optionally updates `output`, `metadata`, and `attributes`.
+
+<PropertiesTable
+  props={[
+    {
+      name: "output",
+      type: "any",
+      description: "Final output data from the operation",
+      required: false,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>",
+      description: "Additional metadata to merge",
+      required: false,
+    },
+    {
+      name: "attributes",
+      type: "Partial<AISpanTypeMap[TType]>",
+      description: "Type-specific attributes to update",
+      required: false,
+    },
+  ]}
+/>
+
+#### error
+
+```typescript
+error(options: ErrorSpanOptions<TType>): void
+```
+
+Records an error on the span. Sets the `errorInfo` field and can optionally end the span.
+
+<PropertiesTable
+  props={[
+    {
+      name: "error",
+      type: "Error",
+      description: "The error that occurred",
+      required: true,
+    },
+    {
+      name: "endSpan",
+      type: "boolean",
+      description: "Whether to end the span after recording the error",
+      required: false,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>",
+      description: "Additional error context metadata",
+      required: false,
+    },
+    {
+      name: "attributes",
+      type: "Partial<AISpanTypeMap[TType]>",
+      description: "Type-specific attributes to update",
+      required: false,
+    },
+  ]}
+/>
+
+#### update
+
+```typescript
+update(options: UpdateSpanOptions<TType>): void
+```
+
+Updates span data while it's still active. Can modify `input`, `output`, `metadata`, and `attributes`.
+
+<PropertiesTable
+  props={[
+    {
+      name: "input",
+      type: "any",
+      description: "Update or set input data",
+      required: false,
+    },
+    {
+      name: "output",
+      type: "any",
+      description: "Update or set output data",
+      required: false,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>",
+      description: "Metadata to merge with existing",
+      required: false,
+    },
+    {
+      name: "attributes",
+      type: "Partial<AISpanTypeMap[TType]>",
+      description: "Type-specific attributes to update",
+      required: false,
+    },
+  ]}
+/>
+
+#### createChildSpan
+
+```typescript
+createChildSpan<TChildType extends AISpanType>(
+  options: ChildSpanOptions<TChildType>
+): AISpan<TChildType>
+```
+
+Creates a child span under this span. Child spans track sub-operations and inherit the trace context.
+
+<PropertiesTable
+  props={[
+    {
+      name: "type",
+      type: "TChildType",
+      description: "Type of the child span",
+      required: true,
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Name of the child span",
+      required: true,
+    },
+    {
+      name: "attributes",
+      type: "AISpanTypeMap[TChildType]",
+      description: "Type-specific attributes",
+      required: false,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>",
+      description: "Initial metadata",
+      required: false,
+    },
+    {
+      name: "input",
+      type: "any",
+      description: "Initial input data",
+      required: false,
+    },
+  ]}
+/>
+
+#### createEventSpan
+
+```typescript
+createEventSpan<TChildType extends AISpanType>(
+  options: ChildEventOptions<TChildType>
+): AISpan<TChildType>
+```
+
+Creates an event span under this span. Event spans represent point-in-time occurrences with no duration.
+
+<PropertiesTable
+  props={[
+    {
+      name: "type",
+      type: "TChildType",
+      description: "Type of the event span",
+      required: true,
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Name of the event",
+      required: true,
+    },
+    {
+      name: "attributes",
+      type: "AISpanTypeMap[TChildType]",
+      description: "Type-specific attributes",
+      required: false,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>",
+      description: "Event metadata",
+      required: false,
+    },
+    {
+      name: "input",
+      type: "any",
+      description: "Event input data",
+      required: false,
+    },
+    {
+      name: "output",
+      type: "any",
+      description: "Event output data",
+      required: false,
+    },
+  ]}
+/>
+
+## ExportedAISpan
+
+Exported AI Span interface, used for tracing exporters. A lightweight version of AISpan without methods or circular references.
+
+```typescript
+interface ExportedAISpan<TType extends AISpanType> extends BaseSpan<TType> {
+  /** Parent span id reference (undefined for root spans) */
+  parentSpanId?: string;
+  
+  /** TRUE if the span is the root span of a trace */
+  isRootSpan: boolean;
+}
+```
+
+## Span Lifecycle Events
+
+Events emitted during the span lifecycle.
+
+### AITracingEventType
+
+```typescript
+enum AITracingEventType {
+  /** Emitted when a span is created and started */
+  SPAN_STARTED = 'span_started',
+  
+  /** Emitted when a span is updated via update() */
+  SPAN_UPDATED = 'span_updated',
+  
+  /** Emitted when a span is ended via end() or error() */
+  SPAN_ENDED = 'span_ended',
+}
+```
+
+### AITracingEvent
+
+```typescript
+type AITracingEvent =
+  | { type: 'span_started'; exportedSpan: AnyExportedAISpan }
+  | { type: 'span_updated'; exportedSpan: AnyExportedAISpan }
+  | { type: 'span_ended'; exportedSpan: AnyExportedAISpan };
+```
+
+Exporters receive these events to process and send trace data to observability platforms.
+
+## Union Types
+
+### AnyAISpan
+
+```typescript
+type AnyAISpan = AISpan<keyof AISpanTypeMap>;
+```
+
+Union type for cases that need to handle any span type.
+
+### AnyExportedAISpan
+
+```typescript
+type AnyExportedAISpan = ExportedAISpan<keyof AISpanTypeMap>;
+```
+
+Union type for cases that need to handle any exported span type.
+
+## See Also
+
+### Documentation
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview) - Concepts and usage
+- [Creating Child Spans](/docs/observability/ai-tracing/overview#creating-child-spans) - Practical examples
+- [Retrieving Trace IDs](/docs/observability/ai-tracing/overview#retrieving-trace-ids) - Using trace IDs
+
+### Reference
+- [AITracing Classes](/reference/observability/ai-tracing/ai-tracing) - Core tracing classes
+- [Interfaces](/reference/observability/ai-tracing/interfaces) - Complete type reference
+- [Configuration](/reference/observability/ai-tracing/configuration) - Configuration options
+
+### Examples
+- [Basic AI Tracing](/examples/observability/basic-ai-tracing) - Working with spans

package/.docs/raw/reference/observability/otel-tracing/providers/index.mdx

@@ -0,0 +1,22 @@
+---
+title: "OTLP Providers | Observability | Mastra Docs"
+description: Overview of OTLP observability providers.
+---
+
+import { Callout } from "nextra/components";
+
+# OTLP Providers
+
+These providers are supported with OTLP-based tracing:
+
+- [Arize AX](./arize-ax.mdx)
+- [Arize Phoenix](./arize-phoenix.mdx)
+- [Braintrust](./braintrust.mdx)
+- [Dash0](./dash0.mdx)
+- [Laminar](./laminar.mdx)
+- [Langfuse](./langfuse.mdx)
+- [Langsmith](./langsmith.mdx)
+- [LangWatch](./langwatch.mdx)
+- [New Relic](./new-relic.mdx)
+- [SigNoz](./signoz.mdx)
+- [Traceloop](./traceloop.mdx)

package/.docs/raw/reference/streaming/agents/stream.mdx

@@ -182,7 +182,7 @@ await agent.stream("message for agent");
       type: "TelemetrySettings",
       isOptional: true,
       description:
-        "Settings for telemetry collection during streaming.",
+        "Settings for OTLP telemetry collection during streaming (not AI tracing).",
       properties: [
         {
           parameters: [{
@@ -341,6 +341,38 @@ await agent.stream("message for agent");
       isOptional: true,
       description: "Runtime context for dependency injection and contextual information.",
     },
+    {
+      name: "tracingContext",
+      type: "TracingContext",
+      isOptional: true,
+      description: "AI tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.",
+      properties: [
+        {
+          parameters: [{
+            name: "currentSpan",
+            type: "AISpan",
+            isOptional: true,
+            description: "Current AI span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution."
+          }]
+        }
+      ]
+    },
+    {
+      name: "tracingOptions",
+      type: "TracingOptions",
+      isOptional: true,
+      description: "Options for AI tracing configuration.",
+      properties: [
+        {
+          parameters: [{
+            name: "metadata",
+            type: "Record<string, any>",
+            isOptional: true,
+            description: "Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags."
+          }]
+        }
+      ]
+    },
     {
       name: "maxTokens",
       type: "number",
@@ -456,6 +488,12 @@ await agent.stream("message for agent");
         }
       ]
     },
+    {
+      name: "traceId",
+      type: "string",
+      isOptional: true,
+      description: "The trace ID associated with this execution when AI tracing is enabled. Use this to correlate logs and debug execution flow.",
+    },
   ]}
 />
 

package/.docs/raw/reference/streaming/agents/streamVNext.mdx

@@ -105,6 +105,32 @@ const aiSdkStream = await agent.streamVNext("message for agent", {
       type: "TracingContext",
       isOptional: true,
       description: "AI tracing context for span hierarchy and metadata.",
+      properties: [
+        {
+          parameters: [{
+            name: "currentSpan",
+            type: "AISpan",
+            isOptional: true,
+            description: "Current AI span for creating child spans and adding metadata."
+          }]
+        }
+      ]
+    },
+    {
+      name: "tracingOptions",
+      type: "TracingOptions",
+      isOptional: true,
+      description: "Options for AI tracing configuration.",
+      properties: [
+        {
+          parameters: [{
+            name: "metadata",
+            type: "Record<string, any>",
+            isOptional: true,
+            description: "Metadata to add to the root trace span."
+          }]
+        }
+      ]
     },
     {
       name: "returnScorerData",
@@ -292,7 +318,7 @@ const aiSdkStream = await agent.streamVNext("message for agent", {
       type: "TelemetrySettings",
       isOptional: true,
       description:
-        "Settings for telemetry collection during streaming.",
+        "Settings for OTLP telemetry collection during streaming (not AI tracing).",
       properties: [
         {
           parameters: [{
@@ -525,7 +551,13 @@ const aiSdkStream = await agent.streamVNext("message for agent", {
     {
       name: "stream",
       type: "MastraModelOutput<Output> | AISDKV5OutputStream<Output>",
-      description: "Returns a streaming interface based on the format parameter. When format is 'mastra' (default), returns MastraModelOutput. When format is 'aisdk', returns AISDKV5OutputStream for AI SDK v5 compatibility.",
+      description: "Returns a streaming interface based on the format parameter. When format is 'mastra' (default), returns MastraModelOutput with traceId property. When format is 'aisdk', returns AISDKV5OutputStream for AI SDK v5 compatibility.",
+    },
+    {
+      name: "traceId",
+      type: "string",
+      isOptional: true,
+      description: "The trace ID associated with this execution when AI tracing is enabled. Available via stream.traceId for Mastra format.",
     },
   ]}
 />