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

new OtelBridge()

Méthodes

executeInContext

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

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

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

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

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

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 :

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

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 :

{
  "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 : guide de configuration avec des exemples
• Présentation du tracing : concepts généraux du tracing
• Référence d’OtelExporter : exportateur OTEL pour l’envoi des Traces