Datadog exporter

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Mastra observability configuration guide for sending LLM traces and APM data to Datadog’s monitoring platform, targeting developers integrating Datadog LLM Observability and Application Performance Monitoring into Mastra applications.

Insight

The @mastra/datadog package exports traces to Datadog’s LLM Observability product, providing insights into model performance, token usage, and conversation flows. The exporter supports two modes: agentless mode (direct HTTPS to Datadog) and agent mode (via local Datadog Agent on localhost:8126). Configuration options include: mlApp (groups traces under ML app name), apiKey (required for agentless mode), site (datadoghq.com, datadoghq.eu, us3.datadoghq.com, etc.), service (defaults to mlApp), env (environment name), agentless (boolean toggle), integrationsEnabled (dd-trace auto-instrumentation), and logLevel (debug|info|warn|error). Mastra span types automatically map to Datadog LLM Observability kinds: AGENT_RUN→agent, MODEL_GENERATION→workflow, MODEL_STEP→llm, TOOL_CALL→tool, MCP_TOOL_CALL→tool, WORKFLOW_RUN→workflow, and other/future types default to ‘task’. For full APM tracing (HTTP routes, request latency, error tracking, service maps), use dd-trace directly with optional native modules (@datadog/native-metrics, @datadog/native-appsec, @datadog/native-iast-taint-tracking, @datadog/pprof) that provide performance monitoring. Native modules have best compatibility with Node.js 22.x but are optional—if they fail to load, core tracing still works. The DatadogExporter can detect an existing dd-trace initialization and skip re-initialization, adding LLM Observability on top of existing APM setup. When using agent mode, the API key is read from the local agent’s configuration rather than passed directly.

Hành động

Install @mastra/datadog@latest via npm, pnpm, yarn, or bun. Set environment variables: DD_API_KEY (from Datadog Organization Settings → API Keys), DD_LLMOBS_ML_APP (ML app grouping name), optionally DD_SITE (defaults to datadoghq.com) and DD_ENV. For zero-config setup, instantiate DatadogExporter() with no arguments after setting env vars. For explicit config, pass mlApp, apiKey, site, service, env, agentless, integrationsEnabled, and logLevel to the constructor. Configure the Mastra observability property with a configs.datadog object containing serviceName and exporters array. For APM with dd-trace: import and initialize tracer.init() at the top of entry file before any other imports (critical for auto-instrumentation), set DD_SERVICE, DD_ENV, DD_VERSION environment variables, and configure Mastra bundler.externals with the dd-trace native module packages. For combined LLM Observability and APM, initialize dd-trace before creating the Mastra instance with both Observability config and bundler externals. For troubleshooting ABI mismatches with native modules, use Node.js 22.x or ignore warnings since core tracing functionality still works.

Kết quả

Traces are sent to Datadog LLM Observability providing model performance insights, token usage tracking, and conversation flow visualization. APM traces appear in Datadog showing request latency, errors, and service maps. Both LLM Observability and APM data appear under the same service in the Datadog dashboard.

Điều kiện áp dụng

Requires @mastra/datadog@latest package. APM tracing requires dd-trace package. Native modules have best compatibility with Node.js 22.x. Import and initialize dd-trace before all other modules for auto-instrumentation to work correctly. When using bundlers (esbuild, webpack, Mastra CLI), mark dd-trace and its native module dependencies as externals.

Nội dung gốc (Original)

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.

Also using dd-trace APM?: If you also use dd-trace APM auto-instrumentation, consider the Datadog Bridge 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:

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

Datadog Account: Sign up at datadoghq.com with LLM Observability enabled
API Key: Get your API key from Datadog Organization Settings → API Keys
Environment Variables: Set your credentials

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:

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

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

Datadog Agent: Install a Datadog 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 to set it up.
dd-trace package: Install the tracing library in your project:

npm:
```
npm install dd-trace
```
pnpm:
```
pnpm add dd-trace
```
Yarn:
```
yarn add dd-trace
```
Bun:
```
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:

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:

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

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',
    ],
  },
})

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:

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:

Use Node.js 22.x: Native modules have the best compatibility with Node.js 22.x.
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:

export const mastra = new Mastra({
  bundler: {
    externals: [
      'dd-trace',
      '@datadog/native-metrics',
      '@datadog/native-appsec',
      '@datadog/native-iast-taint-tracking',
      '@datadog/pprof',
    ],
  },
})

Liên kết

Nền tảng: Dev Framework · Mastra
Nguồn: https://mastra.ai/docs/observability/tracing/exporters/datadog

Xem thêm:

KakaFlow KB

Nội dung

Datadog exporter

Datadog exporter

Tình huống

Insight

Hành động

Kết quả

Điều kiện áp dụng

Nội dung gốc (Original)

Datadog exporter

Installation

Configuration

Prerequisites

Zero-Config Setup

Explicit Configuration

Configuration options

Complete Configuration

With Local Datadog Agent

Span type mapping

Application Performance Monitoring

Prerequisites

APM only

APM and LLM Observability

Troubleshooting

Native module ABI mismatch

Bundler externals configuration

Liên kết

Sơ đồ

Mục lục

Liên kết ngược

KakaFlow KB

Nội dung

Datadog exporter

Datadog exporter

Tình huống

Insight

Hành động

Kết quả

Điều kiện áp dụng

Nội dung gốc (Original)

Datadog exporter

Installation

Configuration

Prerequisites

Zero-Config Setup

Explicit Configuration

Configuration options

Complete Configuration

With Local Datadog Agent

Span type mapping

Application Performance Monitoring

Prerequisites

APM only

APM and LLM Observability

Troubleshooting

Native module ABI mismatch

Bundler externals configuration

Related

Liên kết

Sơ đồ

Mục lục

Liên kết ngược