Bridge OpenTelemetry

attention

Le bridge OpenTelemetry est actuellement expérimental. Les API et les options de configuration pourront évoluer dans de futures versions.

Le bridge OpenTelemetry (OTEL) permet une intégration bidirectionnelle entre le système de traçage de Mastra et une infrastructure OpenTelemetry existante. Contrairement aux exportateurs qui envoient les données de trace vers des plateformes externes, le bridge crée des spans OTEL natifs qui participent à votre contexte de traçage distribué.

Vous souhaitez envoyer des traces sans infrastructure OTEL existante ?

Si vous ne disposez pas encore d’une instrumentation OpenTelemetry, l’exportateur OpenTelemetry peut être plus simple : il envoie directement les traces sans nécessiter la configuration d’un SDK OTEL.

Quand utiliser le bridge

Utilisez OtelBridge dans les cas suivants :

• Votre application possède déjà une instrumentation OTEL, par exemple pour les serveurs HTTP ou les clients de base de données
• Vous souhaitez que les opérations Mastra apparaissent comme des spans enfants de vos traces OTEL existantes
• Le code instrumenté par OTEL au sein des outils Mastra doit conserver des relations parent-enfant correctes
• Vous construisez un système distribué dans lequel le contexte de trace doit se propager entre les services

Fonctionnement

OtelBridge fournit une intégration bidirectionnelle :

D’OTEL vers Mastra :

• Lit automatiquement le contexte ambiant d’OTEL (AsyncLocalStorage)
• Hérite de l’identifiant de trace et de l’identifiant du span parent à partir des spans OTEL actifs
• Respecte les décisions d’échantillonnage d’OTEL : si une trace n’est pas échantillonnée, Mastra ne crée aucun span pour celle-ci
• Ne nécessite aucune transmission manuelle de l’identifiant de trace lorsque l’auto-instrumentation OTEL est active

De Mastra vers OTEL :

• Crée des spans OTEL natifs pour les opérations Mastra, notamment les agents, appels de LLM, outils et workflows
• Préserve les relations parent-enfant correctes dans les traces distribuées
• Permet au code instrumenté par OTEL, comme les clients HTTP ou les appels de base de données, de s’imbriquer correctement dans les opérations Mastra
• Transmet les événements de journalisation Mastra au LoggerProvider OTEL enregistré globalement. Les journaux provenant d’un span Mastra sont émis dans le contexte OTEL de ce span afin que les backends puissent les corréler à la trace. Si aucun LoggerProvider n’est enregistré, l’émission des journaux est une opération silencieuse sans effet.

Installation

npm

npm install @mastra/otel-bridge

pnpm

pnpm add @mastra/otel-bridge

Yarn

yarn add @mastra/otel-bridge

Bun

bun add @mastra/otel-bridge

Le bridge fonctionne avec votre configuration OpenTelemetry existante. Selon votre configuration, vous pouvez également avoir besoin de certains des packages suivants :

• @opentelemetry/sdk-node — SDK Node.js principal pour OTEL
• @opentelemetry/auto-instrumentations-node — auto-instrumentation des bibliothèques courantes
• @opentelemetry/exporter-trace-otlp-proto — exportateur OTLP (Protobuf sur HTTP)
• @opentelemetry/exporter-trace-otlp-http — exportateur OTLP (JSON sur HTTP)
• @opentelemetry/exporter-trace-otlp-grpc — exportateur OTLP (gRPC)
• @opentelemetry/sdk-trace-base — SDK de traçage de base, notamment pour BatchSpanProcessor
• @opentelemetry/core — utilitaires principaux, notamment pour W3CTraceContextPropagator
• @opentelemetry/sdk-logs et un exportateur de journaux OTLP, par exemple @opentelemetry/exporter-logs-otlp-http — nécessaires si vous souhaitez que le bridge transmette également les événements de journalisation Mastra

Configuration

L’utilisation d’OtelBridge nécessite deux étapes :

1. Configurer l’instrumentation OpenTelemetry dans votre application
2. Ajouter OtelBridge à votre configuration d’observabilité Mastra

Étape 1 : instrumentation OpenTelemetry

Créez un fichier d’instrumentation qui initialise OTEL. Il doit s’exécuter avant le code de votre application :

instrumentation.ts

import { NodeSDK } from '@opentelemetry/sdk-node'
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
import { W3CTraceContextPropagator } from '@opentelemetry/core'

const sdk = new NodeSDK({
  serviceName: 'my-service',
  spanProcessors: [
    new BatchSpanProcessor(
      new OTLPTraceExporter({
        url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
      }),
    ),
  ],
  instrumentations: [getNodeAutoInstrumentations()],
  textMapPropagator: new W3CTraceContextPropagator(),
})

