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

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

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

@@ -0,0 +1,116 @@
+---
+title: "LangfuseExporter | Exporters | AI Tracing | Reference"
+description: Langfuse exporter for AI tracing
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# LangfuseExporter
+
+Sends AI tracing data to Langfuse for observability.
+
+## Constructor
+
+```typescript
+new LangfuseExporter(config: LangfuseExporterConfig)
+```
+
+## LangfuseExporterConfig
+
+```typescript
+interface LangfuseExporterConfig {
+  publicKey?: string;
+  secretKey?: string;
+  baseUrl?: string;
+  realtime?: boolean;
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+  options?: any;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "publicKey",
+      type: "string",
+      description: "Langfuse API key",
+      required: false,
+    },
+    {
+      name: "secretKey",
+      type: "string",
+      description: "Langfuse secret key",
+      required: false,
+    },
+    {
+      name: "baseUrl",
+      type: "string",
+      description: "Langfuse host URL",
+      required: false,
+    },
+    {
+      name: "realtime",
+      type: "boolean",
+      description: "Enable realtime mode - flushes after each event",
+      required: false,
+    },
+    {
+      name: "logLevel",
+      type: "'debug' | 'info' | 'warn' | 'error'",
+      description: "Logger level (default: 'warn')",
+      required: false,
+    },
+    {
+      name: "options",
+      type: "any",
+      description: "Additional Langfuse client options",
+      required: false,
+    },
+  ]}
+/>
+
+## Methods
+
+### exportEvent
+
+```typescript
+async exportEvent(event: AITracingEvent): Promise<void>
+```
+
+Exports a tracing event to Langfuse.
+
+### export
+
+```typescript
+async export(spans: ReadOnlyAISpan[]): Promise<void>
+```
+
+Batch exports spans to Langfuse.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending data and shuts down the client.
+
+## Usage
+
+```typescript
+import { LangfuseExporter } from '@mastra/langfuse';
+
+const exporter = new LangfuseExporter({
+  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
+  secretKey: process.env.LANGFUSE_SECRET_KEY,
+  baseUrl: 'https://cloud.langfuse.com',
+  realtime: true,
+});
+```
+
+## Span Mapping
+
+- Root spans → Langfuse traces
+- `LLM_GENERATION` spans → Langfuse generations
+- All other spans → Langfuse spans
+- Event spans → Langfuse events