Exporter Datadog

Datadog est une plateforme de surveillance complète qui propose des fonctionnalités dédiées à LLM Observability. L'exporter Datadog envoie vos traces au produit LLM Observability de Datadog, qui fournit des informations sur les performances des modèles, l'utilisation des tokens et les flux de conversation.

Vous utilisez également dd-trace APM ?

Si vous utilisez également l'auto-instrumentation APM de dd-trace, envisagez plutôt le bridge Datadog. Le bridge crée des spans dd-trace en temps réel afin que les appels HTTP et de base de données effectués dans les outils et les processeurs soient correctement imbriqués sous leur span Mastra parent. Employé seul, l'exporter envoie les données LLM Observability après la fin de l'exécution ; les spans APM auto-instrumentés sont donc rattachés au gestionnaire de requête.

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

Prérequis

1. Compte Datadog : inscrivez-vous sur datadoghq.com avec LLM Observability activé
2. Clé d'API : récupérez votre clé d'API dans Organization Settings → API Keys de Datadog
3. Variables d'environnement : définissez vos identifiants

.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

Configuration automatique

Une fois les variables d’environnement définies, utilisez l’exporter sans 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()],
      },
    },
  }),
})

Configuration explicite

Vous pouvez également transmettre les identifiants directement ; ils prévalent sur les variables d’environnement :

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

Options de configuration

Configuration complète

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

Avec un Agent Datadog local

Si un Agent Datadog s'exécute localement, vous pouvez acheminer les traces par son intermédiaire plutôt que directement en HTTPS :

new DatadogExporter({
  mlApp: process.env.DD_LLMOBS_ML_APP!,
  agentless: false, // Use local Datadog Agent
  env: 'production',
})

Remarque : en mode avec Agent, la clé d'API est lue dans la configuration de l'Agent local.

Association des types de spans

Les types de spans Mastra sont automatiquement associés aux types de spans Datadog LLM Observability :

SpanType Mastra	Type Datadog
AGENT_RUN	agent
MODEL_GENERATION	workflow
MODEL_STEP	llm
TOOL_CALL	tool
MCP_TOOL_CALL	tool
WORKFLOW_RUN	workflow
Autres types de Workflow	task
GENERIC	task

Les autres types de spans Mastra, y compris les futurs types, sont associés par défaut à « task » sauf indication contraire.

Surveillance des performances des applications

Les sections précédentes présentent l'intégration LLM Observability de Mastra. Pour tracer les routes de votre serveur HTTP Mastra, notamment la latence des requêtes, le suivi des erreurs et les cartes de services, utilisez directement dd-trace avec Datadog Application Performance Monitoring (APM).

Prérequis

1. Agent Datadog : installez un Agent Datadog sur le même hôte ou rendez-le accessible par le réseau. L'Agent reçoit les traces de dd-trace sur localhost:8126 et les transmet à Datadog. Suivez le guide d'installation de l'Agent pour le configurer.

2. Package dd-trace : installez la bibliothèque de tracing dans votre projet :

   npm

   npm install dd-trace

   pnpm

   pnpm add dd-trace

   Yarn

   yarn add dd-trace

   Bun

   bun add dd-trace

remarque

Les traces APM transitent toujours par l'Agent Datadog. Ce comportement diffère de LLM Observability, qui prend en charge le mode sans Agent avec un envoi HTTPS direct vers Datadog.

APM uniquement

Importez et initialisez dd-trace en haut de votre fichier d'entrée, avant tout autre import :

src/mastra/index.ts

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

Définissez les variables d'environnement des métadonnées du tracer :

.env

DD_SERVICE=my-mastra-app
DD_ENV=production
DD_VERSION=1.0.0

dd-trace instrumente automatiquement les frameworks HTTP courants, notamment ceux pris en charge par les adaptateurs de serveur de Mastra. Les requêtes entrantes, les appels HTTP sortants et les requêtes de base de données apparaissent comme traces APM dans Datadog.

APM et LLM Observability

Importez et initialisez dd-trace avant de créer l'instance Mastra. DatadogExporter détecte le tracer existant et évite de le réinitialiser, puis ajoute LLM Observability à votre configuration APM :

src/mastra/index.ts

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

.env

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

Les routes du serveur apparaissent comme traces APM et les appels au LLM comme spans LLM Observability, le tout sous le même service dans Datadog.

remarque

Importez et initialisez dd-trace avant tous les autres modules. Son auto-instrumentation peut ainsi modifier les bibliothèques HTTP, de base de données et de framework lors de leur chargement.

Dépannage

Incompatibilité ABI d'un module natif

Si vous rencontrez des erreurs telles que :

Error: No native build was found for runtime=node abi=137 platform=linuxglibc arch=x64

Cette erreur indique un problème de compatibilité de version de Node.js avec les modules natifs de dd-trace. Ces modules natifs sont facultatifs et fournissent des fonctions de surveillance des performances.

Solutions :

1. Utiliser Node.js 22.x : les modules natifs offrent la meilleure compatibilité avec Node.js 22.x.

2. Ignorer les avertissements des modules natifs : les modules natifs (@datadog/native-metrics, @datadog/native-appsec, etc.) sont facultatifs. S'ils ne se chargent pas, les fonctionnalités principales de tracing continuent de fonctionner.

Configuration des dépendances externes du bundler

Avec des bundlers tels qu'esbuild, webpack ou celui de la CLI Mastra, vous devrez peut-être marquer dd-trace et ses dépendances comme externes :

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

Voir aussi

• Présentation du tracing
• Documentation de Datadog LLM Observability
• Documentation de Datadog APM