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

# Bridge Datadog

> **Attention:** Le bridge Datadog est actuellement **expérimental**. Les API et les options de configuration pourront évoluer dans de prochaines versions.

Le bridge Datadog permet une intégration bidirectionnelle entre le système de tracing de Mastra et Datadog. Contrairement aux exporters qui envoient les données de trace après la fin de l'exécution, le bridge crée en temps réel des spans dd-trace natifs. Les opérations APM auto-instrumentées au sein de vos outils et processeurs, telles que les appels HTTP et les requêtes de base de données, sont ainsi correctement imbriquées sous leurs spans Mastra parents.

> **Vous n'utilisez pas dd-trace APM ?:** Si vous devez uniquement envoyer des données LLM Observability et n'utilisez pas l'auto-instrumentation APM de `dd-trace`, l'[exporter Datadog](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/datadog) est plus simple. Il prend en charge le mode sans Agent et envoie directement les spans à Datadog sans Agent local.

## Quand utiliser le bridge

Utilisez DatadogBridge lorsque vous :

- utilisez l'auto-instrumentation `dd-trace` dans votre application, par exemple pour des serveurs HTTP ou des clients de base de données ;
- souhaitez que les appels de service APM effectués par des outils, des outils MCP ou des processeurs de sortie apparaissent sous leur span Mastra parent plutôt que sous le gestionnaire de requête ;
- avez besoin que les traces APM et les données LLM Observability partagent une topologie de trace cohérente ;
- construisez un système distribué dans lequel le contexte de trace Datadog doit se propager entre les services.

## Fonctionnement

DatadogBridge intervient dans deux parties du pipeline dd-trace :

**Propagation du contexte APM (en temps réel) :**

- crée un span APM dd-trace au moyen de `tracer.startSpan()` lors de la création de chaque span Mastra ;
- active le span APM dans la portée de dd-trace au moyen de `tracer.scope().activate()` pendant l'exécution ;
- rattache les opérations auto-instrumentées au sein de la portée active au bon span Mastra parent ;
- hérite du contexte dd-trace actif, par exemple le span d'une requête entrante, lorsqu'aucun parent Mastra explicite n'existe.

**Émission LLM Observability (à la fin du span) :**

- émet les annotations, notamment les informations sur le modèle, l'utilisation des tokens, les entrées/sorties et les erreurs, via le pipeline LLM Observability de `dd-trace` ;
- conserve les relations parent-enfant dans Datadog LLM Observability au moyen d'appels `llmobs.trace()` imbriqués ;
- réutilise la même forme de données et la même association des types de spans que l'[exporter Datadog](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/datadog).

## Corrélation des traces et des journaux

Sans le bridge, l'exporter Datadog ne crée les spans LLM Observability qu'une fois la trace terminée. Pendant l'exécution, aucun span `dd-trace` n'est actif dans la portée. Tout appel HTTP ou de base de données effectué par un outil est donc rattaché au span `dd-trace` actif à cet instant, généralement celui du gestionnaire de requête entrante. Les appels de service provenant d'outils MCP ou de processeurs de sortie apparaissent alors comme enfants du span de requête au lieu du span de l'Agent ou du processeur qui les a réellement effectués.

Le bridge corrige ce problème en créant dès le départ de véritables spans dd-trace ; la portée est ainsi correcte lorsque l'auto-instrumentation s'exécute.

## Installation

**npm**:

```bash
npm install @mastra/datadog dd-trace
```

**pnpm**:

```bash
pnpm add @mastra/datadog dd-trace
```

**Yarn**:

```bash
yarn add @mastra/datadog dd-trace
```

**Bun**:

```bash
bun add @mastra/datadog dd-trace
```

Le bridge nécessite l'installation de `dd-trace` ainsi qu'un Agent Datadog local, ou un récepteur OTLP compatible, pour recevoir les données APM. Consultez les [prérequis APM](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/datadog) de la page de l'exporter pour les détails de configuration de l'Agent.

## Configuration

L'utilisation de DatadogBridge nécessite deux étapes :

1. Initialisez `dd-trace` afin que son auto-instrumentation modifie les bibliothèques HTTP, de base de données et de framework.
2. Ajoutez DatadogBridge à la configuration d'observabilité de Mastra.

### Étape 1 : initialiser dd-trace

`dd-trace` doit être initialisé avant tout autre import afin que son auto-instrumentation puisse modifier les bibliothèques lors de leur chargement. Le bridge détecte un tracer déjà initialisé et le réutilise.

```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 { DatadogBridge } from '@mastra/datadog'

// ...
```

> **Remarque:** Importez et initialisez `dd-trace` tout en haut du fichier d'entrée de votre application, avant tout autre import.

### Étape 2 : configurer Mastra

Ajoutez DatadogBridge à la configuration d'observabilité de Mastra :

```typescript
export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-mastra-app',
        bridge: new DatadogBridge({
          mlApp: process.env.DD_LLMOBS_ML_APP!,
        }),
      },
    },
  }),
  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_LLMOBS_ML_APP=my-llm-app
```

