@mastra/mcp-docs-server 1.2.15-alpha.9 → 1.2.16-alpha.1

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

@@ -1,321 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Datadog exporter
-
-[Datadog](https://datadoghq.com/) is a complete monitoring platform with dedicated LLM Observability features. The Datadog exporter sends your traces to Datadog's LLM Observability product, providing insights into model performance and token usage, plus conversation flows.
-
-> **Also using dd-trace APM?:** If you also use `dd-trace` APM auto-instrumentation, consider the [Datadog Bridge](https://mastra.ai/docs/observability/integrations/bridges/datadog) instead. The bridge creates `dd-trace` spans in real time so HTTP and database calls inside tools and processors are correctly nested under their parent Mastra span. The exporter on its own sends LLM Observability data after execution completes, which means auto-instrumented APM spans fall back to the request handler.
-
-## 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 LLM Observability 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.
-
-## Application Performance Monitoring
-
-The sections above cover Mastra's [LLM Observability](https://docs.datadoghq.com/llm_observability/) integration. To trace your Mastra HTTP server routes (request latency, error tracking, service maps), use `dd-trace` directly for Datadog Application Performance Monitoring (APM).
-
-### Prerequisites
-
-1. **Datadog Agent**: Install a [Datadog Agent](https://docs.datadoghq.com/agent/) on the same host or accessible via network. The agent receives traces from `dd-trace` on `localhost:8126` and forwards them to Datadog. Follow the [agent installation guide](https://docs.datadoghq.com/agent/) to set it up.
-
-2. **dd-trace package**: Install the tracing library in your project:
-
-   **npm**:
-
-   ```bash
-   npm install dd-trace
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm add dd-trace
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn add dd-trace
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun add dd-trace
-   ```
-
-> **Note:** APM traces always route through the Datadog Agent. This is different from LLM Observability, which supports agentless mode (direct HTTPS to Datadog).
-
-### APM only
-
-Import and initialize `dd-trace` at the top of your entry file, before any other imports:
-
-```typescript
-import tracer from 'dd-trace'
-
-tracer.init({
-  service: process.env.DD_SERVICE || 'my-mastra-app',
-  env: process.env.DD_ENV || 'production',
-  version: process.env.DD_VERSION,
-})
-
-import { Mastra } from '@mastra/core'
-
-export const mastra = new Mastra({
-  bundler: {
-    externals: [
-      'dd-trace',
-      '@datadog/native-metrics',
-      '@datadog/native-appsec',
-      '@datadog/native-iast-taint-tracking',
-      '@datadog/pprof',
-    ],
-  },
-})
-```
-
-Set the tracer metadata environment variables:
-
-```bash
-DD_SERVICE=my-mastra-app
-DD_ENV=production
-DD_VERSION=1.0.0
-```
-
-`dd-trace` auto-instruments popular HTTP frameworks, including those supported by Mastra's [server adapters](https://mastra.ai/docs/server/server-adapters). Inbound requests, outbound HTTP calls, and database queries appear as APM traces in Datadog.
-
-### APM and LLM Observability
-
-Import and initialize `dd-trace` before creating the Mastra instance. The `DatadogExporter` detects the existing tracer and skips re-initialization, adding LLM Observability on top of your APM setup:
-
-```typescript
-import tracer from 'dd-trace'
-
-tracer.init({
-  service: process.env.DD_SERVICE || 'my-mastra-app',
-  env: process.env.DD_ENV || 'production',
-  version: process.env.DD_VERSION,
-})
-
-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-mastra-app',
-        exporters: [
-          new DatadogExporter({
-            mlApp: process.env.DD_LLMOBS_ML_APP!,
-            apiKey: process.env.DD_API_KEY!,
-          }),
-        ],
-      },
-    },
-  }),
-  bundler: {
-    externals: [
-      'dd-trace',
-      '@datadog/native-metrics',
-      '@datadog/native-appsec',
-      '@datadog/native-iast-taint-tracking',
-      '@datadog/pprof',
-    ],
-  },
-})
-```
-
-```bash
-DD_SERVICE=my-mastra-app
-DD_ENV=production
-DD_VERSION=1.0.0
-DD_API_KEY=your-datadog-api-key
-DD_LLMOBS_ML_APP=my-llm-app
-```
-
-Server routes appear as APM traces and LLM calls appear as LLM Observability spans, all under the same service in Datadog.
-
-> **Note:** Import and initialize `dd-trace` before all other modules. This allows its auto-instrumentation to patch HTTP, database, and framework libraries at load time.
-
-## 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/)
-- [Datadog APM documentation](https://docs.datadoghq.com/tracing/)

package/.docs/docs/observability/integrations/exporters/mastra-platform.md

@@ -1,201 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Mastra platform exporter
-
-The `MastraPlatformExporter` sends traces, logs, metrics, scores, and feedback to the Mastra platform. Use it to route observability data from any Mastra app to a hosted project in the Mastra platform.
-
-> **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` class is still exported from `@mastra/observability` for backward compatibility, but it's deprecated. New code should use `MastraPlatformExporter`.
-
-> **Self-hosted or standalone apps:** If you host your Mastra application on your own infrastructure (not on Mastra platform), you still need a deployed Studio project to view traces, logs, and metrics. `MastraPlatformExporter` sends data to a Studio project, so one must exist before you can use it.
->
-> 1. [Create a Mastra project](https://mastra.ai/guides/getting-started/quickstart) if you don't have one yet.
-> 2. [Deploy Studio](https://mastra.ai/docs/studio/deployment) to the Mastra platform with `mastra studio deploy`.
-> 3. Follow the [quickstart steps below](#quickstart) to create an access token and find your project ID.
-
-## Version compatibility
-
-- `MastraPlatformExporter` is available starting in `@mastra/observability@1.12.0`. In `1.8.0` through `1.11.x` the same exporter includes only as `CloudExporter`. The constructor signature and environment variables are identical.
-- In `@mastra/observability@1.8.0` through `1.9.1`, set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai` in addition to `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID`.
-- Starting in `@mastra/observability@1.9.2`, the exporter defaults to `https://observability.mastra.ai`, so `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` is only required when you want to send telemetry to a different collector.
-
-## Quickstart
-
-To connect `MastraPlatformExporter`, create an access token, find the destination `projectId`, and add the exporter to your observability config.
-
-### 1. Create an access token
-
-Run the following command:
-
-```bash
-mastra auth tokens create exporter-token
-```
-
-This command prints a token secret that you can use as `MASTRA_PLATFORM_ACCESS_TOKEN`.
-
-If you already have an access token, copy the **Observability** value from the Mastra platform instead. You can find it in either of these places:
-
-- On the **Projects** page, open the project list and find the **Observability** row on the project card.
-- On the project **Overview** page, find the **Observability** row directly below the deployment URL.
-
-Set the token as an environment variable:
-
-```bash
-MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
-```
-
-### 2. Find your `projectId`
-
-Run the following command:
-
-```bash
-mastra studio deploy list
-```
-
-The output looks similar to this:
-
-```text
-✅ <your-project-name> (<your-project-id>)
-   Latest:   00000000-0000-0000-0000-000000000000 — running
-   URL:      https://260407.studio.mastra.cloud
-```
-
-In this output, the value in parentheses is the `projectId`:
-
-```text
-<your-project-id>
-```
-
-Set it as an environment variable:
-
-```bash
-MASTRA_PROJECT_ID=<your-project-id>
-```
-
-### 3. Set your environment variables
-
-Set both values in your environment so `MastraPlatformExporter` can authenticate and route telemetry to the correct project:
-
-```bash
-MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
-MASTRA_PROJECT_ID=<your-project-id>
-```
-
-If you use `@mastra/observability@1.8.0` through `1.9.1`, also set the Mastra platform collector explicitly:
-
-```bash
-MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai
-```
-
-If you want to send telemetry somewhere other than Mastra platform, set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` as well. Pass either a base origin or a full traces publish URL ending in `/spans/publish`.
-
-```bash
-MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
-```
-
-When you pass a base origin, `MastraPlatformExporter` derives the matching publish URLs for traces, logs, metrics, scores, and feedback automatically.
-
-### 4. Enable `MastraPlatformExporter`
-
-The following example demonstrates how to add `MastraPlatformExporter` to your observability config:
-
-```ts
-import { Mastra } from '@mastra/core'
-import { Observability, MastraPlatformExporter } from '@mastra/observability'
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      production: {
-        serviceName: 'api-server',
-        exporters: [new MastraPlatformExporter()],
-      },
-    },
-  }),
-})
-```
-
-Set `serviceName` on the observability config, not on `MastraPlatformExporter` itself.
-
-Use a stable `serviceName` value. In Studio, traces can be filtered by **Deployments → Service Name**, so a consistent name makes traces easier to find.
-
-Visit [Observability configuration reference](https://mastra.ai/reference/observability/tracing/configuration) for the full observability config shape.
-
-If you prefer, rely entirely on environment variables:
-
-```ts
-new MastraPlatformExporter()
-```
-
-With `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` set, `MastraPlatformExporter` sends data to the Mastra platform project you configured. If you also set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`, it sends data to that collector instead. Visit [MastraPlatformExporter reference](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for the full list of configuration options.
-
-## Recommended configuration
-
-Include `MastraStorageExporter` if you also want to inspect local traces in Studio or persist observability data to your configured storage.
-
-```ts
-import { Mastra } from '@mastra/core'
-import {
-  Observability,
-  MastraStorageExporter,
-  MastraPlatformExporter,
-  SensitiveDataFilter,
-} from '@mastra/observability'
-
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      default: {
-        serviceName: 'mastra',
-        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
-        spanOutputProcessors: [new SensitiveDataFilter()],
-      },
-    },
-  }),
-})
-```
-
-## Complete configuration
-
-`MastraPlatformExporter` defaults to Mastra platform. If you want to send telemetry to a different collector, set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` in your environment or pass `endpoint` in code.
-
-```bash
-MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
-```
-
-The following example demonstrates how to override the collector endpoint and batching behavior in code:
-
-```ts
-new MastraPlatformExporter({
-  endpoint: 'https://collector.example.com',
-  maxBatchSize: 1000,
-  maxBatchWaitMs: 5000,
-  logLevel: 'info',
-})
-```
-
-## Viewing data in Mastra Studio
-
-After you enable `MastraPlatformExporter`, open your project in [Mastra Studio](https://projects.mastra.ai) to inspect the exported data.
-
-- Open the project you set `MASTRA_PROJECT_ID` to and select **Open Studio**.
-- In Studio, go to **Traces** to inspect agent and workflow traces.
-- Open the filter menu and use **Deployments → Service Name** to isolate traces from a specific app or deployment.
-- Use the **Logs** page in the project dashboard to inspect exported logs.
-
-When you deploy with Mastra Studio, set **Deployment → Service Name** to a stable value and keep it aligned with the `serviceName` in your observability config. This makes traces easier to filter in Studio through **Deployments → Service Name** when multiple services or deployments send data to the same project.
-
-## Performance
-
-> **Info:** MastraPlatformExporter uses batching to optimize network usage. Events are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
-
-### Batching behavior
-
-- Events 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.
-- The exporter degrades gracefully if Mastra Studio is unreachable.
-
-## Related
-
-- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [MastraStorageExporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage)

package/.docs/docs/observability/integrations/overview.md

@@ -1,47 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Integrations overview
-
-Mastra observability integrations control where observability data goes and how it's transformed on the way out. Use integrations to store data in Mastra storage, send it to Mastra platform, connect to external observability providers, or redact exported span data.
-
-## When to use integrations
-
-- Keep observability available in Studio with `MastraStorageExporter`.
-- Send hosted observability data to Mastra platform with `MastraPlatformExporter`.
-- Forward traces to external providers such as Datadog, Langfuse, or OpenTelemetry backends.
-- Redact sensitive values before they leave the runtime.
-
-## Choose an integration path
-
-- Studio workflow: Start with [Mastra Storage](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage).
-- Hosted Mastra workflow: Add [Mastra platform](https://mastra.ai/docs/observability/integrations/exporters/mastra-platform).
-- External observability stack: Choose one or more exporter pages under the sidebar `Exporters` section.
-- Existing distributed trace context: Use a bridge, then add exporters as needed.
-
-## Exporters
-
-Exporters send observability data to a destination:
-
-- [Mastra Storage](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage): Persist observability data for Studio.
-- [Mastra platform](https://mastra.ai/docs/observability/integrations/exporters/mastra-platform): Send hosted observability data to Mastra platform.
-- External providers: Use exporter pages for Datadog, Langfuse, OpenTelemetry, and other supported platforms.
-
-## Bridges
-
-Bridges connect Mastra to an existing distributed tracing context:
-
-- [OpenTelemetry bridge](https://mastra.ai/docs/observability/integrations/bridges/otel): Integrate Mastra with an existing OpenTelemetry trace.
-- [Datadog bridge](https://mastra.ai/docs/observability/integrations/bridges/datadog): Send Mastra traces to Datadog and its LLM Observability product.
-
-## Processors
-
-Processors transform or redact spans before export:
-
-- [Sensitive Data Filter](https://mastra.ai/docs/observability/integrations/processors/sensitive-data-filter): Redact sensitive fields before spans leave the runtime.
-
-## Next steps
-
-- [Configuration](https://mastra.ai/docs/observability/overview)
-- [Tracing](https://mastra.ai/docs/observability/tracing/overview)
-- [Mastra Storage](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage)
-- [OpenTelemetry bridge](https://mastra.ai/docs/observability/integrations/bridges/otel)