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

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

@@ -0,0 +1,181 @@
+---
+title: "AITracing | AI Tracing | Reference"
+description: Core AI Tracing classes and methods
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# AITracing
+
+## DefaultAITracing
+
+Default implementation of the AITracing interface.
+
+### Constructor
+
+```typescript
+new DefaultAITracing(config: TracingConfig)
+```
+
+Creates a new DefaultAITracing instance with the specified configuration.
+
+### Properties
+
+Inherits all properties and methods from BaseAITracing.
+
+## BaseAITracing
+
+Base class for custom AI tracing implementations.
+
+### Methods
+
+#### getConfig
+
+```typescript
+getConfig(): Readonly<Required<TracingConfig>>
+```
+
+Returns the current tracing configuration.
+
+#### getExporters
+
+```typescript
+getExporters(): readonly AITracingExporter[]
+```
+
+Returns all configured exporters.
+
+#### getProcessors
+
+```typescript
+getProcessors(): readonly AISpanProcessor[]
+```
+
+Returns all configured processors.
+
+#### getLogger
+
+```typescript
+getLogger(): IMastraLogger
+```
+
+Returns the logger instance for exporters and other components.
+
+#### startSpan
+
+```typescript
+startSpan<TType extends AISpanType>(
+  options: StartSpanOptions<TType>
+): AISpan<TType>
+```
+
+Start a new span of a specific AISpanType. Creates the root span of a trace if no parent is provided.
+
+<PropertiesTable
+  props={[
+    {
+      name: "type",
+      type: "AISpanType",
+      description: "Type of span to create",
+      required: true,
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Name of the span",
+      required: true,
+    },
+    {
+      name: "parent",
+      type: "AnyAISpan",
+      description: "Parent span (if not root)",
+      required: false,
+    },
+    {
+      name: "attributes",
+      type: "AISpanTypeMap[TType]",
+      description: "Type-specific attributes",
+      required: false,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>",
+      description: "User-defined metadata",
+      required: false,
+    },
+    {
+      name: "input",
+      type: "any",
+      description: "Initial input data",
+      required: false,
+    },
+    {
+      name: "customSamplerOptions",
+      type: "CustomSamplerOptions",
+      description: "Options for custom sampler",
+      required: false,
+    },
+  ]}
+/>
+
+#### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Shuts down all exporters and processors, cleaning up resources.
+
+## Custom Implementation
+
+To create a custom AI tracing implementation, extend BaseAITracing:
+
+```typescript
+class CustomAITracing extends BaseAITracing {
+  constructor(config: TracingConfig) {
+    super(config);
+    // Custom initialization
+  }
+  
+  // Override methods as needed
+  startSpan<TType extends AISpanType>(
+    options: StartSpanOptions<TType>
+  ): AISpan<TType> {
+    // Custom span creation logic
+    return super.startSpan(options);
+  }
+}
+```
+
+## NO-OP Spans
+
+When tracing is disabled (sampling returns false), NO-OP spans are returned:
+
+### NoOpAISpan
+
+```typescript
+class NoOpAISpan<TType extends AISpanType> extends BaseAISpan<TType>
+```
+
+A span that performs no operations. All methods are no-ops:
+- `id` returns `'no-op'`
+- `traceId` returns `'no-op-trace'`
+- `isValid` returns `false`
+- `end()`, `error()`, `update()` do nothing
+- `createChildSpan()` returns another NO-OP span
+
+## See Also
+
+### Documentation
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview) - Concepts and usage guide
+- [Configuration Reference](/reference/observability/ai-tracing/configuration) - Configuration options
+- [Interfaces Reference](/reference/observability/ai-tracing/interfaces) - Type definitions
+- [Span Reference](/reference/observability/ai-tracing/span) - Span lifecycle and methods
+
+### Examples
+- [Basic AI Tracing](/examples/observability/basic-ai-tracing) - Getting started example
+
+### Exporters
+- [DefaultExporter](/reference/observability/ai-tracing/exporters/default-exporter) - Storage persistence
+- [CloudExporter](/reference/observability/ai-tracing/exporters/cloud-exporter) - Mastra Cloud integration
+- [ConsoleExporter](/reference/observability/ai-tracing/exporters/console-exporter) - Debug output

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

