@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/reference/observability/tracing/exporters/console-exporter.md

@@ -0,0 +1,138 @@
+# ConsoleExporter
+
+Outputs trace events to the console for debugging and development.
+
+## Constructor
+
+```typescript
+new ConsoleExporter(config?: BaseExporterConfig)
+```
+
+## BaseExporterConfig
+
+```typescript
+interface BaseExporterConfig {
+  logger?: IMastraLogger
+  logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'
+}
+```
+
+## Properties
+
+```typescript
+readonly name = 'tracing-console-exporter';
+```
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to the console.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Logs shutdown message.
+
+## Output Format
+
+The exporter outputs different formats based on event type:
+
+### SPAN\_STARTED
+
+```text
+🚀 SPAN_STARTED
+   Type: [span type]
+   Name: [span name]
+   ID: [span id]
+   Trace ID: [trace id]
+   Input: [formatted input]
+   Attributes: [formatted attributes]
+────────────────────────────────────────
+```
+
+### SPAN\_ENDED
+
+```text
+✅ 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
+
+```text
+📝 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/observability'
+import { ConsoleLogger, LogLevel } from '@mastra/core/logger'
+
+// Use default logger (INFO level)
+const exporter = new ConsoleExporter()
+
+// Use custom log level
+const exporter = new ConsoleExporter({
+  logLevel: 'debug',
+})
+
+// Use custom logger instance
+const customLogger = new ConsoleLogger({ level: LogLevel.DEBUG })
+const exporterWithLogger = new ConsoleExporter({
+  logger: 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
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - Complete guide
+- [Exporters](https://mastra.ai/docs/observability/tracing/overview) - Exporter concepts
+
+### Other Exporters
+
+- [DefaultExporter](https://mastra.ai/reference/observability/tracing/exporters/default-exporter) - Storage persistence
+- [CloudExporter](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter) - Mastra Cloud
+- [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse) - Langfuse integration
+- [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust) - Braintrust integration
+
+### Reference
+
+- [Configuration](https://mastra.ai/reference/observability/tracing/configuration) - Configuration options
+- [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces) - Type definitions

package/.docs/reference/observability/tracing/exporters/datadog.md

@@ -0,0 +1,116 @@
+# DatadogExporter
+
+Sends Tracing data to Datadog's LLM Observability product for monitoring and analytics.
+
+## Constructor
+
+```typescript
+new DatadogExporter(config: DatadogExporterConfig)
+```
+
+## DatadogExporterConfig
+
+```typescript
+interface DatadogExporterConfig extends BaseExporterConfig {
+  apiKey?: string
+  mlApp?: string
+  site?: string
+  service?: string
+  env?: string
+  agentless?: boolean
+  integrationsEnabled?: boolean
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to Datadog LLM Observability.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered spans to Datadog without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending data and shuts down the exporter. Cancels any pending cleanup timers and disables LLM Observability.
+
+## Usage
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { DatadogExporter } from '@mastra/datadog'
+
+// Reads from DD_LLMOBS_ML_APP, DD_API_KEY, DD_SITE, DD_ENV
+const exporter = new DatadogExporter()
+```
+
+### Explicit Configuration
+
+```typescript
+import { DatadogExporter } from '@mastra/datadog'
+
+const exporter = new DatadogExporter({
+  mlApp: 'my-llm-app',
+  apiKey: process.env.DD_API_KEY,
+  site: 'datadoghq.com',
+  env: 'production',
+})
+```
+
+### With Local Datadog Agent
+
+```typescript
+const exporter = new DatadogExporter({
+  mlApp: 'my-llm-app',
+  agentless: false, // Use local Datadog Agent
+  env: 'production',
+})
+```
+
+## Span Mapping
+
+Mastra span types are mapped to Datadog LLMObs span kinds:
+
+| Mastra SpanType    | Datadog Kind |
+| ------------------ | ------------ |
+| `AGENT_RUN`        | `agent`      |
+| `MODEL_GENERATION` | `workflow`   |
+| `MODEL_STEP`       | `llm`        |
+| `TOOL_CALL`        | `tool`       |
+| `MCP_TOOL_CALL`    | `tool`       |
+| `WORKFLOW_RUN`     | `workflow`   |
+| All other types    | `task`       |
+
+All unmapped span types (including `MODEL_CHUNK`, `WORKFLOW_STEP`, `GENERIC`, and future span types) automatically default to `task`.
+
+## Environment Variables
+
+The exporter reads configuration from these environment variables:
+
+| Variable                      | Description                              |
+| ----------------------------- | ---------------------------------------- |
+| `DD_API_KEY`                  | Datadog API key                          |
+| `DD_LLMOBS_ML_APP`            | ML application name                      |
+| `DD_SITE`                     | Datadog site                             |
+| `DD_ENV`                      | Environment name                         |
+| `DD_LLMOBS_AGENTLESS_ENABLED` | Set to 'false' or '0' to use local agent |

package/.docs/reference/observability/tracing/exporters/default-exporter.md

@@ -0,0 +1,174 @@
+# DefaultExporter
+
+Persists traces to Mastra's configured storage with automatic batching and retry logic.
+
+## Constructor
+
+```typescript
+new DefaultExporter(config?: DefaultExporterConfig)
+```
+
+## DefaultExporterConfig
+
+```typescript
+interface DefaultExporterConfig extends BaseExporterConfig {
+  /** 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 storage strategy or 'auto' for automatic selection. Default: 'auto' */
+  strategy?: TracingStorageStrategy | 'auto'
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+## TracingStorageStrategy
+
+```typescript
+type TracingStorageStrategy = '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 = 'mastra-default-observability-exporter';
+```
+
+## Methods
+
+### init
+
+```typescript
+init(options: InitExporterOptions): void
+```
+
+Initializes the exporter after dependencies are ready. Resolves tracing strategy based on storage capabilities.
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Processes a tracing event according to the resolved strategy.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered events to storage without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### 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 TracingStrategy {
+  /** Strategies supported by this adapter */
+  supported: TracingStorageStrategy[]
+
+  /** Preferred strategy for optimal performance */
+  preferred: TracingStorageStrategy
+}
+```
+
+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/observability'
+
+// Default configuration
+const exporter = new DefaultExporter()
+
+// Custom batching configuration
+const customExporter = new DefaultExporter({
+  maxBatchSize: 500,
+  maxBatchWaitMs: 2000,
+  strategy: 'batch-with-updates',
+  logLevel: 'debug',
+})
+```
+
+## See Also
+
+### Documentation
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - Complete guide
+- [Exporters](https://mastra.ai/docs/observability/tracing/overview) - Exporter concepts
+
+### Other Exporters
+
+- [CloudExporter](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter) - Mastra Cloud
+- [ConsoleExporter](https://mastra.ai/reference/observability/tracing/exporters/console-exporter) - Debug output
+- [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse) - Langfuse integration
+- [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust) - Braintrust integration
+
+### Reference
+
+- [Configuration](https://mastra.ai/reference/observability/tracing/configuration) - Configuration options
+- [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces) - Type definitions

package/.docs/reference/observability/tracing/exporters/laminar.md

@@ -0,0 +1,78 @@
+# LaminarExporter
+
+Sends Tracing data to Laminar via OTLP/HTTP (protobuf).
+
+## Constructor
+
+```typescript
+new LaminarExporter(config?: LaminarExporterConfig)
+```
+
+## LaminarExporterConfig
+
+```typescript
+interface LaminarExporterConfig extends BaseExporterConfig {
+  apiKey?: string
+  baseUrl?: string
+  endpoint?: string
+  headers?: Record<string, string>
+  realtime?: boolean
+  disableBatch?: boolean
+  batchSize?: number
+  timeoutMillis?: number
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to Laminar.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered spans to Laminar without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending data and shuts down the exporter.
+
+## Usage
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { LaminarExporter } from '@mastra/laminar'
+
+// Reads from LMNR_PROJECT_API_KEY, LMNR_BASE_URL, LAMINAR_ENDPOINT
+const exporter = new LaminarExporter()
+```
+
+### Explicit Configuration
+
+```typescript
+import { LaminarExporter } from '@mastra/laminar'
+
+const exporter = new LaminarExporter({
+  apiKey: process.env.LMNR_PROJECT_API_KEY,
+  baseUrl: 'https://api.lmnr.ai',
+  realtime: true,
+})
+```

package/.docs/reference/observability/tracing/exporters/langfuse.md

@@ -0,0 +1,134 @@
+# LangfuseExporter
+
+Sends Tracing data to Langfuse for observability.
+
+## Constructor
+
+```typescript
+new LangfuseExporter(config: LangfuseExporterConfig)
+```
+
+## LangfuseExporterConfig
+
+```typescript
+interface LangfuseExporterConfig extends BaseExporterConfig {
+  publicKey?: string
+  secretKey?: string
+  baseUrl?: string
+  realtime?: boolean
+  options?: any
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to Langfuse.
+
+### export
+
+```typescript
+async export(spans: ReadOnlySpan[]): Promise<void>
+```
+
+Batch exports spans to Langfuse.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered spans to Langfuse without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending data and shuts down the client.
+
+## Usage
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { LangfuseExporter } from '@mastra/langfuse'
+
+// Reads from LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL
+const exporter = new LangfuseExporter()
+```
+
+### Explicit Configuration
+
+```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
+- `MODEL_GENERATION` spans → Langfuse generations
+- All other spans → Langfuse spans
+- Event spans → Langfuse events
+
+## Prompt Linking
+
+Link LLM generations to [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management) using the `withLangfusePrompt` helper:
+
+```typescript
+import { buildTracingOptions } from '@mastra/observability'
+import { withLangfusePrompt } from '@mastra/langfuse'
+import { Langfuse } from 'langfuse'
+
+const langfuse = new Langfuse({
+  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
+  secretKey: process.env.LANGFUSE_SECRET_KEY!,
+})
+
+const prompt = await langfuse.getPrompt('customer-support')
+
+const agent = new Agent({
+  name: 'support-agent',
+  instructions: prompt.prompt,
+  model: 'openai/gpt-4o',
+  defaultGenerateOptions: {
+    tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
+  },
+})
+```
+
+### Helper Functions
+
+#### `withLangfusePrompt(prompt)`
+
+Adds Langfuse prompt metadata to tracing options.
+
+```typescript
+// With Langfuse SDK prompt object
+withLangfusePrompt(prompt)
+
+// With manual fields
+withLangfusePrompt({ name: 'my-prompt', version: 1 })
+withLangfusePrompt({ id: 'prompt-uuid' })
+```
+
+When `metadata.langfuse.prompt` is set on a `MODEL_GENERATION` span (with either `id` alone, or `name` + `version`), the exporter automatically links the generation to the prompt in Langfuse.