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

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

@@ -1,138 +0,0 @@
-# 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

@@ -1,116 +0,0 @@
-# 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

@@ -1,174 +0,0 @@
-# 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

@@ -1,78 +0,0 @@
-# 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

@@ -1,134 +0,0 @@
-# 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.