@@ -0,0 +1,233 @@
+---
+title: "Configuration | AI Tracing | Reference"
+description: AI Tracing configuration types and registry functions
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# Configuration
+
+## ObservabilityRegistryConfig
+
+```typescript
+interface ObservabilityRegistryConfig {
+  default?: { enabled?: boolean };
+  configs?: Record<string, TracingConfig | AITracing>;
+  configSelector?: ConfigSelector;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "default",
+      type: "{ enabled?: boolean }",
+      description: "Enable default configuration",
+      required: false,
+    },
+    {
+      name: "configs",
+      type: "Record<string, TracingConfig | AITracing>",
+      description: "Named tracing configurations",
+      required: false,
+    },
+    {
+      name: "configSelector",
+      type: "ConfigSelector",
+      description: "Runtime configuration selector",
+      required: false,
+    },
+  ]}
+/>
+
+## TracingConfig
+
+```typescript
+interface TracingConfig {
+  name: string;
+  serviceName: string;
+  sampling?: SamplingStrategy;
+  exporters?: AITracingExporter[];
+  processors?: AISpanProcessor[];
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "name",
+      type: "string",
+      description: "Configuration identifier",
+      required: true,
+    },
+    {
+      name: "serviceName",
+      type: "string",
+      description: "Service name in traces",
+      required: true,
+    },
+    {
+      name: "sampling",
+      type: "SamplingStrategy",
+      description: "Sampling configuration",
+      required: false,
+    },
+    {
+      name: "exporters",
+      type: "AITracingExporter[]",
+      description: "Trace data exporters",
+      required: false,
+    },
+    {
+      name: "processors",
+      type: "AISpanProcessor[]",
+      description: "Span processors",
+      required: false,
+    },
+  ]}
+/>
+
+## SamplingStrategy
+
+```typescript
+type SamplingStrategy = 
+  | { type: 'always' }
+  | { type: 'never' }
+  | { type: 'ratio', probability: number }
+  | { type: 'custom', sampler: (options?: TracingOptions) => boolean };
+```
+
+## ConfigSelector
+
+```typescript
+type ConfigSelector = (
+  options: ConfigSelectorOptions,
+  availableConfigs: Map<string, AITracing>
+) => string | undefined;
+```
+
+## ConfigSelectorOptions
+
+```typescript
+interface ConfigSelectorOptions {
+  metadata?: Record<string, any>;
+  runtimeContext?: Map<string, any>;
+}
+```
+
+# Registry Functions
+
+## setupAITracing
+
+```typescript
+function setupAITracing(config: ObservabilityRegistryConfig): void
+```
+
+Initializes AI tracing from configuration. Called automatically by Mastra constructor.
+
+## registerAITracing
+
+```typescript
+function registerAITracing(
+  name: string, 
+  instance: AITracing, 
+  isDefault?: boolean
+): void
+```
+
+Registers a tracing config in the global registry.
+
+## getAITracing
+
+```typescript
+function getAITracing(name: string): AITracing | undefined
+```
+
+Retrieves a tracing config by name.
+
+## getDefaultAITracing
+
+```typescript
+function getDefaultAITracing(): AITracing | undefined
+```
+
+Returns the default tracing config.
+
+## getSelectedAITracing
+
+```typescript
+function getSelectedAITracing(
+  options: ConfigSelectorOptions
+): AITracing | undefined
+```
+
+Returns the tracing config selected by the config selector or default.
+
+## setSelector
+
+```typescript
+function setSelector(selector: ConfigSelector): void
+```
+
+Sets the global config selector function.
+
+## unregisterAITracing
+
+```typescript
+function unregisterAITracing(name: string): boolean
+```
+
+Removes a tracing config from the registry.
+
+## shutdownAITracingRegistry
+
+```typescript
+async function shutdownAITracingRegistry(): Promise<void>
+```
+
+Shuts down all tracing configs and clears the registry.
+
+## clearAITracingRegistry
+
+```typescript
+function clearAITracingRegistry(): void
+```
+
+Clears all configs without shutdown.
+
+## getAllAITracing
+
+```typescript
+function getAllAITracing(): ReadonlyMap<string, AITracing>
+```
+
+Returns all registered tracing configs.
+
+## hasAITracing
+
+```typescript
+function hasAITracing(name: string): boolean
+```
+
+Checks if a tracing instance exists and is enabled.
+
+## See Also
+
+### Documentation
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview) - Concepts and usage guide
+- [Sampling Strategies](/docs/observability/ai-tracing/overview#sampling-strategies) - Sampling configuration details
+- [Multi-Config Setup](/docs/observability/ai-tracing/overview#multi-config-setup) - Using multiple configurations
+
+### Reference
+- [AITracing Classes](/reference/observability/ai-tracing/ai-tracing) - Core tracing classes
+- [Interfaces](/reference/observability/ai-tracing/interfaces) - Type definitions
+- [Span Reference](/reference/observability/ai-tracing/span) - Span lifecycle
+
+### Examples
+- [Basic AI Tracing](/examples/observability/basic-ai-tracing) - Getting started
+
+### Exporters
+- [DefaultExporter](/reference/observability/ai-tracing/exporters/default-exporter) - Storage configuration
+- [CloudExporter](/reference/observability/ai-tracing/exporters/cloud-exporter) - Cloud setup
+- [Langfuse](/reference/observability/ai-tracing/exporters/langfuse) - Langfuse integration
+- [Braintrust](/reference/observability/ai-tracing/exporters/braintrust) - Braintrust integration

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