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

new OtelExporter(config: OtelExporterConfig)

OtelExporterConfig

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

Configurations des Providers

Dash0Config

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

SignozConfig

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

NewRelicConfig

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

TraceloopConfig

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

LaminarConfig

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

CustomConfig

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

Méthodes

exportTracingEvent

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

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

flush

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

async shutdown(): Promise<void>

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

Exemples d’utilisation

Sans configuration (avec des variables d’environnement)

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

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é

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

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 :

{
  "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 : guide de configuration avec les configurations des Providers
• OtelBridge : pour l’intégration bidirectionnelle du contexte OTEL
• Vue d’ensemble du traçage : concepts généraux du traçage