@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.0

package/.docs/raw/observability/overview.mdx

@@ -1,11 +1,16 @@
 ---
 title: "Observability Overview | Observability"
 description: Monitor and debug applications with Mastra's Observability features.
+packages:
+  - "@mastra/core"
+  - "@mastra/libsql"
+  - "@mastra/loggers"
+  - "@mastra/observability"
 ---
 
 # Observability Overview
 
-Mastra provides comprehensive observability features designed specifically for AI applications. Monitor LLM operations, trace agent decisions, and debug complex workflows with specialized tools that understand AI-specific patterns.
+Mastra provides observability features for AI applications. Monitor LLM operations, trace agent decisions, and debug complex workflows with tools that understand AI-specific patterns.
 
 ## Key Features
 
@@ -16,7 +21,7 @@ Specialized tracing for AI operations that captures:
 - **Model interactions**: Token usage, latency, prompts, and completions
 - **Agent execution**: Decision paths, tool calls, and memory operations
 - **Workflow steps**: Branching logic, parallel execution, and step outputs
-- **Automatic instrumentation**: Zero-configuration tracing with decorators
+- **Automatic instrumentation**: Tracing with decorators
 
 ## Quick Start
 
@@ -25,18 +30,33 @@ Configure Observability in your Mastra instance:
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { PinoLogger } from "@mastra/loggers";
-import { LibSqlStorage } from "@mastra/libsql";
-import { Observability } from "@mastra/observability";
+import { LibSQLStore } from "@mastra/libsql";
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from "@mastra/observability";
 
 export const mastra = new Mastra({
-  // ... other config
   logger: new PinoLogger(),
   storage: new LibSQLStore({
     id: 'mastra-storage',
     url: "file:./mastra.db", // Storage is required for tracing
   }),
-  observability: new Observability({ // Enables Tracing
-    default: { enabled: true },
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: "mastra",
+        exporters: [
+          new DefaultExporter(), // Persists traces to storage for Mastra Studio
+          new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
+        ],
+        spanOutputProcessors: [
+          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
+        ],
+      },
+    },
   }),
 });
 ```

package/.docs/raw/observability/tracing/bridges/otel.mdx

@@ -1,6 +1,10 @@
 ---
 title: "OpenTelemetry Bridge | Tracing | Observability"
 description: "Integrate Mastra tracing with existing OpenTelemetry infrastructure"
+packages:
+  - "@mastra/core"
+  - "@mastra/observability"
+  - "@mastra/otel-bridge"
 ---
 
 # OpenTelemetry Bridge
@@ -70,7 +74,7 @@ Using the OtelBridge requires two steps:
 
 Create an instrumentation file that initializes OTEL. This must run before your application code:
 
-```typescript title="instrumentation.ts" showLineNumbers copy
+```typescript title="instrumentation.ts"
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
@@ -99,7 +103,7 @@ export { sdk };
 
 Add the OtelBridge to your Mastra observability config:
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { Observability } from "@mastra/observability";
 import { OtelBridge } from "@mastra/otel-bridge";
@@ -171,8 +175,7 @@ Both services must have:
 Tags help you categorize and filter traces in your OTEL backend. Add tags when executing agents or workflows:
 
 ```typescript
-const result = await agent.generate({
-  messages: [{ role: "user", content: "Hello" }],
+const result = await agent.generate("Hello", {
   tracingOptions: {
     tags: ["production", "experiment-v2", "user-request"],
   },

package/.docs/raw/observability/tracing/exporters/arize.mdx

@@ -1,6 +1,10 @@
 ---
 title: "Arize Exporter | Tracing | Observability"
 description: "Send traces to Arize Phoenix or Arize AX using OpenTelemetry and OpenInference"
+packages:
+  - "@mastra/arize"
+  - "@mastra/core"
+  - "@mastra/observability"
 ---
 
 # Arize Exporter
@@ -27,12 +31,38 @@ Phoenix is an open-source observability platform that can be self-hosted or used
 4. **Environment Variables**: Set your configuration
 
 ```bash title=".env"
+# Required
 PHOENIX_ENDPOINT=http://localhost:6006/v1/traces  # Or your Phoenix Cloud URL
-PHOENIX_API_KEY=your-api-key  # Optional for local instances
-PHOENIX_PROJECT_NAME=mastra-service  # Optional, defaults to 'mastra-service'
+
+# Optional
+PHOENIX_API_KEY=your-api-key  # For authenticated Phoenix instances
+PHOENIX_PROJECT_NAME=mastra-service  # Defaults to 'mastra-service'
+```
+
+#### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { ArizeExporter } from "@mastra/arize";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      arize: {
+        serviceName: "mastra-service",
+        exporters: [new ArizeExporter()],
+      },
+    },
+  }),
+});
 ```
 
-#### Basic Setup
+#### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
@@ -85,12 +115,38 @@ Arize AX is an enterprise observability platform with advanced features for prod
 4. **Environment Variables**: Set your credentials
 
 ```bash title=".env"
