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

# Exportateur OpenTelemetry

L’exportateur OpenTelemetry (OTEL) envoie vos traces et journaux à toute plateforme d’observabilité compatible avec OTEL en utilisant les [conventions sémantiques OpenTelemetry pour l’IA générative](https://opentelemetry.io/docs/specs/semconv/gen-ai/) standardisées. Cela garantit une large compatibilité avec des plateformes comme Datadog, New Relic, SigNoz, MLflow, Latitude, Dash0, Traceloop, Laminar, telemetry.dev et bien d’autres.

> **Vous recherchez une intégration OTEL bidirectionnelle ?:** Si vous disposez déjà d’une instrumentation OpenTelemetry et souhaitez que les traces Mastra héritent du contexte des spans OTEL actifs, consultez plutôt le [pont OpenTelemetry](https://mastra.zisheng.pro/fr/docs/observability/integrations/bridges/otel).

## Installation

Chaque fournisseur nécessite des packages de protocole spécifiques. Installez l’exportateur de base ainsi que le package de protocole correspondant à votre fournisseur :

### Pour les fournisseurs HTTP/Protobuf (SigNoz, New Relic, Laminar, MLflow, Latitude, telemetry.dev)

**npm**:

```bash
npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-proto
```

### Pour les fournisseurs `gRPC` (Dash0, Datadog)

**npm**:

```bash
npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
```

### Pour les fournisseurs HTTP/JSON (Traceloop)

**npm**:

```bash
npm install @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
```

**pnpm**:

```bash
pnpm add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
```

**Yarn**:

```bash
yarn add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
```

**Bun**:

```bash
bun add @mastra/otel-exporter@latest @opentelemetry/exporter-trace-otlp-http
```

## Variables d’environnement

Tous les fournisseurs permettent une configuration automatique au moyen de variables d’environnement. Définissez les variables appropriées et l’exportateur les utilisera automatiquement :

| Fournisseur | Variables d’environnement                                                                   |
| ----------- | ------------------------------------------------------------------------------------------- |
| Dash0       | `DASH0_API_KEY` (required), `DASH0_ENDPOINT` (required), `DASH0_DATASET` (optional)         |
| SigNoz      | `SIGNOZ_API_KEY` (required), `SIGNOZ_REGION` (optional), `SIGNOZ_ENDPOINT` (optional)       |
| New Relic   | `NEW_RELIC_LICENSE_KEY` (required), `NEW_RELIC_ENDPOINT` (optional)                         |
| Traceloop   | `TRACELOOP_API_KEY` (required), `TRACELOOP_DESTINATION_ID`, `TRACELOOP_ENDPOINT` (optional) |
| Laminar     | `LMNR_PROJECT_API_KEY` (required), `LAMINAR_ENDPOINT` (optional)                            |

## Configurations des fournisseurs

### MLflow

[MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) prend en charge nativement le tracing Mastra via son endpoint OTLP situé à `/v1/traces`. Utilisez le fournisseur `custom` avec HTTP/Protobuf et incluez l’en-tête de l’expérience afin que les traces soient acheminées vers l’expérience MLflow appropriée :

```typescript
new OtelExporter({
  provider: {
    custom: {
      endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`,
      protocol: 'http/protobuf',
      headers: {
        'x-mlflow-experiment-id': process.env.MLFLOW_EXPERIMENT_ID,
      },
    },
  },
})
```

### Latitude

[Latitude](https://latitude.so) est une plateforme open source d’observabilité et d’évaluation des LLM qui ingère des traces OTLP. Utilisez le fournisseur `custom` avec HTTP/Protobuf, en ciblant l’endpoint d’ingestion de Latitude et en vous authentifiant avec votre clé API et le slug de votre projet :

```typescript
new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://ingest.latitude.so/v1/traces',
      protocol: 'http/protobuf',
      headers: {
        Authorization: `Bearer ${process.env.LATITUDE_API_KEY}`,
        'X-Latitude-Project': process.env.LATITUDE_PROJECT,
      },
    },
  },
})
```

Inscrivez-vous sur [console.latitude.so](https://console.latitude.so/login), ou auto-hébergez le service et faites pointer l’endpoint vers votre propre hôte d’ingestion.

### telemetry.dev

[telemetry.dev](https://telemetry.dev) ingère des traces OTLP/HTTP protobuf et normalise les conventions sémantiques OpenTelemetry GenAI en champs de modèle, de fournisseur, de tokens, de latence et de coût. Utilisez le fournisseur `custom` avec la clé API de votre projet :

```bash
TELEMETRY_DEV_API_KEY=td_live_...
```

```typescript
new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://ingest.telemetry.dev/v1/traces',
      protocol: 'http/protobuf',
      headers: {
        Authorization: `Bearer ${process.env.TELEMETRY_DEV_API_KEY}`,
      },
    },
  },
})
```

### Dash0

[Dash0](https://www.dash0.com/) fournit une observabilité en temps réel accompagnée d’analyses automatiques.

#### Configuration automatique

Définissez les variables d’environnement et utilisez l’exportateur avec une configuration vide :

```bash
# Required
DASH0_API_KEY=your-api-key
DASH0_ENDPOINT=ingress.us-west-2.aws.dash0.com:4317

