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

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

@@ -0,0 +1,121 @@
+---
+title: "Langfuse Exporter | AI Tracing | Observability | Mastra Docs"
+description: "Send AI traces to Langfuse for LLM observability and analytics"
+---
+
+import { Callout } from "nextra/components";
+
+# Langfuse Exporter
+
+[Langfuse](https://langfuse.com/) is an open-source observability platform specifically designed for LLM applications. The Langfuse exporter sends your AI traces to Langfuse, providing detailed insights into model performance, token usage, and conversation flows.
+
+## When to Use Langfuse
+
+Langfuse is ideal when you need:
+- **LLM-specific analytics** - Token usage, costs, latency breakdown
+- **Conversation tracking** - Session-based trace grouping
+- **Quality scoring** - Manual and automated evaluation scores
+- **Model comparison** - A/B testing and version comparisons
+- **Self-hosted option** - Deploy on your own infrastructure
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/langfuse
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **Langfuse Account**: Sign up at [cloud.langfuse.com](https://cloud.langfuse.com) or deploy self-hosted
+2. **API Keys**: Create public/secret key pair in Langfuse Settings → API Keys
+3. **Environment Variables**: Set your credentials
+
+```bash filename=".env"
+LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxx
+LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxx
+LANGFUSE_BASE_URL=https://cloud.langfuse.com  # Or your self-hosted URL
+```
+
+### Basic Setup
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { LangfuseExporter } from "@mastra/langfuse";
+
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      langfuse: {
+        serviceName: 'my-service',
+        exporters: [
+          new LangfuseExporter({
+            publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
+            secretKey: process.env.LANGFUSE_SECRET_KEY!,
+            baseUrl: process.env.LANGFUSE_BASE_URL,
+            options: {
+              environment: process.env.NODE_ENV,
+            },
+          }),
+        ],
+      },
+    },
+  },
+});
+```
+
+## Configuration Options
+
+### Realtime vs Batch Mode
+
+The Langfuse exporter supports two modes for sending traces:
+
+#### Realtime Mode (Development)
+Traces appear immediately in Langfuse dashboard, ideal for debugging:
+
+```typescript
+new LangfuseExporter({
+  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
+  secretKey: process.env.LANGFUSE_SECRET_KEY!,
+  realtime: true,  // Flush after each event
+})
+```
+
+#### Batch Mode (Production)
+Better performance with automatic batching:
+
+```typescript
+new LangfuseExporter({
+  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
+  secretKey: process.env.LANGFUSE_SECRET_KEY!,
+  realtime: false,  // Default - batch traces
+})
+```
+
+### Complete Configuration
+
+```typescript
+new LangfuseExporter({
+  // Required credentials
+  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
+  secretKey: process.env.LANGFUSE_SECRET_KEY!,
+
+  // Optional settings
+  baseUrl: process.env.LANGFUSE_BASE_URL,     // Default: https://cloud.langfuse.com
+  realtime: process.env.NODE_ENV === 'development',  // Dynamic mode selection
+  logLevel: 'info',  // Diagnostic logging: debug | info | warn | error
+
+  // Langfuse-specific options
+  options: {
+    environment: process.env.NODE_ENV,        // Shows in UI for filtering
+    version: process.env.APP_VERSION,         // Track different versions
+    release: process.env.GIT_COMMIT,          // Git commit hash
+  },
+})
+```
+
+## Related
+
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [Langfuse Documentation](https://langfuse.com/docs)

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

@@ -0,0 +1,88 @@
+---
+title: "LangSmith Exporter | AI Tracing | Observability | Mastra Docs"
+description: "Send AI traces to LangSmith for LLM observability and evaluation"
+---
+
+import { Callout } from "nextra/components";
+
+# LangSmith Exporter
+
+[LangSmith](https://smith.langchain.com/) is LangChain's platform for monitoring and evaluating LLM applications. The LangSmith exporter sends your AI traces to LangSmith, providing insights into model performance, debugging capabilities, and evaluation workflows.
+
+## When to Use LangSmith
+
+LangSmith is ideal when you need:
+- **LangChain ecosystem integration** - Native support for LangChain applications
+- **Debugging and testing** - Detailed trace visualization and replay
+- **Evaluation pipelines** - Built-in evaluation and dataset management
+- **Prompt versioning** - Track and compare prompt variations
+- **Collaboration features** - Team workspaces and shared projects
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/langsmith
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **LangSmith Account**: Sign up at [smith.langchain.com](https://smith.langchain.com)
+2. **API Key**: Generate an API key in LangSmith Settings → API Keys
+3. **Environment Variables**: Set your credentials
+
+```bash filename=".env"
+LANGSMITH_API_KEY=ls-xxxxxxxxxxxx
+LANGSMITH_BASE_URL=https://api.smith.langchain.com  # Optional for self-hosted
+```
+
+### Basic Setup
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { LangSmithExporter } from "@mastra/langsmith";
+
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      langsmith: {
+        serviceName: 'my-service',
+        exporters: [
+          new LangSmithExporter({
+            apiKey: process.env.LANGSMITH_API_KEY,
+          }),
+        ],
+      },
+    },
+  },
+});
+```
+
+## Configuration Options
+
+### Complete Configuration
+
+```typescript
+new LangSmithExporter({
+  // Required credentials
+  apiKey: process.env.LANGSMITH_API_KEY!,
+
+  // Optional settings
+  apiUrl: process.env.LANGSMITH_BASE_URL,       // Default: https://api.smith.langchain.com
+  callerOptions: {                              // HTTP client options
+    timeout: 30000,                             // Request timeout in ms
+    maxRetries: 3,                              // Retry attempts
+  },
+  logLevel: 'info',                             // Diagnostic logging: debug | info | warn | error
+
+  // LangSmith-specific options
+  hideInputs: false,                            // Hide input data in UI
+  hideOutputs: false,                           // Hide output data in UI
+})
+```
+
+## Related
+
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [LangSmith Documentation](https://docs.smith.langchain.com/)

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

@@ -0,0 +1,250 @@
+---
+title: "OpenTelemetry Exporter | AI Tracing | Observability | Mastra Docs"
+description: "Send AI traces to any OpenTelemetry-compatible observability platform"
+---
+
+import { Callout } from "nextra/components";
+
+# OpenTelemetry Exporter
+
+<Callout type="warning">
+The OpenTelemetry exporter is currently **experimental**. APIs and configuration options may change in future releases.
+</Callout>
+
+The OpenTelemetry (OTEL) exporter sends your AI traces to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, Dash0, Traceloop, Laminar, and more.
+
+## When to Use OTEL Exporter
+
+The OTEL exporter is ideal when you need:
+- **Platform flexibility** - Send traces to any OTEL-compatible backend
+- **Standards compliance** - Follow OpenTelemetry GenAI semantic conventions
+- **Multi-vendor support** - Configure once, switch providers easily
+- **Enterprise platforms** - Integrate with existing observability infrastructure
+- **Custom collectors** - Send to your own OTEL collector
+
+## Installation
+
+Each provider requires specific protocol packages. Install the base exporter plus the protocol package for your provider:
+
+### For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar)
+
+```bash npm2yarn
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-proto
+```
+
+### For gRPC Providers (Dash0)
+
+```bash npm2yarn
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
+```
+
+### For HTTP/JSON Providers (Traceloop)
+
+```bash npm2yarn
+npm install @mastra/otel-exporter @opentelemetry/exporter-trace-otlp-http
+```
+
+## Provider Configurations
+
+### Dash0
+
+[Dash0](https://www.dash0.com/) provides real-time observability with automatic insights.
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { OtelExporter } from "@mastra/otel-exporter";
+
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      otel: {
+        serviceName: 'my-service',
+        exporters: [
+          new OtelExporter({
+            provider: {
+              dash0: {
+                apiKey: process.env.DASH0_API_KEY,
+                endpoint: process.env.DASH0_ENDPOINT, // e.g., 'ingress.us-west-2.aws.dash0.com:4317'
+                dataset: 'production', // Optional dataset name
+              }
+            },
+          }),
+        ],
+      },
+    },
+  },
+});
+```
+
+<Callout type="info">
+Get your Dash0 endpoint from your dashboard. It should be in the format `ingress.{region}.aws.dash0.com:4317`.
+</Callout>
+
+### SigNoz
+
+[SigNoz](https://signoz.io/) is an open-source APM alternative with built-in AI tracing support.
+
+```typescript filename="src/mastra/index.ts"
+new OtelExporter({
+  provider: {
+    signoz: {
+      apiKey: process.env.SIGNOZ_API_KEY,
+      region: 'us', // 'us' | 'eu' | 'in'
+      // endpoint: 'https://my-signoz.example.com', // For self-hosted
+    }
+  },
+})
+```
+
+### New Relic
+
+[New Relic](https://newrelic.com/) provides comprehensive observability with AI monitoring capabilities.
+
+```typescript filename="src/mastra/index.ts"
+new OtelExporter({
+  provider: {
+    newrelic: {
+      apiKey: process.env.NEW_RELIC_LICENSE_KEY,
+      // endpoint: 'https://otlp.eu01.nr-data.net', // For EU region
+    }
+  },
+})
+```
+
+### Traceloop
+
+[Traceloop](https://www.traceloop.com/) specializes in LLM observability with automatic prompt tracking.
+
+```typescript filename="src/mastra/index.ts"
+new OtelExporter({
+  provider: {
+    traceloop: {
+      apiKey: process.env.TRACELOOP_API_KEY,
+      destinationId: 'my-destination', // Optional
+    }
+  },
+})
+```
+
+### Laminar
+
+[Laminar](https://www.lmnr.ai/) provides specialized LLM observability and analytics.
+
+```typescript filename="src/mastra/index.ts"
+new OtelExporter({
+  provider: {
+    laminar: {
+      apiKey: process.env.LMNR_PROJECT_API_KEY,
+      // teamId: process.env.LAMINAR_TEAM_ID, // Optional, for backwards compatibility
+    }
+  },
+})
+```
+
+### Custom/Generic OTEL Endpoints
+
+For other OTEL-compatible platforms or custom collectors:
+
+```typescript filename="src/mastra/index.ts"
+new OtelExporter({
+  provider: {
+    custom: {
+      endpoint: 'https://your-collector.example.com/v1/traces',
+      protocol: 'http/protobuf', // 'http/json' | 'http/protobuf' | 'grpc'
+      headers: {
+        'x-api-key': process.env.API_KEY,
+      },
+    }
+  },
+})
+```
+
+## Configuration Options
+
+### Complete Configuration
+
+```typescript
+new OtelExporter({
+  // Provider configuration (required)
+  provider: {
+    // Use one of: dash0, signoz, newrelic, traceloop, laminar, custom
+  },
+
+  // Export configuration
+  timeout: 30000,        // Export timeout in milliseconds
+  batchSize: 100,        // Number of spans per batch
+
+  // Debug options
+  logLevel: 'info',      // 'debug' | 'info' | 'warn' | 'error'
+})
+```
+
+## OpenTelemetry Semantic Conventions
+
+The exporter follows [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/), ensuring compatibility with observability platforms:
+
+### Span Naming
+- **LLM Operations**: `chat {model}` or `tool_selection {model}`
+- **Tool Execution**: `tool.execute {tool_name}`
+- **Agent Runs**: `agent.{agent_id}`
+- **Workflow Runs**: `workflow.{workflow_id}`
+
+### Key Attributes
+- `gen_ai.operation.name` - Operation type (chat, tool.execute, etc.)
+- `gen_ai.system` - AI provider (openai, anthropic, etc.)
+- `gen_ai.request.model` - Model identifier
+- `gen_ai.usage.input_tokens` - Number of input tokens
+- `gen_ai.usage.output_tokens` - Number of output tokens
+- `gen_ai.request.temperature` - Sampling temperature
+- `gen_ai.response.finish_reasons` - Completion reason
+
+## Buffering Strategy
+
+The exporter buffers spans until a trace is complete:
+1. Collects all spans for a trace
+2. Waits 5 seconds after root span completes
+3. Exports complete trace with preserved parent-child relationships
+4. Ensures no orphaned spans
+
+## Protocol Selection Guide
+
+Choose the right protocol package based on your provider:
+
+| Provider | Protocol | Required Package |
+|----------|----------|------------------|
+| Dash0 | gRPC | `@opentelemetry/exporter-trace-otlp-grpc` |
+| SigNoz | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
+| New Relic | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
+| Traceloop | HTTP/JSON | `@opentelemetry/exporter-trace-otlp-http` |
+| Laminar | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
+| Custom | Varies | Depends on your collector |
+
+<Callout type="warning">
+Make sure to install the correct protocol package for your provider. The exporter will provide a helpful error message if the wrong package is installed.
+</Callout>
+
+## Troubleshooting
+
+### Missing Dependency Error
+
+If you see an error like:
+```
+HTTP/Protobuf exporter is not installed (required for signoz).
+To use HTTP/Protobuf export, install the required package:
+  npm install @opentelemetry/exporter-trace-otlp-proto
+```
+
+Install the suggested package for your provider.
+
+### Common Issues
+
+1. **Wrong protocol package**: Verify you installed the correct exporter for your provider
+2. **Invalid endpoint**: Check endpoint format matches provider requirements
+3. **Authentication failures**: Verify API keys and headers are correct
+4. **No traces appearing**: Check that traces complete (root span must end)
+
+## Related
+
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [OpenTelemetry GenAI Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
+- [OTEL Exporter Reference](/reference/observability/ai-tracing/exporters/otel)