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 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.

Installation
Lien direct vers 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)
Lien direct vers Pour les fournisseurs HTTP/Protobuf (SigNoz, New Relic, Laminar, MLflow, Latitude, telemetry.dev)

npm
pnpm
Yarn
Bun

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

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

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

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

Pour les fournisseurs `gRPC` (Dash0, Datadog)
Lien direct vers for-grpc-providers-dash0-datadog

npm
pnpm
Yarn
Bun

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

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

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

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

Pour les fournisseurs HTTP/JSON (Traceloop)
Lien direct vers Pour les fournisseurs HTTP/JSON (Traceloop)

npm
pnpm
Yarn
Bun

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

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

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

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

Variables d’environnement
Lien direct vers 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
Lien direct vers Configurations des fournisseurs

MLflow
Lien direct vers MLflow

MLflow 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 :

src/mastra/index.ts
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
Lien direct vers Latitude

Latitude 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 :

src/mastra/index.ts
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, ou auto-hébergez le service et faites pointer l’endpoint vers votre propre hôte d’ingestion.

telemetry.dev
Lien direct vers telemetry.dev

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 :

.env
TELEMETRY_DEV_API_KEY=td_live_...

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

Dash0
Lien direct vers Dash0

Dash0 fournit une observabilité en temps réel accompagnée d’analyses automatiques.

Configuration automatique
Lien direct vers Configuration automatique

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

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

# Optional
DASH0_DATASET=production

src/mastra/index.ts
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
Lien direct vers Configuration explicite

src/mastra/index.ts
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`
Lien direct vers signoz

SigNoz est une solution APM open source qui prend en charge nativement le tracing.

Configuration automatique
Lien direct vers Configuration automatique

.env
# Required
SIGNOZ_API_KEY=your-api-key

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

src/mastra/index.ts
new OtelExporter({ provider: { signoz: {} } })

Configuration explicite
Lien direct vers Configuration explicite

src/mastra/index.ts
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
Lien direct vers New Relic

New Relic fournit une observabilité complète avec des fonctionnalités de surveillance de l’IA.

Configuration automatique
Lien direct vers Configuration automatique

.env
# Required
NEW_RELIC_LICENSE_KEY=your-license-key

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

src/mastra/index.ts
new OtelExporter({ provider: { newrelic: {} } })

Configuration explicite
Lien direct vers Configuration explicite

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

Traceloop
Lien direct vers Traceloop

Traceloop est spécialisé dans l’observabilité des LLM avec suivi automatique des prompts.

Configuration automatique
Lien direct vers Configuration automatique

.env
# Required
TRACELOOP_API_KEY=your-api-key

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

src/mastra/index.ts
new OtelExporter({ provider: { traceloop: {} } })

Configuration explicite
Lien direct vers Configuration explicite

src/mastra/index.ts
new OtelExporter({
  provider: {
    traceloop: {
      apiKey: process.env.TRACELOOP_API_KEY,
      destinationId: 'my-destination', // Optional
    },
  },
})

Laminar
Lien direct vers Laminar

Laminar fournit des fonctions spécialisées d’observabilité et d’analyse des LLM.

Configuration automatique
Lien direct vers Configuration automatique

.env
# Required
LMNR_PROJECT_API_KEY=your-api-key

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

src/mastra/index.ts
new OtelExporter({ provider: { laminar: {} } })

Configuration explicite
Lien direct vers Configuration explicite

src/mastra/index.ts
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. Il offre une intégration optimisée à la plateforme Laminar.

Datadog
Lien direct vers Datadog

Datadog 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 pour fonctionner correctement :

src/mastra/index.ts
// 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 :

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, 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. Il offre une intégration optimisée à la plateforme APM de Datadog.

Endpoints OTEL personnalisés ou génériques
Lien direct vers Endpoints OTEL personnalisés ou génériques

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

src/mastra/index.ts
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
Lien direct vers 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 :

src/mastra/index.ts
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
pnpm
Yarn
Bun

# 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

# 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

# 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

# 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
Lien direct vers Options de configuration

Configuration complète
Lien direct vers Configuration complète

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`
Lien direct vers opentelemetry-semantic-conventions

L’exportateur respecte les conventions sémantiques OpenTelemetry pour GenAI v1.38.0, ce qui garantit sa compatibilité avec les plateformes d’observabilité :

Nommage des spans
Lien direct vers 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
Lien direct vers 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
Lien direct vers 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
Lien direct vers Résolution des problèmes

Erreur de dépendance manquante
Lien direct vers Erreur de dépendance manquante

