Datadog Exporter

Datadog 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

npm install @mastra/datadog@latest

pnpm

pnpm add @mastra/datadog@latest

Yarn

yarn add @mastra/datadog@latest

Bun

bun add @mastra/datadog@latest

Configuration

Prerequisites

1. Datadog Account: Sign up at 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

.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:

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):

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

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:

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:

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
• Datadog LLM Observability Documentation