/otel-exporter

Maturity: alpha — may change without notice; production use at your own risk.

OpenTelemetry exporter — wire wasmagent EventLog into Jaeger / Tempo / any OTLP collector.

Part of wasmagent — a TypeScript + WASM agent runtime.

Stability: beta

This package is in beta. The span schema and attribute names may change in minor releases as the OpenTelemetry semantic conventions for AI agents stabilise.

Install

@wasmagent/otel-exporter requires @wasmagent/core as a peer dependency. The bridge types (OtelBridge, withOtel) live in @wasmagent/core/experimental.

npm install @wasmagent/otel-exporter @wasmagent/core

Note: OtelBridge and withOtel are exported from @wasmagent/core/experimental. This subpath has no stability guarantee — APIs may change in minor releases. See the stability note above.

Usage

Bridges agent events (model calls, tool calls, kernel executions) to OTLP traces with correct parent/child span relationships. See examples/otel-jaeger.

import { OtlpHttpExporter } from "@wasmagent/otel-exporter";
import { OtelBridge, withOtel } from "@wasmagent/core/experimental"; // peer dep

const exporter = new OtlpHttpExporter({ endpoint: "http://localhost:4318" });
const bridge = new OtelBridge({ exporter });
for await (const ev of withOtel(agent.run("task"), bridge)) {
  // ev is a typed AgentEvent
}

Calling export() directly (without the bridge): OtlpHttpExporter.export(spans: ReadableSpan[]) — the ReadableSpan type is re-exported from @wasmagent/core/experimental and matches the OpenTelemetry SDK ReadableSpan shape.

Semantic Convention Version Tracking

This package tracks the OpenTelemetry GenAI semantic conventions.

| Constant | Value | Meaning | |---|---|---| | GENAI_SEMCONV_VERSION | "1.28.0" | The semconv spec version this package conforms to |

Opting into experimental semconv

The GenAI semantic conventions are currently in Development/Experimental stability. As the spec evolves, attribute names may change. This package supports incremental opt-in:

import { OtlpHttpExporter } from "@wasmagent/otel-exporter";

// Option 1: explicit in code
const exporter = new OtlpHttpExporter({ semconvVersion: "latest" });

// Option 2: environment variable (cluster-level override)
// Set OTEL_SEMCONV_STABILITY_OPT_IN=genai/experimental
const exporter2 = new OtlpHttpExporter(); // picks up env var automatically

When useLatestSemconv is true, the exporter may emit attribute names following the newest draft conventions. When false (the default), it uses the baseline stable mapping.

The environment variable OTEL_SEMCONV_STABILITY_OPT_IN follows the OTel specification for semconv stability opt-in. Setting it to "genai/experimental" enables experimental GenAI conventions.

License

Apache-2.0 — © wasmagent contributors