# 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
npm install @mastra/datadog@latest
```

```bash
pnpm add @mastra/datadog@latest
```

```bash
yarn add @mastra/datadog@latest
```

```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/llms.txt)
- [Datadog LLM Observability Documentation](https://docs.datadoghq.com/llm_observability/)