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

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

npm install @mastra/datadog dd-trace

pnpm

pnpm add @mastra/datadog dd-trace

Yarn

yarn add @mastra/datadog dd-trace

Bun

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

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

src/mastra/index.ts

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

.env

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.

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.

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 :

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

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 :

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.

Voir aussi

• Présentation du tracing
• Exporter Datadog — LLM Observability uniquement, sans APM dd-trace
• Référence de DatadogBridge — documentation de l'API
• Documentation de Datadog APM
• Documentation de Datadog LLM Observability