# Optional
DASH0_DATASET=production
```

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

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      otel: {
        serviceName: 'my-service',
        exporters: [new OtelExporter({ provider: { dash0: {} } })],
      },
    },
  }),
})
```

#### Configuration explicite

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

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      otel: {
        serviceName: 'my-service',
        exporters: [
          new OtelExporter({
            provider: {
              dash0: {
                apiKey: process.env.DASH0_API_KEY,
                endpoint: process.env.DASH0_ENDPOINT, // e.g., 'ingress.us-west-2.aws.dash0.com:4317'
                dataset: 'production', // Optional dataset name
              },
            },
            resourceAttributes: {
              // Optional OpenTelemetry Resource Attributes for the trace
              ['deployment.environment']: 'dev',
            },
          }),
        ],
      },
    },
  }),
})
```

> **Info:** Récupérez votre endpoint Dash0 depuis votre tableau de bord. Il doit respecter le format `ingress.{region}.aws.dash0.com:4317`.

### `SigNoz`

[SigNoz](https://signoz.io/) est une solution APM open source qui prend en charge nativement le tracing.

#### Configuration automatique

```bash
# Required
SIGNOZ_API_KEY=your-api-key

# Optional
SIGNOZ_REGION=us  # 'us' | 'eu' | 'in'
SIGNOZ_ENDPOINT=https://my-signoz.example.com  # For self-hosted
```

```typescript
new OtelExporter({ provider: { signoz: {} } })
```

#### Configuration explicite

```typescript
new OtelExporter({
  provider: {
    signoz: {
      apiKey: process.env.SIGNOZ_API_KEY,
      region: 'us', // 'us' | 'eu' | 'in'
      // endpoint: 'https://my-signoz.example.com', // For self-hosted
    },
  },
})
```

### New Relic

[New Relic](https://newrelic.com/) fournit une observabilité complète avec des fonctionnalités de surveillance de l’IA.

#### Configuration automatique

```bash
# Required
NEW_RELIC_LICENSE_KEY=your-license-key

# Optional
NEW_RELIC_ENDPOINT=https://otlp.eu01.nr-data.net  # For EU region
```

```typescript
new OtelExporter({ provider: { newrelic: {} } })
```

#### Configuration explicite

```typescript
new OtelExporter({
  provider: {
    newrelic: {
      apiKey: process.env.NEW_RELIC_LICENSE_KEY,
      // endpoint: 'https://otlp.eu01.nr-data.net', // For EU region
    },
  },
})
```

### Traceloop

[Traceloop](https://www.traceloop.com/) est spécialisé dans l’observabilité des LLM avec suivi automatique des prompts.

#### Configuration automatique

```bash
# Required
TRACELOOP_API_KEY=your-api-key

# Optional
TRACELOOP_DESTINATION_ID=my-destination
TRACELOOP_ENDPOINT=https://custom.traceloop.com
```

```typescript
new OtelExporter({ provider: { traceloop: {} } })
```

#### Configuration explicite

```typescript
new OtelExporter({
  provider: {
    traceloop: {
      apiKey: process.env.TRACELOOP_API_KEY,
      destinationId: 'my-destination', // Optional
    },
  },
})
```

### Laminar

[Laminar](https://laminar.sh/) fournit des fonctions spécialisées d’observabilité et d’analyse des LLM.

#### Configuration automatique

```bash
# Required
LMNR_PROJECT_API_KEY=your-api-key