Lorsque `dd-trace` est initialisé, il achemine les données APM vers votre Agent Datadog local sur `localhost:8126`. Le bridge active LLM Observability sur ce même tracer, de sorte que les deux ensembles de données apparaissent sous le même service dans Datadog.

Aucun exporter Mastra n'est requis lorsque vous utilisez le bridge : les données APM et LLM Observability transitent toutes par `dd-trace`. Vous pouvez néanmoins ajouter des exporters Mastra si vous souhaitez envoyer les traces vers d'autres destinations.

## Mode avec ou sans Agent

Le bridge utilise par défaut le **mode avec Agent** (`agentless: false`). Ce mode suppose qu'un Agent Datadog local s'exécute sur `localhost:8126` afin de recevoir les données APM et LLM Observability. Il s'agit de la configuration habituelle avec l'auto-instrumentation `dd-trace`, car les données APM transitent toujours par l'Agent.

Si vous ne disposez pas d'un Agent Datadog local et avez seulement besoin des données LLM Observability, sans auto-instrumentation APM, vous pouvez activer le mode sans Agent pour envoyer les données directement à Datadog. Vous devez alors fournir une clé d'API.

```typescript
new DatadogBridge({
  mlApp: process.env.DD_LLMOBS_ML_APP!,
  apiKey: process.env.DD_API_KEY!,
  agentless: true,
})
```

> **Remarque:** Pour la plupart des utilisateurs du bridge, le mode avec Agent est le meilleur choix. Les données APM ne peuvent pas être envoyées en mode sans Agent ; l'activation de ce mode sépare donc le trafic LLM Observability du trafic APM. Si vous souhaitez uniquement LLM Observability sans Agent, utilisez plutôt l'[exporter Datadog](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/datadog).

## Hiérarchie des traces

Avec DatadogBridge, vos traces conservent une hiérarchie correcte au-delà des frontières entre dd-trace et Mastra. Les appels de service effectués par les outils et les processeurs apparaissent sous le bon span Mastra :

```text
HTTP POST /api/chat (from web framework instrumentation)
└── agent.orchestrator (from Mastra via DatadogBridge)
    ├── chat gpt-5.4 (LLM call)
    ├── tool.execute search (tool execution)
    │   └── HTTP GET api.example.com (auto-instrumented from inside the tool)
    └── processor.guardrail (output processor)
        └── HTTP POST guardrail-service/check (auto-instrumented from inside the processor)
```

Dans Datadog, la trace APM affiche cette topologie complète, tandis que LLM Observability présente les spans propres à l'Agent et au LLM avec leurs entrées, leurs sorties et leurs métriques de tokens.

## Association des types de spans

Pour LLM Observability, le bridge utilise la même association des types de spans que l'exporter Datadog. Consultez l'[association des types de spans](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/datadog) sur la page de l'exporter.

## Utiliser des tags

Les tags permettent de classer et de filtrer les traces dans Datadog. Ajoutez-les lors de l'exécution des Agents ou des Workflows :

```typescript
const result = await agent.generate('Hello', {
  tracingOptions: {
    tags: ['production', 'experiment-v2', 'user-request'],
  },
})
```

Les tags au format `key:value`, par exemple `instance_name:career-scout-api`, sont séparés en entrées de tag structurées. Les tags sans deux-points reçoivent la valeur `true`.

## Promouvoir les clés de contexte en tags simples

Utilisez `requestContextKeys` pour promouvoir certaines clés du contexte de requête ou des attributs du span en tags LLM Observability simples et indexables. Elles peuvent ainsi être filtrées dans l'interface Datadog :

```typescript
new DatadogBridge({
  mlApp: process.env.DD_LLMOBS_ML_APP!,
  requestContextKeys: ['tenantId', 'agentId'],
})
```

Les clés promues sont retirées de `annotations.metadata` et ajoutées comme tags simples sur chaque span LLM Observability.

## Dépannage

Si les spans APM ne sont pas rattachés aux spans Mastra comme prévu :

- vérifiez que `dd-trace` est initialisé **avant** tout autre import, puisqu'il modifie les bibliothèques lors de leur chargement ;
- vérifiez qu'un Agent Datadog local s'exécute et est accessible sur `localhost:8126` ;
- assurez-vous que DatadogBridge est défini comme `bridge`, et non comme une entrée de `exporters`, dans votre configuration d'observabilité ;
- vérifiez que vous n'avez pas également ajouté `DatadogExporter` à `exporters`, car l'utilisation conjointe des deux émettrait les données LLM Observability en double.

Pour les problèmes de compatibilité des modules natifs avec `dd-trace` et les dépendances externes du bundler, consultez la section [dépannage de l'exporter Datadog](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/datadog).

## Voir aussi

- [Présentation du tracing](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview)
- [Exporter Datadog](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/datadog) — LLM Observability uniquement, sans APM `dd-trace`
- [Référence de DatadogBridge](https://mastra.zisheng.pro/fr/reference/observability/tracing/bridges/datadog) — documentation de l'API
- [Documentation de Datadog APM](https://docs.datadoghq.com/tracing/)
- [Documentation de Datadog LLM Observability](https://docs.datadoghq.com/llm_observability/)