> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# Exporter Datadog

[Datadog](https://datadoghq.com/) 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](https://mastra.zisheng.pro/fr/docs/observability/integrations/bridges/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**:

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

### Prérequis

1. **Compte Datadog** : inscrivez-vous sur [datadoghq.com](https://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

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

### Configuration automatique

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

### Configuration explicite

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

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

## Options de configuration

### Configuration complète

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

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

```typescript
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](https://docs.datadoghq.com/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](https://docs.datadoghq.com/agent/) 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](https://docs.datadoghq.com/agent/) pour le configurer.

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

   **npm**:

   ```bash
   npm install dd-trace
   ```

   **pnpm**:

   ```bash
   pnpm add dd-trace
   ```

   **Yarn**:

   ```bash
   yarn add dd-trace
   ```

   **Bun**:

   ```bash
   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 :

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

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

```bash
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](https://mastra.zisheng.pro/fr/docs/server/server-adapters) 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 :

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

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 :

```text
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 :

```typescript
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](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview)
- [Documentation de Datadog LLM Observability](https://docs.datadoghq.com/llm_observability/)
- [Documentation de Datadog APM](https://docs.datadoghq.com/tracing/)