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

package/.docs/docs/observability/tracing/exporters/cloud.md

@@ -0,0 +1,127 @@
+# 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.
+
+## Configuration
+
+### Prerequisites
+
+1. **Mastra Cloud Account**: Sign up at [cloud.mastra.ai](https://cloud.mastra.ai)
+2. **Mastra Cloud Project**: Create a project in Mastra Cloud. Traces are scoped per project, so even if you only want observability, you need a project to act as the destination for your traces.
+3. **Access Token**: Generate in your project's sidebar under **Project Settings → Access Tokens**
+4. **Environment Variables**: Set your credentials:
+
+```bash
+MASTRA_CLOUD_ACCESS_TOKEN=mst_xxxxxxxxxxxxxxxx
+```
+
+### Basic Setup
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability, CloudExporter } from '@mastra/observability'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      production: {
+        serviceName: 'my-service',
+        exporters: [
+          new CloudExporter(), // Uses MASTRA_CLOUD_ACCESS_TOKEN env var
+        ],
+      },
+    },
+  }),
+})
+```
+
+### Recommended Configuration
+
+Include CloudExporter in your observability configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [
+          new DefaultExporter(),
+          new CloudExporter(), // Sends traces to Mastra Cloud (requires MASTRA_CLOUD_ACCESS_TOKEN)
+        ],
+        spanOutputProcessors: [new SensitiveDataFilter()],
+      },
+    },
+  }),
+})
+```
+
+### 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 the project associated with your access token
+
+3. Go to **Observability → Traces**
+
+4. Use filters to find specific traces:
+
+   - Service name
+   - Time range
+   - Trace ID
+   - Error status
+
+> **Note:** Traces are scoped to the project that issued the access token. To view traces, make sure you're viewing the same project you generated the token from.
+
+### Features
+
+- **Trace Timeline** - Visual execution flow
+- **Span Details** - Inputs, outputs, metadata
+- **Performance Metrics** - Latency, token usage
+- **Team Collaboration** - Share trace links
+
+## Performance
+
+> **Info:** CloudExporter uses intelligent batching to optimize network usage. Traces are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
+
+### 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
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
+- [DefaultExporter](https://mastra.ai/docs/observability/tracing/exporters/default)
+- [Mastra Cloud Documentation](https://mastra.ai/docs/mastra-cloud/overview)

package/.docs/docs/observability/tracing/exporters/datadog.md

@@ -0,0 +1,187 @@
+# Datadog Exporter
+
+[Datadog](https://datadoghq.com/) is a comprehensive monitoring platform with dedicated LLM Observability features. The Datadog exporter sends your traces to Datadog's LLM Observability product, providing insights into model performance, token usage, and conversation flows.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/datadog@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/datadog@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/datadog@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/datadog@latest
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **Datadog Account**: Sign up at [datadoghq.com](https://datadoghq.com/) with LLM Observability enabled
+2. **API Key**: Get your API key from Datadog Organization Settings → API Keys
+3. **Environment Variables**: Set your credentials
+
+```bash
+DD_API_KEY=your-datadog-api-key
+DD_LLMOBS_ML_APP=my-llm-app
+DD_SITE=datadoghq.com  # Optional: defaults to datadoghq.com
+DD_ENV=production      # Optional: environment name
+```
+
+### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { DatadogExporter } from '@mastra/datadog'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      datadog: {
+        serviceName: 'my-service',
+        exporters: [new DatadogExporter()],
+      },
+    },
+  }),
+})
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { DatadogExporter } from '@mastra/datadog'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      datadog: {
+        serviceName: 'my-service',
+        exporters: [
+          new DatadogExporter({
+            mlApp: process.env.DD_LLMOBS_ML_APP!,
+            apiKey: process.env.DD_API_KEY!,
+          }),
+        ],
+      },
+    },
+  }),
+})
+```
+
+## Configuration Options
+
+### Complete Configuration
+
+```typescript
+new DatadogExporter({
+  // Required settings
+  mlApp: process.env.DD_LLMOBS_ML_APP!, // Groups traces under this ML app name
+  apiKey: process.env.DD_API_KEY!, // Required for agentless mode (default)
+
+  // Optional settings
+  site: 'datadoghq.com', // Datadog site (datadoghq.eu, us3.datadoghq.com, etc.)
+  service: 'my-service', // Service name (defaults to mlApp)
+  env: 'production', // Environment name
+  agentless: true, // true = direct HTTPS, false = local Datadog Agent
+
+  // Advanced settings
+  integrationsEnabled: false, // Enable dd-trace auto-instrumentation
+
+  // Diagnostic logging
+  logLevel: 'info', // debug | info | warn | error
+})
+```
+
+### With Local Datadog Agent
+
+If you have a Datadog Agent running locally, you can route traces through it instead of direct HTTPS:
+
+```typescript
+new DatadogExporter({
+  mlApp: process.env.DD_LLMOBS_ML_APP!,
+  agentless: false, // Use local Datadog Agent
+  env: 'production',
+})
+```
+
+Note: When using agent mode, the API key is read from the local agent's configuration.
+
+## Span Type Mapping
+
+Mastra span types are automatically mapped to Datadog LLMObs span kinds:
+
+| Mastra SpanType      | Datadog Kind |
+| -------------------- | ------------ |
+| `AGENT_RUN`          | `agent`      |
+| `MODEL_GENERATION`   | `workflow`   |
+| `MODEL_STEP`         | `llm`        |
+| `TOOL_CALL`          | `tool`       |
+| `MCP_TOOL_CALL`      | `tool`       |
+| `WORKFLOW_RUN`       | `workflow`   |
+| Other workflow types | `task`       |
+| `GENERIC`            | `task`       |
+
+Other/future Mastra span types will default to 'task' when mapped unless specified.
+
+## Troubleshooting
+
+### Native module ABI mismatch
+
+If you see errors like:
+
+```text
+Error: No native build was found for runtime=node abi=137 platform=linuxglibc arch=x64
+```
+
+This indicates a Node.js version compatibility issue with `dd-trace`'s native modules. These native modules are **optional** and provide performance monitoring features.
+
+**Solutions:**
+
+1. **Use Node.js 22.x**: Native modules have the best compatibility with Node.js 22.x.
+
+2. **Ignore native module warnings**: The native modules (`@datadog/native-metrics`, `@datadog/native-appsec`, etc.) are optional. If they fail to load, core tracing functionality still works.
+
+### Bundler externals configuration
+
+When using bundlers like esbuild, webpack, or the Mastra CLI bundler, you may need to mark `dd-trace` and its dependencies as external:
+
+```typescript
+export const mastra = new Mastra({
+  bundler: {
+    externals: [
+      'dd-trace',
+      '@datadog/native-metrics',
+      '@datadog/native-appsec',
+      '@datadog/native-iast-taint-tracking',
+      '@datadog/pprof',
+    ],
+  },
+})
+```
+
+## Related
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
+- [Datadog LLM Observability Documentation](https://docs.datadoghq.com/llm_observability/)

package/.docs/docs/observability/tracing/exporters/default.md

@@ -0,0 +1,209 @@
+# Default Exporter
+
+The `DefaultExporter` persists traces to your configured storage backend, making them accessible through Studio. It's automatically enabled when using the default observability configuration and requires no external services.
+
+> **Production Observability:** Observability data can quickly overwhelm general-purpose databases in production. For high-traffic applications, we recommend using **ClickHouse** for the observability storage domain via [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](#production-recommendations) for details.
+
+## Configuration
+
+### Prerequisites
+
+1. **Storage Backend**: Configure a storage provider (libSQL, PostgreSQL, etc.)
+2. **Studio**: Install for viewing traces locally
+
+### Basic Setup
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability, DefaultExporter } from '@mastra/observability'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: 'file:./mastra.db', // Required for trace persistence
+  }),
+  observability: new Observability({
+    configs: {
+      local: {
+        serviceName: 'my-service',
+        exporters: [new DefaultExporter()],
+      },
+    },
+  }),
+})
+```
+
+### Recommended Configuration
+
+Include DefaultExporter in your observability configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: 'file:./mastra.db',
+  }),
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [
+          new DefaultExporter(), // Persists traces to storage for Mastra Studio
+          new CloudExporter(), // Sends traces to Mastra Cloud (requires MASTRA_CLOUD_ACCESS_TOKEN)
+        ],
+        spanOutputProcessors: [new SensitiveDataFilter()],
+      },
+    },
+  }),
+})
+```
+
+## Viewing Traces
+
+### Studio
+
+Access your traces through Studio:
+
+1. Start Studio
+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. Some providers support observability for production workloads, while others are intended primarily for local development.
+
+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.
+
+### Providers with Observability Support
+
+| Storage Provider                                                 | Preferred Strategy | Supported Strategies            | Recommended Use                       |
+| ---------------------------------------------------------------- | ------------------ | ------------------------------- | ------------------------------------- |
+| **ClickHouse** (`@mastra/clickhouse`)                            | insert-only        | insert-only                     | Production (high-volume)              |
+| **[PostgreSQL](https://mastra.ai/reference/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
+| **[MSSQL](https://mastra.ai/reference/storage/mssql)**           | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
+| **[MongoDB](https://mastra.ai/reference/storage/mongodb)**       | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
+| **[libSQL](https://mastra.ai/reference/storage/libsql)**         | batch-with-updates | batch-with-updates, insert-only | Default storage, good for development |
+
+### Providers without Observability Support
+
+The following storage providers **do not support** the observability domain. If you're using one of these providers and need observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider:
+
+- [Convex](https://mastra.ai/reference/storage/convex)
+- [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
+- [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
+- [Cloudflare Durable Objects](https://mastra.ai/reference/storage/cloudflare)
+- [Upstash](https://mastra.ai/reference/storage/upstash)
+- [LanceDB](https://mastra.ai/reference/storage/lance)
+
+### 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
+
+## Production Recommendations
+
+Observability data grows quickly in production environments. A single agent interaction can generate hundreds of spans, and high-traffic applications can produce thousands of traces per day. Most general-purpose databases aren't optimized for this write-heavy, append-only workload.
+
+### Recommended: ClickHouse for High-Volume Production
+
+[ClickHouse](https://mastra.ai/reference/storage/composite) is a columnar database designed for high-volume analytics workloads. It's the recommended choice for production observability because:
+
+- **Optimized for writes**: Handles millions of inserts per second
+- **Efficient compression**: Reduces storage costs for trace data
+- **Fast queries**: Columnar storage enables quick trace lookups and aggregations
+- **Time-series native**: Built-in support for time-based data retention and partitioning
+
+### Using Composite Storage
+
+If you're using a provider without observability support (like Convex or DynamoDB) or want to optimize performance, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to ClickHouse while keeping other data in your primary database.
+
+## 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
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
+- [CloudExporter](https://mastra.ai/docs/observability/tracing/exporters/cloud)
+- [Composite Storage](https://mastra.ai/reference/storage/composite) - Combine multiple storage providers
+- [Storage Configuration](https://mastra.ai/docs/memory/storage)

package/.docs/docs/observability/tracing/exporters/laminar.md

@@ -0,0 +1,100 @@
+# Laminar Exporter
+
+[Laminar](https://laminar.sh/) is an open-source platform for engineering LLM products. The Laminar exporter sends your Mastra traces to Laminar via OTLP/HTTP (protobuf), with Laminar-native span attributes for correct rendering (paths, inputs/outputs, tags, metadata).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/laminar@beta
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/laminar@beta
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/laminar@beta
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/laminar@beta
+```
+
+## Configuration
+
+### Prerequisites
+
+1. **Laminar Project**: Create/select a project in Laminar
+2. **Project API Key**: Copy from Laminar Project Settings
+3. **Environment Variables**: Set your credentials
+
+```bash
+# Required
+LMNR_PROJECT_API_KEY=lmnr_...
+
+# Optional
+LMNR_BASE_URL=https://api.lmnr.ai
+LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces
+```
+
+### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { LaminarExporter } from '@mastra/laminar'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      laminar: {
+        serviceName: 'my-service',
+        exporters: [new LaminarExporter()],
+      },
+    },
+  }),
+})
+```
+
+### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { LaminarExporter } from '@mastra/laminar'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      laminar: {
+        serviceName: 'my-service',
+        exporters: [
+          new LaminarExporter({
+            apiKey: process.env.LMNR_PROJECT_API_KEY!,
+            baseUrl: process.env.LMNR_BASE_URL, // Optional
+            endpoint: process.env.LAMINAR_ENDPOINT, // Optional
+            realtime: process.env.NODE_ENV === 'development', // Optional
+          }),
+        ],
+      },
+    },
+  }),
+})
+```
+
+## Related
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
+- [Laminar Documentation](https://docs.laminar.sh)