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

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

@@ -0,0 +1,116 @@
+---
+title: "LangfuseExporter | Exporters | AI Tracing | Reference"
+description: Langfuse exporter for AI tracing
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# LangfuseExporter
+
+Sends AI tracing data to Langfuse for observability.
+
+## Constructor
+
+```typescript
+new LangfuseExporter(config: LangfuseExporterConfig)
+```
+
+## LangfuseExporterConfig
+
+```typescript
+interface LangfuseExporterConfig {
+  publicKey?: string;
+  secretKey?: string;
+  baseUrl?: string;
+  realtime?: boolean;
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+  options?: any;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "publicKey",
+      type: "string",
+      description: "Langfuse API key",
+      required: false,
+    },
+    {
+      name: "secretKey",
+      type: "string",
+      description: "Langfuse secret key",
+      required: false,
+    },
+    {
+      name: "baseUrl",
+      type: "string",
+      description: "Langfuse host URL",
+      required: false,
+    },
+    {
+      name: "realtime",
+      type: "boolean",
+      description: "Enable realtime mode - flushes after each event",
+      required: false,
+    },
+    {
+      name: "logLevel",
+      type: "'debug' | 'info' | 'warn' | 'error'",
+      description: "Logger level (default: 'warn')",
+      required: false,
+    },
+    {
+      name: "options",
+      type: "any",
+      description: "Additional Langfuse client options",
+      required: false,
+    },
+  ]}
+/>
+
+## Methods
+
+### exportEvent
+
+```typescript
+async exportEvent(event: AITracingEvent): Promise<void>
+```
+
+Exports a tracing event to Langfuse.
+
+### export
+
+```typescript
+async export(spans: ReadOnlyAISpan[]): Promise<void>
+```
+
+Batch exports spans to Langfuse.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending data and shuts down the client.
+
+## Usage
+
+```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
+- `LLM_GENERATION` spans → Langfuse generations
+- All other spans → Langfuse spans
+- Event spans → Langfuse events

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

