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

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

@@ -0,0 +1,81 @@
+---
+title: "Braintrust Exporter | AI Tracing | Observability | Mastra Docs"
+description: "Send AI traces to Braintrust for evaluation and monitoring"
+---
+
+import { Callout } from "nextra/components";
+
+# Braintrust Exporter
+
+[Braintrust](https://www.braintrust.dev/) is an evaluation and monitoring platform that helps you measure and improve LLM application quality. The Braintrust exporter sends your AI traces to Braintrust, enabling systematic evaluation, scoring, and experimentation.
+
+## When to Use Braintrust
+
+Braintrust excels at:
+- **Evaluation workflows** - Systematic quality measurement
+- **Experiment tracking** - Compare model versions and prompts
+- **Dataset management** - Curate test cases and golden datasets
+- **Regression testing** - Ensure improvements don't break existing functionality
+- **Team collaboration** - Share experiments and insights
+
+## Installation
+
+```bash npm2yarn
+npm install @mastra/braintrust
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **Braintrust Account**: Sign up at [braintrust.dev](https://www.braintrust.dev/)
+2. **Project**: Create or select a project for your traces
+3. **API Key**: Generate in Braintrust Settings → API Keys
+4. **Environment Variables**: Set your credentials:
+
+```bash filename=".env"
+BRAINTRUST_API_KEY=sk-xxxxxxxxxxxxxxxx
+BRAINTRUST_PROJECT_NAME=my-project  # Optional, defaults to 'mastra-tracing'
+```
+
+### Basic Setup
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { BraintrustExporter } from "@mastra/braintrust";
+
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      braintrust: {
+        serviceName: 'my-service',
+        exporters: [
+          new BraintrustExporter({
+            apiKey: process.env.BRAINTRUST_API_KEY,
+            projectName: process.env.BRAINTRUST_PROJECT_NAME,
+          }),
+        ],
+      },
+    },
+  },
+});
+```
+
+### Complete Configuration
+
+```typescript
+new BraintrustExporter({
+  // Required
+  apiKey: process.env.BRAINTRUST_API_KEY!,
+
+  // Optional settings
+  projectName: 'my-project',          // Default: 'mastra-tracing'
+  endpoint: 'https://api.braintrust.dev',  // Custom endpoint if needed
+  logLevel: 'info',                   // Diagnostic logging: debug | info | warn | error
+})
+```
+
+## Related
+
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [Braintrust Documentation](https://www.braintrust.dev/docs)

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

@@ -0,0 +1,120 @@
+---
+title: "Cloud Exporter | AI Tracing | Observability | Mastra Docs"
+description: "Send traces to Mastra Cloud for production monitoring"
+---
+
+import { Callout } from "nextra/components";
+
+# Cloud Exporter
+
+The `CloudExporter` sends traces to Mastra Cloud for centralized monitoring and team collaboration. It's automatically enabled when using the default observability configuration with a valid access token.
+
+## When to Use CloudExporter
+
+CloudExporter is ideal for:
+- **Production monitoring** - Centralized trace visualization
+- **Team collaboration** - Share traces across your organization
+- **Advanced analytics** - Insights and performance metrics
+- **Zero maintenance** - No infrastructure to manage
+
+## Configuration
+
+### Prerequisites
+
+1. **Mastra Cloud Account**: Sign up at [cloud.mastra.ai](https://cloud.mastra.ai)
+2. **Access Token**: Generate in Mastra Cloud → Settings → API Tokens
+3. **Environment Variables**: Set your credentials:
+
+```bash filename=".env"
+MASTRA_CLOUD_ACCESS_TOKEN=mst_xxxxxxxxxxxxxxxx
+```
+
+### Basic Setup
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { CloudExporter } from "@mastra/core/ai-tracing";
+
+export const mastra = new Mastra({
+  observability: {
+    configs: {
+      production: {
+        serviceName: 'my-service',
+        exporters: [
+          new CloudExporter(),  // Uses MASTRA_CLOUD_ACCESS_TOKEN env var
+        ],
+      },
+    },
+  },
+});
+```
+
+### Automatic Configuration
+
+When using the default observability configuration, CloudExporter is automatically included if the access token is set:
+
+```typescript
+export const mastra = new Mastra({
+  observability: {
+    default: { enabled: true },  // Automatically includes CloudExporter if token exists
+  },
+});
+```
+
+### Complete Configuration
+
+```typescript
+new CloudExporter({
+  // Optional - defaults to env var
+  accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
+
+  // Optional - for self-hosted Mastra Cloud
+  endpoint: 'https://cloud.your-domain.com',
+
+  // Batching configuration
+  maxBatchSize: 1000,     // Max spans per batch
+  maxBatchWaitMs: 5000,   // Max wait before sending batch
+
+  // Diagnostic logging
+  logLevel: 'info',  // debug | info | warn | error
+})
+```
+
+## Viewing Traces
+
+### Mastra Cloud Dashboard
+
+1. Navigate to [cloud.mastra.ai](https://cloud.mastra.ai)
+2. Select your project
+3. Go to Observability → Traces
+4. Use filters to find specific traces:
+   - Service name
+   - Time range
+   - Trace ID
+   - Error status
+
+### Features
+
+- **Trace Timeline** - Visual execution flow
+- **Span Details** - Inputs, outputs, metadata
+- **Performance Metrics** - Latency, token usage
+- **Team Collaboration** - Share trace links
+
+## Performance
+
+<Callout type="info">
+  CloudExporter uses intelligent batching to optimize network usage. Traces are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
+</Callout>
+
+### Batching Behavior
+
+- Traces are batched up to `maxBatchSize` (default: 1000)
+- Batches are sent when full or after `maxBatchWaitMs` (default: 5 seconds)
+- Failed batches are retried with exponential backoff
+- Graceful degradation if Mastra Cloud is unreachable
+
+## Related
+
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [DefaultExporter](/docs/observability/ai-tracing/exporters/default)
+- [Mastra Cloud Documentation](https://cloud.mastra.ai/docs)

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

@@ -0,0 +1,167 @@
+---
+title: "Default Exporter | AI Tracing | Observability | Mastra Docs"
+description: "Store traces locally for development and debugging"
+---
+
+# Default Exporter
+
+The `DefaultExporter` persists traces to your configured storage backend, making them accessible through the Mastra Playground. It's automatically enabled when using the default observability configuration and requires no external services.
+
+## When to Use DefaultExporter
+
+DefaultExporter is ideal for:
+- **Local development** - Debug and analyze traces offline
+- **Data ownership** - Complete control over your trace data
+- **Zero dependencies** - No external services required
+- **Playground integration** - View traces in Mastra Playground UI
+
+## Configuration
+
+### Prerequisites
+
+1. **Storage Backend**: Configure a storage provider (LibSQL, PostgreSQL, etc.)
+2. **Mastra Playground**: Install for viewing traces locally
+
+### Basic Setup
+
+```typescript filename="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { DefaultExporter } from "@mastra/core/ai-tracing";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    url: "file:./mastra.db",  // Required for trace persistence
+  }),
+  observability: {
+    configs: {
+      local: {
+        serviceName: 'my-service',
+        exporters: [
+          new DefaultExporter(),
+        ],
+      },
+    },
+  },
+});
+```
+
+### Automatic Configuration
+
+When using the default observability configuration, DefaultExporter is automatically included:
+
+```typescript
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    url: "file:./mastra.db",
+  }),
+  observability: {
+    default: { enabled: true },  // Automatically includes DefaultExporter
+  },
+});
+```
+
+## Viewing Traces
+
+### Mastra Playground
+
+Access your traces through the local Playground:
+
+1. Start the Playground
+2. Navigate to Observability
+3. Filter and search your local traces
+4. Inspect detailed span information
+
+## Tracing Strategies
+
+DefaultExporter automatically selects the optimal tracing strategy based on your storage provider. You can also override this selection if needed.
+
+### Available Strategies
+
+| Strategy | Description | Use Case |
+|----------|-------------|----------|
+| **realtime** | Process each event immediately | Development, debugging, low traffic |
+| **batch-with-updates** | Buffer events and batch write with full lifecycle support | Low volume Production |
+| **insert-only** | Only process completed spans, ignore updates | High volume Production |
+
+### Strategy Configuration
+
+```typescript
+new DefaultExporter({
+  strategy: 'auto',  // Default - let storage provider decide
+  // or explicitly set:
+  // strategy: 'realtime' | 'batch-with-updates' | 'insert-only'
+
+  // Batching configuration (applies to both batch-with-updates and insert-only)
+  maxBatchSize: 1000,      // Max spans per batch
+  maxBatchWaitMs: 5000,    // Max wait before flushing
+  maxBufferSize: 10000,    // Max spans to buffer
+})
+```
+
+## Storage Provider Support
+
+Different storage providers support different tracing strategies.
+
+If you set the strategy to `'auto'`, the `DefaultExporter` automatically selects the optimal strategy for the storage provider. If you set the strategy to a mode that the storage provider doesn't support, you will get an error message.
+
+| Storage Provider | Preferred Strategy | Supported Strategies | Notes |
+|-----------------|-------------------|---------------------|--------|
+| **[LibSQL](/reference/storage/libsql)** | batch-with-updates | realtime, batch-with-updates, insert-only | Default storage, good for development |
+
+### Strategy Benefits
+
+- **realtime**: Immediate visibility, best for debugging
+- **batch-with-updates**: 10-100x throughput improvement, full span lifecycle
+- **insert-only**: Additional 70% reduction in database operations, perfect for analytics
+
+## Batching Behavior
+
+### Flush Triggers
+
+For both batch strategies (`batch-with-updates` and `insert-only`), traces are flushed to storage when any of these conditions are met:
+
+1. **Size trigger**: Buffer reaches `maxBatchSize` spans
+2. **Time trigger**: `maxBatchWaitMs` elapsed since first event
+3. **Emergency flush**: Buffer approaches `maxBufferSize` limit
+4. **Shutdown**: Force flush all pending events
+
+### Error Handling
+
+The DefaultExporter includes robust error handling for production use:
+
+- **Retry Logic**: Exponential backoff (500ms, 1s, 2s, 4s)
+- **Transient Failures**: Automatic retry with backoff
+- **Persistent Failures**: Drop batch after 4 failed attempts
+- **Buffer Overflow**: Prevent memory issues during storage outages
+
+### Configuration Examples
+
+```typescript
+// Zero config - recommended for most users
+new DefaultExporter()
+
+// Development override
+new DefaultExporter({
+  strategy: 'realtime',  // Immediate visibility for debugging
+})
+
+// High-throughput production
+new DefaultExporter({
+  maxBatchSize: 2000,      // Larger batches
+  maxBatchWaitMs: 10000,   // Wait longer to fill batches
+  maxBufferSize: 50000,    // Handle longer outages
+})
+
+// Low-latency production
+new DefaultExporter({
+  maxBatchSize: 100,       // Smaller batches
+  maxBatchWaitMs: 1000,    // Flush quickly
+})
+```
+
+## Related
+
+- [AI Tracing Overview](/docs/observability/ai-tracing/overview)
+- [CloudExporter](/docs/observability/ai-tracing/exporters/cloud)
+- [Storage Configuration](/docs/storage/overview)

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)