# Optional
LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces
```

```typescript
new OtelExporter({ provider: { laminar: {} } })
```

#### Configuration explicite

```typescript
new OtelExporter({
  provider: {
    laminar: {
      apiKey: process.env.LMNR_PROJECT_API_KEY,
    },
  },
})
```

> **Exportateur natif Laminar:** Pour bénéficier de fonctionnalités propres à Laminar, comme les chemins de spans natifs ainsi que l’affichage des métadonnées et des tags dans son tableau de bord, envisagez plutôt d’utiliser l’exportateur dédié [`@mastra/laminar`](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/laminar). Il offre une intégration optimisée à la plateforme Laminar.

### Datadog

[Datadog](https://www.datadoghq.com/) APM assure la surveillance des performances applicatives avec un tracing distribué. Pour envoyer des traces à Datadog via OTLP, l’Agent Datadog doit être en cours d’exécution avec l’ingestion OTLP activée.

Datadog utilise gRPC pour l’ingestion OTLP, ce qui nécessite des imports explicites et une [configuration du bundler](https://mastra.zisheng.pro/fr/reference/configuration) pour fonctionner correctement :

```typescript
// Explicitly import gRPC dependencies for the bundler
import '@grpc/grpc-js'
import '@opentelemetry/exporter-trace-otlp-grpc'
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { OtelExporter, type ExportProtocol } from '@mastra/otel-exporter'

export const mastra = new Mastra({
  // Add grpc-js to externals so it's handled at runtime
  bundler: {
    externals: ['@grpc/grpc-js'],
  },
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-service',
        exporters: [
          new OtelExporter({
            provider: {
              custom: {
                endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
                protocol: (process.env.OTEL_EXPORTER_OTLP_PROTOCOL || 'grpc') as ExportProtocol,
                headers: {},
              },
            },
          }),
        ],
      },
    },
  }),
})
```

> **Info:** L’Agent Datadog doit être configuré avec l’ingestion OTLP activée. Ajoutez ce qui suit à votre fichier `datadog.yaml` :
>
> ```yaml
> otlp_config:
>   receiver:
>     protocols:
>       grpc:
>         endpoint: 0.0.0.0:4317
> ```
>
> Lorsque l’Agent Datadog s’exécute localement, l’endpoint OTLP par défaut est `http://localhost:4317`.