+# Required
 ARIZE_SPACE_ID=your-space-id
 ARIZE_API_KEY=your-api-key
-ARIZE_PROJECT_NAME=mastra-service  # Optional
+
+# Optional
+ARIZE_PROJECT_NAME=mastra-service
+```
+
+#### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { ArizeExporter } from "@mastra/arize";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      arize: {
+        serviceName: "mastra-service",
+        exporters: [new ArizeExporter()],
+      },
+    },
+  }),
+});
 ```
 
-#### Basic Setup
+#### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
@@ -203,25 +259,6 @@ Reserved fields such as `input`, `output`, `sessionId`, thread/user IDs, and Ope
 
 This exporter implements the [OpenInference Semantic Conventions](https://github.com/Arize-ai/openinference/tree/main/spec) for generative AI applications, providing standardized trace structure across different observability platforms.
 
-## Using Tags
-
-Tags help you categorize and filter traces in Phoenix and Arize AX. Add tags when executing agents or workflows:
-
-```typescript
-const result = await agent.generate({
-  messages: [{ role: "user", content: "Hello" }],
-  tracingOptions: {
-    tags: ["production", "experiment-v2", "user-request"],
-  },
-});
-```
-
-Tags appear as the `tag.tags` attribute following OpenInference conventions and can be used to filter and search traces. Common use cases include:
-
-- Environment labels: `"production"`, `"staging"`
-- Experiment tracking: `"experiment-v1"`, `"control-group"`
-- Priority levels: `"priority-high"`, `"batch-job"`
-
 ## Related
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)

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

@@ -1,6 +1,10 @@
 ---
 title: "Braintrust Exporter | Tracing | Observability"
 description: "Send traces to Braintrust for evaluation and monitoring"
+packages:
+  - "@mastra/braintrust"
+  - "@mastra/core"
+  - "@mastra/observability"
 ---
 
 # Braintrust Exporter
@@ -24,10 +28,35 @@ npm install @mastra/braintrust@beta
 
 ```bash title=".env"
 BRAINTRUST_API_KEY=sk-xxxxxxxxxxxxxxxx
-BRAINTRUST_PROJECT_NAME=my-project  # Optional, defaults to 'mastra-tracing'
+
+# Optional
+BRAINTRUST_ENDPOINT=https://api.braintrust.dev  # Custom endpoint if needed
+```
+
+### Zero-Config Setup
+
+With environment variables set, use the exporter with no configuration:
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+import { Observability } from "@mastra/observability";
+import { BraintrustExporter } from "@mastra/braintrust";
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      braintrust: {
+        serviceName: "my-service",
+        exporters: [new BraintrustExporter()],
+      },
+    },
+  }),
+});
 ```
 
-### Basic Setup
+### Explicit Configuration
+
+You can also pass credentials directly (takes precedence over environment variables):
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
@@ -42,7 +71,7 @@ export const mastra = new Mastra({
         exporters: [
           new BraintrustExporter({
             apiKey: process.env.BRAINTRUST_API_KEY,
-            projectName: process.env.BRAINTRUST_PROJECT_NAME,
+            projectName: "my-project",
           }),
         ],
       },
@@ -65,25 +94,6 @@ new BraintrustExporter({
 });
 ```
 
-## Using Tags
-
-Tags help you categorize and filter traces in the Braintrust dashboard. Add tags when executing agents or workflows:
-
-```typescript
-const result = await agent.generate({
-  messages: [{ role: "user", content: "Hello" }],
-  tracingOptions: {
-    tags: ["production", "experiment-v2", "user-request"],
-  },
-});
-```
-
-Tags appear in Braintrust's trace view and can be used to filter and search traces. Common use cases include:
-
-- Environment labels: `"production"`, `"staging"`
-- Experiment tracking: `"experiment-v1"`, `"control-group"`
-- Priority levels: `"priority-high"`, `"batch-job"`
-
 ## Related
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)

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

@@ -1,6 +1,9 @@
 ---
 title: "Cloud Exporter | Tracing | Observability"
 description: "Send traces to Mastra Cloud for production monitoring"
