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

# OtelExporter

Envoie les traces et les logs vers toute plateforme d’observabilité compatible avec OpenTelemetry. Les traces utilisent les conventions sémantiques GenAI standardisées ; les logs conservent leur niveau de gravité et leur corps de message d’origine, et sont corrélés aux traces à la fois par le contexte de trace natif de l’enregistrement de log OTEL et par les attributs `mastra.traceId` / `mastra.spanId`.

## Constructeur

```typescript
new OtelExporter(config: OtelExporterConfig)
```

## `OtelExporterConfig`

```typescript
interface OtelExporterConfig {
  provider?: ProviderConfig
  signals?: {
    traces?: boolean
    logs?: boolean
  }
  timeout?: number
  batchSize?: number
  logLevel?: 'debug' | 'info' | 'warn' | 'error'
}
```

## Configurations des Providers

### `Dash0Config`

```typescript
interface Dash0Config {
  apiKey?: string
  endpoint?: string
  dataset?: string
}
```

### `SignozConfig`

```typescript
interface SignozConfig {
  apiKey?: string
  region?: 'us' | 'eu' | 'in'
  endpoint?: string
}
```

### `NewRelicConfig`

```typescript
interface NewRelicConfig {
  apiKey?: string
  endpoint?: string
}
```

### `TraceloopConfig`

```typescript
interface TraceloopConfig {
  apiKey?: string
  destinationId?: string
  endpoint?: string
}
```

### `LaminarConfig`

```typescript
interface LaminarConfig {
  apiKey?: string
  endpoint?: string
}
```

### `CustomConfig`

```typescript
interface CustomConfig {
  endpoint: string
  protocol?: 'http/json' | 'http/protobuf' | 'grpc' | 'zipkin'
  headers?: Record<string, string>
}
```

## Méthodes

### `exportTracingEvent`

```typescript
async exportTracingEvent(event: TracingEvent): Promise<void>
```

Exporte un événement de traçage vers le backend OTEL configuré.

### flush

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

Force l’envoi de tous les spans en mémoire tampon vers le backend OTEL sans arrêter l’Exporter. Utile dans les environnements serverless où vous devez vous assurer que les spans sont exportés avant la fin de l’environnement d’exécution.

### shutdown

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

Envoie les traces en attente et arrête l’Exporter.

## Exemples d’utilisation

### Sans configuration (avec des variables d’environnement)

```typescript
import { OtelExporter } from '@mastra/otel-exporter'

// Set SIGNOZ_API_KEY, SIGNOZ_REGION environment variables
const exporter = new OtelExporter({ provider: { signoz: {} } })

// Or for other providers:
// Set DASH0_API_KEY, DASH0_ENDPOINT for Dash0
// Set NEW_RELIC_LICENSE_KEY for New Relic
// Set TRACELOOP_API_KEY for Traceloop
// Set LMNR_PROJECT_API_KEY for Laminar
```

### Configuration explicite

```typescript
import { OtelExporter } from '@mastra/otel-exporter'

const exporter = new OtelExporter({
  provider: {
    signoz: {
      apiKey: process.env.SIGNOZ_API_KEY,
      region: 'us',
    },
  },
})
```

### Avec un point de terminaison personnalisé

```typescript
const exporter = new OtelExporter({
  provider: {
    custom: {
      endpoint: 'https://my-collector.example.com/v1/traces',
      protocol: 'http/protobuf',
      headers: {
        'x-api-key': process.env.API_KEY,
      },
    },
  },
  timeout: 60000,
  logLevel: 'debug',
})
```

## Exigences relatives aux protocoles

Chaque Provider nécessite des packages d’Exporter OTEL différents. L’export des traces et celui des logs sont indépendants : installez uniquement le package de traces si vous n’avez besoin que des traces, ou installez les packages de traces et de logs du protocole choisi si vous souhaitez également exporter les logs. Zipkin ne prend pas en charge les logs OTLP.

| Protocole     | Package de traces                                             | Package de logs                                              |
| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
| gRPC          | `@opentelemetry/exporter-trace-otlp-grpc` (+ `@grpc/grpc-js`) | `@opentelemetry/exporter-logs-otlp-grpc` (+ `@grpc/grpc-js`) |
| HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto`                    | `@opentelemetry/exporter-logs-otlp-proto`                    |
| HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`                     | `@opentelemetry/exporter-logs-otlp-http`                     |
| Zipkin        | `@opentelemetry/exporter-zipkin`                              | non pris en charge                                           |

## Prise en charge des tags

OtelExporter prend en charge l’ajout de tags aux traces à des fins de catégorisation et de filtrage. Les tags sont uniquement appliqués aux spans racines et sont stockés dans l’attribut `mastra.tags`.

### 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 chaîne JSON dans l’attribut de span `mastra.tags`, afin d’assurer une compatibilité maximale avec les backends :

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

> **Remarque:** Bien que la spécification OpenTelemetry prenne en charge les attributs de tableau natifs, de nombreux backends (Jaeger, Zipkin, Tempo) ont une prise en charge limitée des tableaux. Les chaînes JSON garantissent un comportement cohérent sur toutes les plateformes d’observabilité.

## Ressources associées

- [Guide OtelExporter](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/otel) : guide de configuration avec les configurations des Providers
- [OtelBridge](https://mastra.zisheng.pro/fr/docs/observability/integrations/bridges/otel) : pour l’intégration bidirectionnelle du contexte OTEL
- [Vue d’ensemble du traçage](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview) : concepts généraux du traçage