DatadogBridge

attention

Le Bridge Datadog est actuellement expérimental. Les API et les options de configuration peuvent changer dans de futures versions.

Permet une intégration bidirectionnelle entre le Tracing Mastra et Datadog. Crée des spans APM dd-trace natifs en temps réel afin que les opérations auto-instrumentées dans les Tools et les Processors soient correctement imbriquées sous leur span Mastra parent. Émet les données LLM Observability par l'intermédiaire du pipeline de dd-trace lorsque les spans se terminent.

Constructeur

new DatadogBridge(config?: DatadogBridgeConfig)

DatadogBridgeConfig

interface DatadogBridgeConfig extends BaseExporterConfig {
  apiKey?: string
  mlApp?: string
  site?: string
  service?: string
  env?: string
  agentless?: boolean
  integrationsEnabled?: boolean
  requestContextKeys?: string[]
}

Étend BaseExporterConfig, qui comprend :

• logger?: IMastraLogger - Instance du Logger
• logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - Niveau de journalisation (par défaut : INFO)

Méthodes

createSpan

createSpan(options: CreateSpanOptions<SpanType>): SpanIds | undefined

Appelée par l'instance Observability de Mastra pendant la construction du span. Crée immédiatement un span APM dd-trace au moyen de tracer.startSpan() et renvoie des identifiants compatibles avec Mastra. Les identifiants renvoyés sont utilisés par Mastra pendant toute la durée de vie du span. L'objet span dd-trace est stocké en interne et utilisé pour l'activation de la portée.

Renvoie : SpanIds | undefined - { spanId, traceId, parentSpanId }, ou undefined si le Bridge est désactivé.

executeInContext

executeInContext<T>(spanId: string, fn: () => Promise<T>): Promise<T>

Exécute une fonction asynchrone dans le contexte dd-trace d'un span Mastra. Les opérations auto-instrumentées par dd-trace qui s'exécutent dans la fonction (HTTP, base de données, etc.) auront ce span comme parent.

Renvoie : Promise<T> - Résultat de l'exécution de la fonction.

executeInContextSync

executeInContextSync<T>(spanId: string, fn: () => T): T

Exécute une fonction synchrone dans le contexte dd-trace d'un span Mastra.

Renvoie : T - Résultat de l'exécution de la fonction.

flush

async flush(): Promise<void>

Force l'envoi à Datadog de toutes les données LLM Observability en mémoire tampon sans arrêter le Bridge. Cette méthode est utile dans les environnements serverless où vous devez vous assurer que les données sont exportées avant la fin de l'environnement d'exécution.

shutdown

async shutdown(): Promise<void>

Force l'arrêt de tous les spans APM qui n'ont pas été correctement fermés, envoie les données LLM Observability en attente, désactive l'intégration LLM Observability et efface tout l'état interne.

Exemples d'utilisation

Utilisation de base

import tracer from 'dd-trace'

tracer.init({
  service: process.env.DD_SERVICE || 'my-mastra-app',
  env: process.env.DD_ENV || 'production',
})

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { DatadogBridge } from '@mastra/datadog'

const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-mastra-app',
        bridge: new DatadogBridge({
          mlApp: process.env.DD_LLMOBS_ML_APP!,
        }),
      },
    },
  }),
  agents: { myAgent },
})

Mode sans Agent (LLM Observability uniquement, sans Agent local)

Si vous ne disposez pas d'un Agent Datadog local et souhaitez uniquement les données LLM Observability, activez le mode sans Agent :

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

Remarque : les données APM ne peuvent pas être envoyées en mode sans Agent. Si vous avez uniquement besoin des données LLM Observability sans APM dd-trace, DatadogExporter constitue une solution plus simple.

Avec des Exporters supplémentaires

Le Bridge peut être combiné à des Exporters autres que Datadog afin d'envoyer les Traces vers des destinations supplémentaires :

import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { DatadogBridge } from '@mastra/datadog'

const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-mastra-app',
        bridge: new DatadogBridge({
          mlApp: process.env.DD_LLMOBS_ML_APP!,
        }),
        exporters: [
          new MastraStorageExporter(), // Studio access
        ],
      },
    },
  }),
})

remarque

Ne combinez pas DatadogBridge et DatadogExporter dans la même configuration. Tous deux émettent vers LLM Observability et écriraient les mêmes données en double.

Prérequis de configuration

DatadogBridge exige que dd-trace soit initialisé avant tout autre import afin que son auto-instrumentation puisse appliquer ses correctifs aux bibliothèques HTTP, de base de données et de framework au moment du chargement.

Consultez le guide de DatadogBridge pour obtenir les instructions de configuration complètes, notamment l'initialisation de dd-trace, les dépendances externes du bundler et la configuration de l'Agent.

Mappage des spans

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

SpanType Mastra	Catégorie Datadog
AGENT_RUN	agent
MODEL_GENERATION	workflow
MODEL_STEP	llm
TOOL_CALL	tool
MCP_TOOL_CALL	tool
WORKFLOW_RUN	workflow
Tous les autres types	task

Prise en charge des tags

Les valeurs de tracingOptions.tags deviennent des tags d'annotation LLM Observability structurés : les entrées key:value sont séparées en paires clé/valeur, tandis que les tags sans deux-points sont définis sur true.

const result = await agent.generate('Hello', {
  tracingOptions: {
    tags: ['production', 'instance_name:career-scout-api'],
  },
})

Cela produit :

{
  "production": true,
  "instance_name": "career-scout-api"
}

Variables d'environnement

Le Bridge lit sa configuration dans les variables d'environnement suivantes :

Variable	Description
DD_API_KEY	Clé d'API Datadog (obligatoire uniquement en mode sans Agent)
DD_LLMOBS_ML_APP	Nom de l'application ML
DD_SITE	Site Datadog
DD_ENV	Nom de l'environnement
DD_LLMOBS_AGENTLESS_ENABLED	Définissez cette variable sur 'true' ou '1' pour activer le mode sans Agent

Voir aussi

• Guide de DatadogBridge - Guide de configuration avec des exemples
• Présentation du Tracing - Concepts généraux du Tracing
• Référence de DatadogExporter - LLM Observability uniquement, sans APM dd-trace