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

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

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

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

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

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

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