> **Attention:** Les imports explicites de `@grpc/grpc-js` et `@opentelemetry/exporter-trace-otlp-grpc` en haut du fichier, ainsi que la configuration [`bundler.externals`](https://mastra.zisheng.pro/fr/reference/configuration), sont indispensables au bon fonctionnement du transport gRPC. Sans eux, vous risquez de rencontrer des problèmes de connexion.

> **Exportateur natif Datadog:** Pour bénéficier de fonctionnalités propres à Datadog, comme l’association automatique des types de spans, la catégorisation des spans LLM et une configuration simplifiée sans réglage gRPC, envisagez plutôt d’utiliser l’exportateur dédié [`@mastra/datadog`](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/datadog). Il offre une intégration optimisée à la plateforme APM de Datadog.

### Endpoints OTEL personnalisés ou génériques

Pour les autres plateformes compatibles avec OTEL ou les collecteurs personnalisés :

```typescript
new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://your-collector.example.com/v1/traces',
      protocol: 'http/protobuf', // 'http/json' | 'http/protobuf' | 'grpc'
      headers: {
        'x-api-key': process.env.API_KEY,
      },
    },
  },
})
```

## Signaux

L’exportateur envoie deux signaux OpenTelemetry :

- Traces : les spans Mastra, exportés via `BatchSpanProcessor`.
- Journaux : les événements de journal Mastra, exportés via `BatchLogRecordProcessor`. Les journaux qui contiennent `traceId` et `spanId` sont corrélés aux traces à l’aide du contexte de trace natif de l’enregistrement OTEL ainsi que des attributs `mastra.traceId` / `mastra.spanId`. Les backends comme Datadog, Grafana et Honeycomb peuvent ainsi associer automatiquement les journaux aux traces.

Les deux signaux sont activés par défaut et partagent la même configuration de fournisseur. L’endpoint des journaux est déduit de celui des traces en remplaçant le suffixe `/v1/traces` par `/v1/logs`.

Pour désactiver un signal, définissez l’option `signals` :

```typescript
new OtelExporter({
  provider: {/* ... */},
  signals: {
    traces: true, // default
    logs: false, // disable log export
  },
})
```

L’exportation des journaux nécessite l’installation du package d’exportation de journaux OTLP correspondant à votre protocole :

**npm**:

```bash
# HTTP/JSON
npm install @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
npm install @opentelemetry/exporter-logs-otlp-proto
# gRPC
npm install @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
```

**pnpm**:

```bash
# HTTP/JSON
pnpm add @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
pnpm add @opentelemetry/exporter-logs-otlp-proto
# gRPC
pnpm add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
```

**Yarn**:

```bash
# HTTP/JSON
yarn add @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
yarn add @opentelemetry/exporter-logs-otlp-proto
# gRPC
yarn add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
```

**Bun**:

```bash
# HTTP/JSON
bun add @opentelemetry/exporter-logs-otlp-http
# HTTP/Protobuf
bun add @opentelemetry/exporter-logs-otlp-proto
# gRPC
bun add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
```

Si le package d’exportation de journaux correspondant n’est pas installé, leur exportation est désactivée silencieusement et les traces continuent de fonctionner.

## Options de configuration

### Configuration complète

```typescript
new OtelExporter({
  // Provider configuration (required)
  provider: {
    // Use one of: dash0, signoz, newrelic, traceloop, laminar, custom
  },

  // Per-signal toggles. Both default to true.
  signals: {
    traces: true,
    logs: true,
  },

  // Export configuration
  timeout: 30000, // Export timeout in milliseconds
  batchSize: 100, // Number of spans/logs per batch

  // Debug options
  logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error'
})
```

## Conventions sémantiques `OpenTelemetry`

L’exportateur respecte les [conventions sémantiques OpenTelemetry pour GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai), ce qui garantit sa compatibilité avec les plateformes d’observabilité :

### Nommage des spans

- **Opérations LLM** : `chat {model}`
- **Exécution d’un Tool** : `execute_tool {tool_name}`
- **Exécutions d’Agent** : `invoke_agent {agent_id}`
- **Exécutions de Workflow** : `invoke_workflow {workflow_id}`

### Attributs principaux

- `gen_ai.operation.name` - Type d’opération (chat, tool.execute, etc.)
- `gen_ai.provider.name` - Fournisseur d’IA (openai, anthropic, etc.)
- `gen_ai.request.model` - Identifiant du modèle
- `gen_ai.input.messages` - Historique de conversation fourni au modèle
- `gen_ai.output.messages` - Messages renvoyés par le modèle
- `gen_ai.usage.input_tokens` - Nombre de tokens en entrée
- `gen_ai.usage.output_tokens` - Nombre de tokens en sortie
- `gen_ai.request.temperature` - Température d’échantillonnage
- `gen_ai.response.finish_reasons` - Raisons de l’arrêt de la génération

## Guide de sélection du protocole

Choisissez le package de protocole adapté à votre fournisseur :

| Fournisseur  | Protocole     | Package requis                             |
| ------------ | ------------- | ------------------------------------------ |
| Dash0        | gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  |
| Datadog      | gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  |
| SigNoz       | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
| New Relic    | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
| Traceloop    | HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`  |
| Laminar      | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
| Personnalisé | Variable      | Dépend de votre collecteur                 |

> **Attention:** Veillez à installer le package de protocole approprié à votre fournisseur. Si le mauvais package est installé, l’exportateur affichera un message d’erreur explicite.

## Résolution des problèmes

### Erreur de dépendance manquante

Si vous voyez une erreur de ce type :

```text
HTTP/Protobuf exporter is not installed (required for signoz).
To use HTTP/Protobuf export, install the required package:
  npm install @opentelemetry/exporter-trace-otlp-proto
```

Installez le package suggéré pour votre fournisseur.

### Problèmes courants

1. **Mauvais package de protocole** : vérifiez que vous avez installé l’exportateur adapté à votre fournisseur
2. **Endpoint non valide** : vérifiez que son format correspond aux exigences du fournisseur
3. **Échecs d’authentification** : vérifiez que les clés API et les en-têtes sont corrects

## Pages connexes

- [Présentation du tracing](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview)
- [Pont OpenTelemetry](https://mastra.zisheng.pro/fr/docs/observability/integrations/bridges/otel)
- [Conventions sémantiques OpenTelemetry pour GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)
- [Référence de l’exportateur OTEL](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/otel)