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

# OtelBridge

> **Attention:** Le bridge OpenTelemetry est actuellement **expérimental**. Les API et les options de configuration peuvent changer dans de prochaines versions.

Permet une intégration bidirectionnelle entre le tracing de Mastra et l’infrastructure OpenTelemetry. Crée des spans OTEL natifs pour les opérations Mastra et hérite du contexte des spans OTEL actifs. Transmet également les événements de log Mastra au `LoggerProvider` OTEL enregistré globalement, en émettant chaque log dans le contexte OTEL du span Mastra d’origine afin que la corrélation entre Traces et logs fonctionne automatiquement.

## Constructeur

```typescript
new OtelBridge()
```

## Méthodes

### `executeInContext`

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

Exécute une fonction asynchrone dans le contexte OTEL d’un span Mastra. Le code instrumenté avec OTEL qui s’exécute dans cette fonction possède les relations parent appropriées.

**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 OTEL d’un span Mastra.

**Renvoie :** `T` - Résultat de l’exécution de la fonction.

### `onLogEvent`

```typescript
async onLogEvent(event: LogEvent): Promise<void>
```

Transmet un événement de log Mastra au `LoggerProvider` OTEL enregistré globalement. La corrélation des Traces est résolue dans l’ordre suivant :

1. Si le log contient un `spanId` pour lequel le bridge possède un span OTEL, il est émis dans le contexte OTEL stocké de ce span.
2. Sinon, si le log contient `traceId` et `spanId`, ces ID sont associés au `SpanContext` de l’enregistrement de log émis.
3. Sinon, le log est émis dans le contexte OTEL actuellement actif.

Si aucun `LoggerProvider` n’est enregistré globalement, l’émission n’effectue silencieusement aucune opération.

### `flush`

```typescript
async flush(): Promise<void>
```

Force le flush du Provider global de tracer OTEL et du Provider global de logger s’ils prennent en charge `forceFlush`. Cette méthode est utile dans les environnements serverless où vous devez vider la télémétrie avant l’arrêt du runtime.

### `shutdown`

```typescript
async shutdown(): Promise<void>
```

Arrête le bridge et libère les ressources. Met fin à tous les spans qui n’ont pas été correctement fermés.

## Exemples d’utilisation

### Utilisation de base

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelBridge } from '@mastra/otel-bridge'

const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-service',
        bridge: new OtelBridge(),
      },
    },
  }),
  agents: { myAgent },
})
```

### Combinaison avec des exportateurs

Le bridge peut être utilisé avec des exportateurs. Il gère le contexte OTEL, tandis que les exportateurs envoient les données vers des destinations supplémentaires :

```typescript
import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { OtelBridge } from '@mastra/otel-bridge'
import { LangfuseExporter } from '@mastra/langfuse'

const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-service',
        bridge: new OtelBridge(), // Handles OTEL context
        exporters: [
          new MastraStorageExporter(), // Studio access
          new LangfuseExporter({
            // Additional destination
            publicKey: process.env.LANGFUSE_PUBLIC_KEY,
            secretKey: process.env.LANGFUSE_SECRET_KEY,
          }),
        ],
      },
    },
  }),
})
```

## Prérequis de configuration d’`OpenTelemetry`

OtelBridge nécessite un SDK OpenTelemetry actif pour fonctionner. Le bridge lit le contexte ambiant d’OTEL.

Consultez le [guide OtelBridge](https://mastra.zisheng.pro/fr/docs/observability/integrations/bridges/otel) pour obtenir les instructions de configuration complètes, notamment la configuration de l’instrumentation OTEL et l’exécution de votre application.

## Prise en charge des tags

OtelBridge prend en charge l’ajout de tags aux Traces afin de les classer et de les filtrer. Les tags sont appliqués uniquement aux spans racines et inclus comme attribut `mastra.tags` dans les spans OTEL natifs.

### Utilisation

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

### Stockage des tags

Les tags sont stockés sous forme de tableau sérialisé en JSON dans l’attribut de span `mastra.tags` :

```json
{
  "mastra.tags": "[\"production\",\"experiment-v2\",\"user-request\"]"
}
```

Ce format garantit la compatibilité avec tous les backends et collecteurs compatibles avec OTEL.

## Voir aussi

- [Guide OtelBridge](https://mastra.zisheng.pro/fr/docs/observability/integrations/bridges/otel) : 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 d’OtelExporter](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/otel) : exportateur OTEL pour l’envoi des Traces