+packages:
+  - "@mastra/core"
+  - "@mastra/observability"
 ---
 
 # Cloud Exporter
@@ -39,17 +42,33 @@ export const mastra = new Mastra({
 });
 ```
 
-### Automatic Configuration
+### Recommended Configuration
 
-When using the default observability configuration, CloudExporter is automatically included if the access token is set:
+Include CloudExporter in your observability configuration:
 
 ```typescript
 import { Mastra } from "@mastra/core";
-import { Observability } from "@mastra/observability";
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from "@mastra/observability";
 
 export const mastra = new Mastra({
   observability: new Observability({
-    default: { enabled: true }, // Automatically includes CloudExporter if token exists
+    configs: {
+      default: {
+        serviceName: "mastra",
+        exporters: [
+          new DefaultExporter(),
+          new CloudExporter(), // Sends traces to Mastra Cloud (requires MASTRA_CLOUD_ACCESS_TOKEN)
+        ],
+        spanOutputProcessors: [
+          new SensitiveDataFilter(),
+        ],
+      },
+    },
   }),
 });
 ```
@@ -112,4 +131,4 @@ CloudExporter uses intelligent batching to optimize network usage. Traces are bu
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [DefaultExporter](/docs/v1/observability/tracing/exporters/default)
-- [Mastra Cloud Documentation](/docs/v1/deployment/mastra-cloud/overview)
+- [Mastra Cloud Documentation](/docs/v1/mastra-cloud/overview)

package/.docs/raw/observability/tracing/exporters/datadog.mdx

@@ -0,0 +1,175 @@
+---
+title: "Datadog Exporter | Tracing | Observability"
+description: "Send traces to Datadog for LLM observability and analytics"
+packages:
+  - "@mastra/core"
+  - "@mastra/observability"
+---
+
+# 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
+
+```bash npm2yarn
+npm install @mastra/datadog@beta
+```
+
+## 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 title=".env"
+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 title="src/mastra/index.ts"
+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 title="src/mastra/index.ts"
+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:
+
+```
+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 title="src/mastra/index.ts"
+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](/docs/v1/observability/tracing/overview)
+- [Datadog LLM Observability Documentation](https://docs.datadoghq.com/llm_observability/)

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

@@ -1,6 +1,10 @@
 ---
 title: "Default Exporter | Tracing | Observability"
 description: "Store traces locally for development and debugging"
+packages:
+  - "@mastra/core"
+  - "@mastra/libsql"
+  - "@mastra/observability"
 ---
 
 # Default Exporter
@@ -11,7 +15,7 @@ The `DefaultExporter` persists traces to your configured storage backend, making
 
 ### Prerequisites
 
-1. **Storage Backend**: Configure a storage provider (LibSQL, PostgreSQL, etc.)
+1. **Storage Backend**: Configure a storage provider (libSQL, PostgreSQL, etc.)
 2. **Studio**: Install for viewing traces locally
 
 ### Basic Setup
@@ -37,21 +41,38 @@ export const mastra = new Mastra({
 });
 ```
 
-### Automatic Configuration
+### Recommended Configuration
 
-When using the default observability configuration, DefaultExporter is automatically included:
+Include DefaultExporter in your observability configuration:
 
 ```typescript
 import { Mastra } from "@mastra/core";
-import { Observability } from "@mastra/observability";
+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({
-    default: { enabled: true }, // Automatically includes DefaultExporter
+    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(),
+        ],
+      },
+    },
   }),
 });
 ```
@@ -102,7 +123,7 @@ If you set the strategy to `'auto'`, the `DefaultExporter` automatically selects
 
 | Storage Provider                                | Preferred Strategy | Supported Strategies                      | Notes                                 |
 | ----------------------------------------------- | ------------------ | ----------------------------------------- | ------------------------------------- |
-| **[LibSQL](/reference/v1/storage/libsql)**         | batch-with-updates | realtime, batch-with-updates, insert-only | Default storage, good for development |
+| **[libSQL](/reference/v1/storage/libsql)**         | batch-with-updates | realtime, batch-with-updates, insert-only | Default storage, good for development |
 | **[PostgreSQL](/reference/v1/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only           | Recommended for production            |
 
 ### Strategy Benefits
@@ -160,4 +181,4 @@ new DefaultExporter({
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [CloudExporter](/docs/v1/observability/tracing/exporters/cloud)
-- [Storage Configuration](/docs/v1/server-db/storage)
+- [Storage Configuration](/docs/v1/memory/storage)