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

# 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

```typescript
new DatadogBridge(config?: DatadogBridgeConfig)
```

## `DatadogBridgeConfig`

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

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

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

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

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

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

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

```typescript
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](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/datadog) 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 :

```typescript
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](https://mastra.zisheng.pro/fr/docs/observability/integrations/bridges/datadog) 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`.

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

Cela produit :

```json
{
  "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](https://mastra.zisheng.pro/fr/docs/observability/integrations/bridges/datadog) - Guide de configuration avec des exemples
- [Présentation du Tracing](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview) - Concepts généraux du Tracing
- [Référence de DatadogExporter](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/datadog) - LLM Observability uniquement, sans APM `dd-trace`