Si vous voyez une erreur de ce type :

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
Lien direct vers Problèmes courants

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

InstallationLien direct vers Installation

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

Pour les fournisseurs gRPC (Dash0, Datadog)Lien direct vers for-grpc-providers-dash0-datadog

Pour les fournisseurs HTTP/JSON (Traceloop)Lien direct vers Pour les fournisseurs HTTP/JSON (Traceloop)

Variables d’environnementLien direct vers Variables d’environnement

Configurations des fournisseursLien direct vers Configurations des fournisseurs

MLflowLien direct vers MLflow

LatitudeLien direct vers Latitude

telemetry.devLien direct vers telemetry.dev

Dash0Lien direct vers Dash0

Configuration automatiqueLien direct vers Configuration automatique

Configuration expliciteLien direct vers Configuration explicite

SigNozLien direct vers signoz

Configuration automatiqueLien direct vers Configuration automatique

Configuration expliciteLien direct vers Configuration explicite

New RelicLien direct vers New Relic

Configuration automatiqueLien direct vers Configuration automatique

Configuration expliciteLien direct vers Configuration explicite

TraceloopLien direct vers Traceloop

Configuration automatiqueLien direct vers Configuration automatique

Configuration expliciteLien direct vers Configuration explicite

LaminarLien direct vers Laminar

Configuration automatiqueLien direct vers Configuration automatique

Configuration expliciteLien direct vers Configuration explicite

DatadogLien direct vers Datadog

Endpoints OTEL personnalisés ou génériquesLien direct vers Endpoints OTEL personnalisés ou génériques

SignauxLien direct vers Signaux

Options de configurationLien direct vers Options de configuration

Configuration complèteLien direct vers Configuration complète

Conventions sémantiques OpenTelemetryLien direct vers opentelemetry-semantic-conventions

Nommage des spansLien direct vers Nommage des spans

Attributs principauxLien direct vers Attributs principaux

Guide de sélection du protocoleLien direct vers Guide de sélection du protocole

Résolution des problèmesLien direct vers Résolution des problèmes

Erreur de dépendance manquanteLien direct vers Erreur de dépendance manquante

Problèmes courantsLien direct vers Problèmes courants

Pages connexesLien direct vers Pages connexes

Installation
Lien direct vers Installation

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

Pour les fournisseurs `gRPC` (Dash0, Datadog)
Lien direct vers for-grpc-providers-dash0-datadog

Pour les fournisseurs HTTP/JSON (Traceloop)
Lien direct vers Pour les fournisseurs HTTP/JSON (Traceloop)

Variables d’environnement
Lien direct vers Variables d’environnement

Configurations des fournisseurs
Lien direct vers Configurations des fournisseurs

MLflow
Lien direct vers MLflow

Latitude
Lien direct vers Latitude

telemetry.dev
Lien direct vers telemetry.dev

Dash0
Lien direct vers Dash0

Configuration automatique
Lien direct vers Configuration automatique

Configuration explicite
Lien direct vers Configuration explicite

`SigNoz`
Lien direct vers signoz

Configuration automatique
Lien direct vers Configuration automatique

Configuration explicite
Lien direct vers Configuration explicite

New Relic
Lien direct vers New Relic

Configuration automatique
Lien direct vers Configuration automatique

Configuration explicite
Lien direct vers Configuration explicite

Traceloop
Lien direct vers Traceloop

Configuration automatique
Lien direct vers Configuration automatique

Configuration explicite
Lien direct vers Configuration explicite

Laminar
Lien direct vers Laminar

Configuration automatique
Lien direct vers Configuration automatique

Configuration explicite
Lien direct vers Configuration explicite

Datadog
Lien direct vers Datadog

Endpoints OTEL personnalisés ou génériques
Lien direct vers Endpoints OTEL personnalisés ou génériques

Signaux
Lien direct vers Signaux

Options de configuration
Lien direct vers Options de configuration

Configuration complète
Lien direct vers Configuration complète

Conventions sémantiques `OpenTelemetry`
Lien direct vers opentelemetry-semantic-conventions

Nommage des spans
Lien direct vers Nommage des spans

Attributs principaux
Lien direct vers Attributs principaux

Guide de sélection du protocole
Lien direct vers Guide de sélection du protocole

Résolution des problèmes
Lien direct vers Résolution des problèmes

Erreur de dépendance manquante
Lien direct vers Erreur de dépendance manquante

Problèmes courants
Lien direct vers Problèmes courants

Pages connexes
Lien direct vers Pages connexes