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

package/.docs/reference/observability/tracing/bridges/otel.md

@@ -0,0 +1,131 @@
+# OtelBridge
+
+> **Warning:** The OpenTelemetry Bridge is currently **experimental**. APIs and configuration options may change in future releases.
+
+Enables bidirectional integration between Mastra tracing and OpenTelemetry infrastructure. Creates native OTEL spans for Mastra operations and inherits context from active OTEL spans.
+
+## Constructor
+
+```typescript
+new OtelBridge()
+```
+
+## Methods
+
+### executeInContext
+
+```typescript
+executeInContext<T>(spanId: string, fn: () => Promise<T>): Promise<T>
+```
+
+Executes an async function within the OTEL context of a Mastra span. OTEL-instrumented code running inside the function will have correct parent relationships.
+
+**Returns:** `Promise<T>` - The result of the function execution.
+
+### executeInContextSync
+
+```typescript
+executeInContextSync<T>(spanId: string, fn: () => T): T
+```
+
+Executes a synchronous function within the OTEL context of a Mastra span.
+
+**Returns:** `T` - The result of the function execution.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Shuts down the bridge and cleans up resources. Ends any spans that were not properly closed.
+
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { OtelBridge } from '@mastra/otel-bridge'
+
+const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'my-service',
+        bridge: new OtelBridge(),
+      },
+    },
+  }),
+  agents: { myAgent },
+})
+```
+
+### Combined with Exporters
+
+The bridge can be used alongside exporters. The bridge handles OTEL context, while exporters send data to additional destinations:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability, DefaultExporter } from '@mastra/observability'
+import { OtelBridge } from '@mastra/otel-bridge'
+import { LangfuseExporter } from '@mastra/langfuse'
+
+const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'my-service',
+        bridge: new OtelBridge(), // Handles OTEL context
+        exporters: [
+          new DefaultExporter(), // Studio access
+          new LangfuseExporter({
+            // Additional destination
+            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
+            secretKey: process.env.LANGFUSE_SECRET_KEY,
+          }),
+        ],
+      },
+    },
+  }),
+})
+```
+
+## OpenTelemetry Setup Requirements
+
+The OtelBridge requires an active OpenTelemetry SDK to function. The bridge reads from OTEL's ambient context.
+
+See the [OtelBridge Guide](https://mastra.ai/docs/observability/tracing/bridges/otel) for complete setup instructions, including how to configure OTEL instrumentation and run your application.
+
+## Tags Support
+
+The OtelBridge supports trace tagging for categorization and filtering. Tags are only applied to root spans and are included as the `mastra.tags` attribute on native OTEL spans.
+
+### Usage
+
+```typescript
+const result = await agent.generate('Hello', {
+  tracingOptions: {
+    tags: ['production', 'experiment-v2', 'user-request'],
+  },
+})
+```
+
+### How Tags Are Stored
+
+Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute:
+
+```json
+{
+  "mastra.tags": "[\"production\",\"experiment-v2\",\"user-request\"]"
+}
+```
+
+This format ensures compatibility with all OTEL-compatible backends and collectors.
+
+## Related
+
+- [OtelBridge Guide](https://mastra.ai/docs/observability/tracing/bridges/otel) - Setup guide with examples
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - General tracing concepts
+- [OtelExporter Reference](https://mastra.ai/reference/observability/tracing/exporters/otel) - OTEL exporter for sending traces

package/.docs/reference/observability/tracing/configuration.md

@@ -0,0 +1,178 @@
+# Configuration
+
+## ObservabilityRegistryConfig
+
+```typescript
+interface ObservabilityRegistryConfig {
+  default?: { enabled?: boolean }
+  configs?: Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>
+  configSelector?: ConfigSelector
+}
+```
+
+## ObservabilityInstanceConfig
+
+```typescript
+interface ObservabilityInstanceConfig {
+  name: string
+  serviceName: string
+  sampling?: SamplingStrategy
+  exporters?: ObservabilityExporter[]
+  spanOutputProcessors?: SpanOutputProcessor[]
+  includeInternalSpans?: boolean
+  requestContextKeys?: string[]
+  serializationOptions?: SerializationOptions
+}
+```
+
+## SerializationOptions
+
+Options for controlling how span data is serialized before export. Use these to customize truncation limits for large payloads.
+
+```typescript
+interface SerializationOptions {
+  maxStringLength?: number
+  maxDepth?: number
+  maxArrayLength?: number
+  maxObjectKeys?: number
+}
+```
+
+## 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: ReadonlyMap<string, ObservabilityInstance>,
+) => string | undefined
+```
+
+## ConfigSelectorOptions
+
+```typescript
+interface ConfigSelectorOptions {
+  requestContext?: RequestContext
+}
+```
+
+# Registry Methods
+
+The Observability class provides methods for managing observability instances:
+
+## registerInstance
+
+```typescript
+registerInstance(
+  name: string,
+  instance: ObservabilityInstance,
+  isDefault?: boolean
+): void;
+```
+
+Registers an observability instance in the registry.
+
+## getInstance
+
+```typescript
+getInstance(name: string): ObservabilityInstance | undefined;
+```
+
+Retrieves an observability instance by name.
+
+## getDefaultInstance
+
+```typescript
+getDefaultInstance(): ObservabilityInstance | undefined;
+```
+
+Returns the default observability instance.
+
+## getSelectedInstance
+
+```typescript
+getSelectedInstance(
+  options: ConfigSelectorOptions
+): ObservabilityInstance | undefined;
+```
+
+Returns the observability instance selected by the config selector or default.
+
+## listInstances
+
+```typescript
+listInstances(): ReadonlyMap<string, ObservabilityInstance>;
+```
+
+Returns all registered observability instances.
+
+## hasInstance
+
+```typescript
+hasInstance(name: string): boolean;
+```
+
+Checks if an observability instance exists.
+
+## setConfigSelector
+
+```typescript
+setConfigSelector(selector: ConfigSelector): void;
+```
+
+Sets the config selector function.
+
+## unregisterInstance
+
+```typescript
+unregisterInstance(name: string): boolean;
+```
+
+Removes an observability instance from the registry.
+
+## clear
+
+```typescript
+clear(): void;
+```
+
+Clears all instances without shutdown.
+
+## shutdown
+
+```typescript
+async shutdown(): Promise<void>;
+```
+
+Shuts down all observability instances and clears the registry.
+
+## See Also
+
+### Documentation
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - Concepts and usage guide
+- [Sampling Strategies](https://mastra.ai/docs/observability/tracing/overview) - Sampling configuration details
+- [Multi-Config Setup](https://mastra.ai/docs/observability/tracing/overview) - Using multiple configurations
+
+### Reference
+
+- [Tracing Classes](https://mastra.ai/reference/observability/tracing/instances) - Core tracing classes
+- [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces) - Type definitions
+- [Spans Reference](https://mastra.ai/reference/observability/tracing/spans) - Span lifecycle
+
+### Exporters
+
+- [DefaultExporter](https://mastra.ai/reference/observability/tracing/exporters/default-exporter) - Storage configuration
+- [CloudExporter](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter) - Cloud setup
+- [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust) - Braintrust integration
+- [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse) - Langfuse integration
+- [LangSmith](https://mastra.ai/reference/observability/tracing/exporters/langsmith) - LangSmith integration

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

@@ -0,0 +1,141 @@
+# ArizeExporter
+
+Sends Tracing data to Arize Phoenix, Arize AX, or any OpenTelemetry-compatible observability platform that supports OpenInference semantic conventions.
+
+## Constructor
+
+```typescript
+new ArizeExporter(config: ArizeExporterConfig)
+```
+
+## ArizeExporterConfig
+
+```typescript
+type ArizeExporterConfig = Omit<OtelExporterConfig, 'provider'> & {
+  // Phoenix / OpenTelemetry configuration
+  endpoint?: string
+  apiKey?: string
+
+  // Arize AX configuration
+  spaceId?: string
+
+  // Common configuration
+  projectName?: string
+  headers?: Record<string, string>
+}
+```
+
+Inherits from `OtelExporterConfig` (excluding `provider`), which includes:
+
+- `timeout?: number` - Export timeout in milliseconds (default: 30000)
+- `batchSize?: number` - Number of spans per batch (default: 512)
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: WARN)
+- `resourceAttributes?: Record<string, any>` - Custom resource attributes
+
+### Metadata passthrough
+
+Non-reserved span attributes are serialized into the OpenInference `metadata` payload. Add them via `tracingOptions.metadata` (e.g., `companyId`, `tier`). Reserved fields such as `input`, `output`, `sessionId`, thread/user IDs, and OpenInference IDs are excluded automatically.
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to the configured endpoint.
+
+### export
+
+```typescript
+async export(spans: ReadOnlySpan[]): Promise<void>
+```
+
+Batch exports spans using OpenTelemetry with OpenInference semantic conventions.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered spans to the configured endpoint 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 { ArizeExporter } from '@mastra/arize'
+
+// For Phoenix: Set PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
+// For Arize AX: Set ARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME
+const exporter = new ArizeExporter()
+```
+
+### Phoenix Configuration
+
+```typescript
+import { ArizeExporter } from '@mastra/arize'
+
+const exporter = new ArizeExporter({
+  endpoint: 'http://localhost:6006/v1/traces',
+  apiKey: process.env.PHOENIX_API_KEY, // Optional for local Phoenix
+  projectName: 'my-ai-project',
+})
+```
+
+### Arize AX Configuration
+
+```typescript
+import { ArizeExporter } from '@mastra/arize'
+
+const exporter = new ArizeExporter({
+  spaceId: process.env.ARIZE_SPACE_ID!,
+  apiKey: process.env.ARIZE_API_KEY!,
+  projectName: 'my-ai-project',
+})
+```
+
+## OpenInference Semantic Conventions
+
+The ArizeExporter implements [OpenInference Semantic Conventions](https://github.com/Arize-ai/openinference/tree/main/spec) for generative AI applications, providing standardized trace structure across different observability platforms.
+
+## Tags Support
+
+The ArizeExporter supports trace tagging for categorization and filtering. Tags are only applied to root spans and are mapped to the native OpenInference `tag.tags` semantic convention.
+
+### Usage
+
+```typescript
+const result = await agent.generate('Hello', {
+  tracingOptions: {
+    tags: ['production', 'experiment-v2', 'user-request'],
+  },
+})
+```
+
+### How Tags Are Stored
+
+Tags are stored using the OpenInference `tag.tags` attribute:
+
+```json
+{
+  "tag.tags": ["production", "experiment-v2", "user-request"]
+}
+```
+
+## Related
+
+- [ArizeExporter Documentation](https://mastra.ai/docs/observability/tracing/exporters/arize)
+- [Phoenix Documentation](https://docs.arize.com/phoenix)
+- [Arize AX Documentation](https://docs.arize.com/)

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

@@ -0,0 +1,93 @@
+# BraintrustExporter
+
+Sends Tracing data to Braintrust for eval and observability.
+
+## Constructor
+
+```typescript
+new BraintrustExporter(config: BraintrustExporterConfig)
+```
+
+## BraintrustExporterConfig
+
+```typescript
+interface BraintrustExporterConfig extends BaseExporterConfig {
+  apiKey?: string
+  endpoint?: string
+  projectName?: string
+  tuningParameters?: Record<string, 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 Braintrust.
+
+### export
+
+```typescript
+async export(spans: ReadOnlySpan[]): Promise<void>
+```
+
+Batch exports spans to Braintrust.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered spans to Braintrust 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 { BraintrustExporter } from '@mastra/braintrust'
+
+// Reads from BRAINTRUST_API_KEY, BRAINTRUST_ENDPOINT
+const exporter = new BraintrustExporter()
+```
+
+### Explicit Configuration
+
+```typescript
+import { BraintrustExporter } from '@mastra/braintrust'
+
+const exporter = new BraintrustExporter({
+  apiKey: process.env.BRAINTRUST_API_KEY,
+  projectName: 'my-ai-project',
+})
+```
+
+## Span Type Mapping
+
+| Span Type                   | Braintrust Type |
+| --------------------------- | --------------- |
+| `MODEL_GENERATION`          | `llm`           |
+| `MODEL_CHUNK`               | `llm`           |
+| `TOOL_CALL`                 | `tool`          |
+| `MCP_TOOL_CALL`             | `tool`          |
+| `WORKFLOW_CONDITIONAL_EVAL` | `function`      |
+| `WORKFLOW_WAIT_EVENT`       | `function`      |
+| All others                  | `task`          |

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

@@ -0,0 +1,163 @@
+# CloudExporter
+
+Sends traces to Mastra Cloud for online visualization and monitoring.
+
+## Constructor
+
+```typescript
+new CloudExporter(config?: CloudExporterConfig)
+```
+
+## CloudExporterConfig
+
+```typescript
+interface CloudExporterConfig extends BaseExporterConfig {
+  /** 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 observability endpoint */
+  endpoint?: string
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+## Environment Variables
+
+The exporter reads these environment variables if not provided in config:
+
+- `MASTRA_CLOUD_ACCESS_TOKEN` - Project-scoped access token for authentication (generate in your Mastra Cloud project under **Project Settings → Access Tokens**)
+- `MASTRA_CLOUD_TRACES_ENDPOINT` - Custom endpoint (defaults to `https://api.mastra.ai/ai/spans/publish`)
+
+## Properties
+
+```typescript
+readonly name = 'mastra-cloud-observability-exporter';
+```
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Processes tracing events. Only exports SPAN\_ENDED events to Cloud.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered events to Mastra Cloud 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 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/observability'
+
+// Uses environment variable for token
+const exporter = new CloudExporter()
+
+// Explicit configuration
+const customExporter = new CloudExporter({
+  accessToken: 'your-token',
+  maxBatchSize: 500,
+  maxBatchWaitMs: 2000,
+  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
+
+- [DefaultExporter](https://mastra.ai/reference/observability/tracing/exporters/default-exporter) - Storage persistence
+- [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