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

package/.docs/raw/reference/observability/ai-tracing/exporters/braintrust.mdx

@@ -0,0 +1,112 @@
+---
+title: "BraintrustExporter | Exporters | AI Tracing | Reference"
+description: Braintrust exporter for AI tracing
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# BraintrustExporter
+
+Sends AI tracing data to Braintrust for eval and observability.
+
+## Constructor
+
+```typescript
+new BraintrustExporter(config: BraintrustExporterConfig)
+```
+
+## BraintrustExporterConfig
+
+```typescript
+interface BraintrustExporterConfig {
+  apiKey?: string;
+  endpoint?: string;
+  projectName?: string;
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+  tuningParameters?: Record<string, any>;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "apiKey",
+      type: "string",
+      description: "Braintrust API key",
+      required: false,
+    },
+    {
+      name: "endpoint",
+      type: "string",
+      description: "Custom Braintrust endpoint",
+      required: false,
+    },
+    {
+      name: "projectName",
+      type: "string",
+      description: "Project name (default: 'mastra-tracing')",
+      required: false,
+    },
+    {
+      name: "logLevel",
+      type: "'debug' | 'info' | 'warn' | 'error'",
+      description: "Logger level (default: 'warn')",
+      required: false,
+    },
+    {
+      name: "tuningParameters",
+      type: "Record<string, any>",
+      description: "Tuning parameters for Braintrust",
+      required: false,
+    },
+  ]}
+/>
+
+## Methods
+
+### exportEvent
+
+```typescript
+async exportEvent(event: AITracingEvent): Promise<void>
+```
+
+Exports a tracing event to Braintrust.
+
+### export
+
+```typescript
+async export(spans: ReadOnlyAISpan[]): Promise<void>
+```
+
+Batch exports spans to Braintrust.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending data and shuts down the client.
+
+## Usage
+
+```typescript
+import { BraintrustExporter } from '@mastra/braintrust';
+
+const exporter = new BraintrustExporter({
+  apiKey: process.env.BRAINTRUST_API_KEY,
+  projectName: 'my-ai-project',
+});
+```
+
+## Span Type Mapping
+
+| AI Span Type | Braintrust Type |
+|--------------|-----------------|
+| `LLM_GENERATION` | `llm` |
+| `LLM_CHUNK` | `llm` |
+| `TOOL_CALL` | `tool` |
+| `MCP_TOOL_CALL` | `tool` |
+| `WORKFLOW_CONDITIONAL_EVAL` | `function` |
+| `WORKFLOW_WAIT_EVENT` | `function` |
+| All others | `task` |

package/.docs/raw/reference/observability/ai-tracing/exporters/cloud-exporter.mdx

@@ -0,0 +1,176 @@
+---
+title: "CloudExporter | Exporters | AI Tracing | Reference"
+description: API reference for the CloudExporter
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# CloudExporter
+
+Sends traces to Mastra Cloud for online visualization and monitoring.
+
+## Constructor
+
+```typescript
+new CloudExporter(config?: CloudExporterConfig)
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "config",
+      type: "CloudExporterConfig",
+      description: "Configuration options",
+      required: false,
+    },
+  ]}
+/>
+
+## CloudExporterConfig
+
+```typescript
+interface CloudExporterConfig {
+  /** Maximum number of spans per batch. Default: 1000 */
+  maxBatchSize?: number;
+  
+  /** Maximum wait time before flushing in milliseconds. Default: 5000 */
+  maxBatchWaitMs?: number;
+  
+  /** Maximum retry attempts. Default: 3 */
+  maxRetries?: number;
+  
+  /** Cloud access token (from env or config) */
+  accessToken?: string;
+  
+  /** Cloud AI tracing endpoint */
+  endpoint?: string;
+  
+  /** Optional logger */
+  logger?: IMastraLogger;
+}
+```
+
+## Environment Variables
+
+The exporter reads these environment variables if not provided in config:
+
+- `MASTRA_CLOUD_ACCESS_TOKEN` - Access token for authentication
+- `MASTRA_CLOUD_AI_TRACES_ENDPOINT` - Custom endpoint (defaults to `https://api.mastra.ai/ai/spans/publish`)
+
+## Properties
+
+```typescript
+readonly name = 'mastra-cloud-ai-tracing-exporter';
+```
+
+## Methods
+
+### exportEvent
+
+```typescript
+async exportEvent(event: AITracingEvent): Promise<void>
+```
+
+Processes tracing events. Only exports SPAN_ENDED events to Cloud.
+
+<PropertiesTable
+  props={[
+    {
+      name: "event",
+      type: "AITracingEvent",
+      description: "The tracing event to export",
+      required: true,
+    },
+  ]}
+/>
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes remaining events and performs cleanup.
+
+## Behavior
+
+### Authentication
+
+If no access token is provided via config or environment variable, the exporter:
+- Logs a warning with sign-up information
+- Operates as a no-op (discards all events)
+
+### Batching
+
+The exporter batches spans for efficient network usage:
+- Flushes when batch size reaches `maxBatchSize`
+- Flushes when `maxBatchWaitMs` elapsed since first span in batch
+- Flushes on `shutdown()`
+
+### Error Handling
+
+- Uses exponential backoff retry with `maxRetries` attempts
+- Drops batches after all retries fail
+- Logs errors but continues processing new events
+
+### Event Processing
+
+- Only processes `SPAN_ENDED` events
+- Ignores `SPAN_STARTED` and `SPAN_UPDATED` events
+- Formats spans to MastraCloudSpanRecord format
+
+## MastraCloudSpanRecord
+
+Internal format for cloud spans:
+
+```typescript
+interface MastraCloudSpanRecord {
+  traceId: string;
+  spanId: string;
+  parentSpanId: string | null;
+  name: string;
+  spanType: string;
+  attributes: Record<string, any> | null;
+  metadata: Record<string, any> | null;
+  startedAt: Date;
+  endedAt: Date | null;
+  input: any;
+  output: any;
+  error: any;
+  isEvent: boolean;
+  createdAt: Date;
+  updatedAt: Date | null;
+}
+```
+
+## Usage
+
+```typescript
+import { CloudExporter } from '@mastra/core/ai-tracing';
+
+// Uses environment variable for token
+const exporter = new CloudExporter();
+
+// Explicit configuration
+const customExporter = new CloudExporter({
+  accessToken: 'your-token',
+  maxBatchSize: 500,
+  maxBatchWaitMs: 2000
+});
+```
+
+## See Also
+
+### Documentation
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview) - Complete guide
+- [Exporters](/docs/observability/ai-tracing/overview#exporters) - Exporter concepts
+
+### Other Exporters
+- [DefaultExporter](/reference/observability/ai-tracing/exporters/default-exporter) - Storage persistence
+- [ConsoleExporter](/reference/observability/ai-tracing/exporters/console-exporter) - Debug output
+- [Langfuse](/reference/observability/ai-tracing/exporters/langfuse) - Langfuse integration
+- [Braintrust](/reference/observability/ai-tracing/exporters/braintrust) - Braintrust integration
+
+### Reference
+- [Configuration](/reference/observability/ai-tracing/configuration) - Configuration options
+- [Interfaces](/reference/observability/ai-tracing/interfaces) - Type definitions

package/.docs/raw/reference/observability/ai-tracing/exporters/console-exporter.mdx

@@ -0,0 +1,148 @@
+---
+title: "ConsoleExporter | Exporters | AI Tracing | Reference"
+description: API reference for the ConsoleExporter
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# ConsoleExporter
+
+Outputs trace events to the console for debugging and development.
+
+## Constructor
+
+```typescript
+new ConsoleExporter(logger?: IMastraLogger)
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "logger",
+      type: "IMastraLogger",
+      description: "Logger instance to use. Falls back to ConsoleLogger with INFO level if not provided",
+      required: false,
+    },
+  ]}
+/>
+
+## Properties
+
+```typescript
+readonly name = 'tracing-console-exporter';
+```
+
+## Methods
+
+### exportEvent
+
+```typescript
+async exportEvent(event: AITracingEvent): Promise<void>
+```
+
+Exports a tracing event to the console.
+
+<PropertiesTable
+  props={[
+    {
+      name: "event",
+      type: "AITracingEvent",
+      description: "The tracing event to export",
+      required: true,
+    },
+  ]}
+/>
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Logs shutdown message.
+
+## Output Format
+
+The exporter outputs different formats based on event type:
+
+### SPAN_STARTED
+
+```
+🚀 SPAN_STARTED
+   Type: [span type]
+   Name: [span name]
+   ID: [span id]
+   Trace ID: [trace id]
+   Input: [formatted input]
+   Attributes: [formatted attributes]
+────────────────────────────────────────
+```
+
+### SPAN_ENDED
+
+```
+✅ SPAN_ENDED
+   Type: [span type]
+   Name: [span name]
+   ID: [span id]
+   Duration: [duration]ms
+   Trace ID: [trace id]
+   Input: [formatted input]
+   Output: [formatted output]
+   Error: [formatted error if present]
+   Attributes: [formatted attributes]
+────────────────────────────────────────
+```
+
+### SPAN_UPDATED
+
+```
+📝 SPAN_UPDATED
+   Type: [span type]
+   Name: [span name]
+   ID: [span id]
+   Trace ID: [trace id]
+   Input: [formatted input]
+   Output: [formatted output]
+   Error: [formatted error if present]
+   Updated Attributes: [formatted attributes]
+────────────────────────────────────────
+```
+
+## Usage
+
+```typescript
+import { ConsoleExporter } from '@mastra/core/ai-tracing';
+import { ConsoleLogger, LogLevel } from '@mastra/core/logger';
+
+// Use default logger (INFO level)
+const exporter = new ConsoleExporter();
+
+// Use custom logger
+const customLogger = new ConsoleLogger({ level: LogLevel.DEBUG });
+const exporterWithLogger = new ConsoleExporter(customLogger);
+```
+
+## Implementation Details
+
+- Formats attributes as JSON with 2-space indentation
+- Calculates and displays span duration in milliseconds
+- Handles serialization errors gracefully
+- Logs unimplemented event types as warnings
+- Uses 80-character separator lines between events
+
+## See Also
+
+### Documentation
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview) - Complete guide
+- [Exporters](/docs/observability/ai-tracing/overview#exporters) - Exporter concepts
+
+### Other Exporters
+- [DefaultExporter](/reference/observability/ai-tracing/exporters/default-exporter) - Storage persistence
+- [CloudExporter](/reference/observability/ai-tracing/exporters/cloud-exporter) - Mastra Cloud
+- [Langfuse](/reference/observability/ai-tracing/exporters/langfuse) - Langfuse integration
+- [Braintrust](/reference/observability/ai-tracing/exporters/braintrust) - Braintrust integration
+
+### Reference
+- [Configuration](/reference/observability/ai-tracing/configuration) - Configuration options
+- [Interfaces](/reference/observability/ai-tracing/interfaces) - Type definitions

package/.docs/raw/reference/observability/ai-tracing/exporters/default-exporter.mdx

@@ -0,0 +1,196 @@
+---
+title: "DefaultExporter | Exporters | AI Tracing | Reference"
+description: API reference for the DefaultExporter
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# DefaultExporter
+
+Persists traces to Mastra's configured storage with automatic batching and retry logic.
+
+## Constructor
+
+```typescript
+new DefaultExporter(config?: BatchingConfig, logger?: IMastraLogger)
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "config",
+      type: "BatchingConfig",
+      description: "Batching configuration options",
+      required: false,
+    },
+    {
+      name: "logger",
+      type: "IMastraLogger",
+      description: "Logger instance. Falls back to ConsoleLogger with INFO level if not provided",
+      required: false,
+    },
+  ]}
+/>
+
+## BatchingConfig
+
+```typescript
+interface BatchingConfig {
+  /** Maximum number of spans per batch. Default: 1000 */
+  maxBatchSize?: number;
+  
+  /** Maximum total buffer size before emergency flush. Default: 10000 */
+  maxBufferSize?: number;
+  
+  /** Maximum time to wait before flushing batch in milliseconds. Default: 5000 */
+  maxBatchWaitMs?: number;
+  
+  /** Maximum number of retry attempts. Default: 4 */
+  maxRetries?: number;
+  
+  /** Base retry delay in milliseconds (uses exponential backoff). Default: 500 */
+  retryDelayMs?: number;
+  
+  /** Tracing strategy or 'auto' for automatic selection. Default: 'auto' */
+  strategy?: TracingStrategy | 'auto';
+}
+```
+
+## TracingStrategy
+
+```typescript
+type TracingStrategy = 'realtime' | 'batch-with-updates' | 'insert-only';
+```
+
+### Strategy Behaviors
+
+- **realtime**: Immediately persists each event to storage
+- **batch-with-updates**: Batches creates and updates separately, applies in order
+- **insert-only**: Only processes SPAN_ENDED events, ignores updates
+
+## Properties
+
+```typescript
+readonly name = 'tracing-default-exporter';
+```
+
+## Methods
+
+### __registerMastra
+
+```typescript
+__registerMastra(mastra: Mastra): void
+```
+
+Registers the Mastra instance. Called automatically after Mastra construction.
+
+### init
+
+```typescript
+init(): void
+```
+
+Initializes the exporter after dependencies are ready. Resolves tracing strategy based on storage capabilities.
+
+### exportEvent
+
+```typescript
+async exportEvent(event: AITracingEvent): Promise<void>
+```
+
+Processes a tracing event according to the resolved strategy.
+
+<PropertiesTable
+  props={[
+    {
+      name: "event",
+      type: "AITracingEvent",
+      description: "The tracing event to export",
+      required: true,
+    },
+  ]}
+/>
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes remaining buffered events and performs cleanup.
+
+## Automatic Strategy Selection
+
+When `strategy: 'auto'` (default), the exporter queries the storage adapter for its capabilities:
+
+```typescript
+interface AITracingStrategy {
+  /** Strategies supported by this adapter */
+  supported: TracingStrategy[];
+  
+  /** Preferred strategy for optimal performance */
+  preferred: TracingStrategy;
+}
+```
+
+The exporter will:
+1. Use the storage adapter's preferred strategy if available
+2. Fall back to the first supported strategy if preferred isn't available
+3. Log a warning if a user-specified strategy isn't supported
+
+## Batching Behavior
+
+### Flush Triggers
+
+The buffer flushes when any of these conditions are met:
+- Buffer size reaches `maxBatchSize`
+- Time since first buffered event exceeds `maxBatchWaitMs`
+- Buffer size reaches `maxBufferSize` (emergency flush)
+- `shutdown()` is called
+
+### Retry Logic
+
+Failed flushes are retried with exponential backoff:
+- Retry delay: `retryDelayMs * 2^attempt`
+- Maximum attempts: `maxRetries`
+- Batch is dropped after all retries fail
+
+### Out-of-Order Handling
+
+For `batch-with-updates` strategy:
+- Tracks which spans have been created
+- Rejects updates/ends for spans not yet created
+- Logs warnings for out-of-order events
+- Maintains sequence numbers for ordered updates
+
+## Usage
+
+```typescript
+import { DefaultExporter } from '@mastra/core/ai-tracing';
+
+// Default configuration
+const exporter = new DefaultExporter();
+
+// Custom batching configuration
+const customExporter = new DefaultExporter({
+  maxBatchSize: 500,
+  maxBatchWaitMs: 2000,
+  strategy: 'batch-with-updates'
+});
+```
+
+## See Also
+
+### Documentation
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview) - Complete guide
+- [Exporters](/docs/observability/ai-tracing/overview#exporters) - Exporter concepts
+
+### Other Exporters
+- [CloudExporter](/reference/observability/ai-tracing/exporters/cloud-exporter) - Mastra Cloud
+- [ConsoleExporter](/reference/observability/ai-tracing/exporters/console-exporter) - Debug output
+- [Langfuse](/reference/observability/ai-tracing/exporters/langfuse) - Langfuse integration
+- [Braintrust](/reference/observability/ai-tracing/exporters/braintrust) - Braintrust integration
+
+### Reference
+- [Configuration](/reference/observability/ai-tracing/configuration) - Configuration options
+- [Interfaces](/reference/observability/ai-tracing/interfaces) - Type definitions