@@ -0,0 +1,112 @@
+---
+title: "LangSmithExporter | Exporters | AI Tracing | Reference"
+description: LangSmith exporter for AI tracing
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+
+# LangSmithExporter
+
+Sends AI tracing data to LangSmith for observability.
+
+## Constructor
+
+```typescript
+new LangSmithExporter(config: LangSmithExporterConfig)
+```
+
+## LangSmithExporterConfig
+
+```typescript
+interface LangSmithExporterConfig extends ClientConfig {
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+  client?: Client;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "apiKey",
+      type: "string",
+      description: "LangSmith API key",
+      required: false,
+    },
+    {
+      name: "apiUrl",
+      type: "string",
+      description: "LangSmith API URL",
+      required: false,
+    },
+    {
+      name: "callerOptions",
+      type: "object",
+      description: "HTTP client configuration options",
+      required: false,
+    },
+    {
+      name: "hideInputs",
+      type: "boolean",
+      description: "Hide input data in the LangSmith UI",
+      required: false,
+    },
+    {
+      name: "hideOutputs",
+      type: "boolean",
+      description: "Hide output data in the LangSmith UI",
+      required: false,
+    },
+    {
+      name: "logLevel",
+      type: "'debug' | 'info' | 'warn' | 'error'",
+      description: "Logger level (default: 'warn')",
+      required: false,
+    },
+    {
+      name: "client",
+      type: "Client",
+      description: "Pre-configured LangSmith client instance",
+      required: false,
+    },
+  ]}
+/>
+
+## Methods
+
+### exportEvent
+
+```typescript
+async exportEvent(event: AITracingEvent): Promise<void>
+```
+
+Exports a tracing event to LangSmith.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Ends all active spans and clears the trace map.
+
+## Usage
+
+```typescript
+import { LangSmithExporter } from '@mastra/langsmith';
+
+const exporter = new LangSmithExporter({
+  apiKey: process.env.LANGSMITH_API_KEY,
+  apiUrl: 'https://api.smith.langchain.com',
+  logLevel: 'info',
+});
+```
+
+## Span Type Mapping
+
+| AI Span Type | LangSmith Type |
+|--------------|----------------|
+| `LLM_GENERATION` | `llm` |
+| `LLM_CHUNK` | `llm` |
+| `TOOL_CALL` | `tool` |
+| `MCP_TOOL_CALL` | `tool` |
+| All others | `chain` |

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

@@ -0,0 +1,355 @@
+---
+title: "OtelExporter | Exporters | AI Tracing | Reference"
+description: OpenTelemetry exporter for AI tracing
+---
+
+import { PropertiesTable } from "@/components/properties-table";
+import { Callout } from "nextra/components";
+
+# OtelExporter
+
+<Callout type="warning">
+The OtelExporter is currently **experimental**. APIs and configuration options may change in future releases.
+</Callout>
+
+Sends AI tracing data to any OpenTelemetry-compatible observability platform using standardized GenAI semantic conventions.
+
+## Constructor
+
+```typescript
+new OtelExporter(config: OtelExporterConfig)
+```
+
+## OtelExporterConfig
+
+```typescript
+interface OtelExporterConfig {
+  provider?: ProviderConfig;
+  timeout?: number;
+  batchSize?: number;
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "provider",
+      type: "ProviderConfig",
+      description: "Provider-specific configuration (see below)",
+      required: true,
+    },
+    {
+      name: "timeout",
+      type: "number",
+      description: "Export timeout in milliseconds (default: 30000)",
+      required: false,
+    },
+    {
+      name: "batchSize",
+      type: "number",
+      description: "Number of spans per batch (default: 100)",
+      required: false,
+    },
+    {
+      name: "logLevel",
+      type: "'debug' | 'info' | 'warn' | 'error'",
+      description: "Logger level (default: 'warn')",
+      required: false,
+    },
+  ]}
+/>
+
+## Provider Configurations
+
+### Dash0Config
+
+```typescript
+interface Dash0Config {
+  apiKey: string;
+  endpoint: string;
+  dataset?: string;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "apiKey",
+      type: "string",
+      description: "Dash0 API key",
+      required: true,
+    },
+    {
+      name: "endpoint",
+      type: "string",
+      description: "Dash0 ingress endpoint (e.g., ingress.us-west-2.aws.dash0.com:4317)",
+      required: true,
+    },
+    {
+      name: "dataset",
+      type: "string",
+      description: "Optional dataset name for data organization",
+      required: false,
+    },
+  ]}
+/>
+
+### SignozConfig
+
+```typescript
+interface SignozConfig {
+  apiKey: string;
+  region?: 'us' | 'eu' | 'in';
+  endpoint?: string;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "apiKey",
+      type: "string",
+      description: "SigNoz ingestion key",
+      required: true,
+    },
+    {
+      name: "region",
+      type: "'us' | 'eu' | 'in'",
+      description: "SigNoz cloud region (default: 'us')",
+      required: false,
+    },
+    {
+      name: "endpoint",
+      type: "string",
+      description: "Custom endpoint for self-hosted SigNoz",
+      required: false,
+    },
+  ]}
+/>
+
+### NewRelicConfig
+
+```typescript
+interface NewRelicConfig {
+  apiKey: string;
+  endpoint?: string;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "apiKey",
+      type: "string",
+      description: "New Relic license key",
+      required: true,
+    },
+    {
+      name: "endpoint",
+      type: "string",
+      description: "Custom endpoint (default: https://otlp.nr-data.net:443/v1/traces)",
+      required: false,
+    },
+  ]}
+/>
+
+### TraceloopConfig
+
+```typescript
+interface TraceloopConfig {
+  apiKey: string;
+  destinationId?: string;
+  endpoint?: string;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "apiKey",
+      type: "string",
+      description: "Traceloop API key",
+      required: true,
+    },
+    {
+      name: "destinationId",
+      type: "string",
+      description: "Optional destination identifier",
+      required: false,
+    },
+    {
+      name: "endpoint",
+      type: "string",
+      description: "Custom endpoint (default: https://api.traceloop.com/v1/traces)",
+      required: false,
+    },
+  ]}
+/>
+
+### LaminarConfig
+
+```typescript
+interface LaminarConfig {
+  apiKey: string;
+  teamId?: string;
+  endpoint?: string;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "apiKey",
+      type: "string",
+      description: "Laminar project API key",
+      required: true,
+    },
+    {
+      name: "teamId",
+      type: "string",
+      description: "Optional team identifier (for backwards compatibility)",
+      required: false,
+    },
+    {
+      name: "endpoint",
+      type: "string",
+      description: "Custom endpoint (default: https://api.lmnr.ai/v1/traces)",
+      required: false,
+    },
+  ]}
+/>
+
+### CustomConfig
+
+```typescript
+interface CustomConfig {
+  endpoint: string;
+  protocol?: 'http/json' | 'http/protobuf' | 'grpc' | 'zipkin';
+  headers?: Record<string, string>;
+}
+```
+
+<PropertiesTable
+  props={[
+    {
+      name: "endpoint",
+      type: "string",
+      description: "OTEL collector endpoint URL",
+      required: true,
+    },
+    {
+      name: "protocol",
+      type: "'http/json' | 'http/protobuf' | 'grpc' | 'zipkin'",
+      description: "Export protocol (default: 'http/json')",
+      required: false,
+    },
+    {
+      name: "headers",
+      type: "Record<string, string>",
+      description: "Custom headers for authentication",
+      required: false,
+    },
+  ]}
+/>
+
+## Methods
+
+### exportEvent
+
+```typescript
+async exportEvent(event: AITracingEvent): Promise<void>
+```
+
+Exports a tracing event to the configured OTEL backend.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending traces and shuts down the exporter.
+
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+import { OtelExporter } from '@mastra/otel-exporter';
+
+const exporter = new OtelExporter({
+  provider: {
+    signoz: {
+      apiKey: process.env.SIGNOZ_API_KEY,
+      region: 'us',
+    }
+  },
+});
+```
+
+### With Custom Endpoint
+
+```typescript
+const exporter = new OtelExporter({
+  provider: {
+    custom: {
+      endpoint: 'https://my-collector.example.com/v1/traces',
+      protocol: 'http/protobuf',
+      headers: {
+        'x-api-key': process.env.API_KEY,
+      },
+    }
+  },
+  timeout: 60000,
+  logLevel: 'debug',
+});
+```
+
+## Span Mapping
+
+The exporter maps Mastra AI spans to OpenTelemetry spans following GenAI semantic conventions:
+
+### Span Names
+- `LLM_GENERATION` → `chat {model}` or `tool_selection {model}`
+- `TOOL_CALL` → `tool.execute {tool_name}`
+- `AGENT_RUN` → `agent.{agent_id}`
+- `WORKFLOW_RUN` → `workflow.{workflow_id}`
+
+### Span Kinds
+- Root agent/workflow spans → `SERVER`
+- LLM calls → `CLIENT`
+- Tool calls → `INTERNAL` or `CLIENT`
+- Workflow steps → `INTERNAL`
+
+### Attributes
+
+The exporter maps to standard OTEL GenAI attributes:
+
+| Mastra Attribute | OTEL Attribute |
+|------------------|----------------|
+| `model` | `gen_ai.request.model` |
+| `provider` | `gen_ai.system` |
+| `inputTokens` / `promptTokens` | `gen_ai.usage.input_tokens` |
+| `outputTokens` / `completionTokens` | `gen_ai.usage.output_tokens` |
+| `temperature` | `gen_ai.request.temperature` |
+| `maxOutputTokens` | `gen_ai.request.max_tokens` |
+| `finishReason` | `gen_ai.response.finish_reasons` |
+
+## Protocol Requirements
+
+Different providers require different OTEL exporter packages:
+
+| Protocol | Required Package | Providers |
+|----------|------------------|-----------|
+| gRPC | `@opentelemetry/exporter-trace-otlp-grpc` | Dash0 |
+| HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | SigNoz, New Relic, Laminar |
+| HTTP/JSON | `@opentelemetry/exporter-trace-otlp-http` | Traceloop, Custom |
+| Zipkin | `@opentelemetry/exporter-zipkin` | Zipkin collectors |
+
+## Parent-Child Relationships
+
+The exporter preserves span hierarchy from Mastra's AI tracing:
+- Uses `parentSpanId` directly from Mastra spans
+- Maintains correct nesting for agents, workflows, LLM calls, and tools
+- Exports complete traces with all relationships intact