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

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

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

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

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

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