sdk.start()

export { sdk }

Étape 2 : configuration de Mastra

Ajoutez OtelBridge à votre configuration d’observabilité Mastra :

src/mastra/index.ts

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

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'my-service',
        bridge: new OtelBridge(),
      },
    },
  }),
  agents: {/* your agents */},
})

Aucun exportateur Mastra n’est nécessaire lors de l’utilisation du bridge, car les traces sont envoyées par la configuration de votre SDK OTEL. Vous pouvez ajouter des exportateurs Mastra si vous souhaitez envoyer les traces vers d’autres destinations.

Transmettre les journaux (facultatif)

Le bridge transmet également les événements de journalisation Mastra au LoggerProvider OTEL enregistré globalement. Pour configurer les journaux avec les traces, enregistrez un logRecordProcessor dans NodeSDK :

instrumentation.ts

import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'
import { BatchLogRecordProcessor } from '@opentelemetry/sdk-logs'

const sdk = new NodeSDK({
  // ...trace config as usual
  logRecordProcessor: new BatchLogRecordProcessor(
    new OTLPLogExporter({
      url: process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT || 'http://localhost:4318/v1/logs',
    }),
  ),
})

Les journaux provenant d’un span Mastra sont émis dans le contexte OTEL de ce span ; les backends tels que Datadog, Grafana et Honeycomb les corrèlent donc automatiquement à la trace environnante. Les journaux sans contexte de trace utilisent le contexte OTEL actuellement actif.

Si vous n’enregistrez pas de LoggerProvider, l’émission des journaux est une opération silencieuse sans effet ; les traces continuent de fonctionner selon la configuration.

Exécuter votre application

Utilisez l’option --import pour garantir que l’instrumentation se charge avant votre application :

tsx --import ./instrumentation.ts ./src/index.ts

Conventions sémantiques

OtelBridge exporte les spans Mastra conformément aux conventions sémantiques OpenTelemetry pour GenAI v1.38.0. Cela comprend des noms de spans normalisés (chat {model}, execute_tool {tool_name}, etc.) et des attributs (gen_ai.usage.input_tokens, gen_ai.request.model, etc.).

Pour en savoir plus sur les noms et les attributs des spans, consultez les conventions sémantiques de l’exportateur OpenTelemetry.

Hiérarchie des traces

Avec OtelBridge, vos traces conservent une hiérarchie correcte au-delà des frontières entre OTEL et Mastra :

HTTP POST /api/chat (from Hono middleware)
└── agent.assistant (from Mastra via OtelBridge)
    ├── chat gpt-5.4 (LLM call)
    ├── tool.execute search (tool execution)
    │   └── HTTP GET api.example.com (from OTEL auto-instrumentation)
    └── chat gpt-5.4 (follow-up LLM call)

Traçage distribué entre plusieurs services

OtelBridge permet de propager les traces au-delà des frontières des services. Lorsque le service A appelle le service B par HTTP, le contexte de trace se propage automatiquement :

Service A: HTTP POST /api/process
└── HTTP POST service-b/api/analyze (outgoing call)

Service B: HTTP POST /api/analyze (incoming call - same trace!)
└── agent.analyzer (Mastra agent inherits trace context)
    └── chat gpt-5.4

Les deux services doivent disposer des éléments suivants :

1. Une instrumentation OTEL configurée
2. Le propagateur W3C Trace Context activé
3. Mastra configuré avec OtelBridge

Utiliser les tags

Les tags vous aident à catégoriser et filtrer les traces dans votre backend OTEL. Ajoutez des tags lorsque vous exécutez des agents ou des workflows :

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

Les tags sont exportés sous forme de chaîne JSON dans l’attribut de span mastra.tags afin d’assurer une large compatibilité avec les backends. Les cas d’utilisation courants incluent :

• Libellés d’environnement : "production", "staging"
• Suivi des expériences : "experiment-v1", "control-group"
• Niveaux de priorité : "priority-high", "batch-job"

Résolution des problèmes

Si les traces ne s’affichent pas ou ne se connectent pas comme prévu :

• Vérifiez que le SDK OTEL est initialisé avant Mastra, en utilisant l’option --import ou en important l’instrumentation au début du point d’entrée
• Vérifiez qu’OtelBridge est ajouté à votre configuration d’observabilité
• Vérifiez que votre backend OTEL est en cours d’exécution et accessible

Ressources associées

• Vue d’ensemble du traçage
• Exportateur OpenTelemetry : pour envoyer des traces aux backends OTEL
• Référence d’OtelBridge : documentation de l’API