OTel-Tracing-Adapter

OtelTracerAdapter ist der produktionstaugliche Tracer. Er steckt das Tracer- Interface des Frameworks in das OpenTelemetry-SDK, sodass Spans zu dem Backend fließen, das du konfiguriert hast (Jaeger, Tempo, Honeycomb, Datadog, New Relic, Grafana Cloud).

import { trace as otelTrace } from '@opentelemetry/api';
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { ActorSystem, TracingExtensionId, OtelTracerAdapter } from 'actor-ts';

// 1. OTel-SDK aufsetzen
const provider = new NodeTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(
  new OTLPTraceExporter({ url: 'https://otel-collector.example.com/v1/traces' }),
));
provider.register();

// 2. Adapter verdrahten
const system = ActorSystem.create('my-app');
system.extension(TracingExtensionId).configure({
  tracer: new OtelTracerAdapter({
    tracer: otelTrace.getTracer('actor-ts', '1.0.0'),
  }),
});

Mit diesem Setup fließen die Auto-Spans des Frameworks (einer pro Actor-Message) zu deinem Tracing-Backend, verbunden mit W3C-traceparent-Kontext über Cluster-Nodes hinweg.

Konfiguration

interface OtelTracerAdapterSettings {
  tracer:   OtelTracer;           // aus @opentelemetry/api
  sampler?: Sampler;              // optional — meist auf SDK-Ebene konfiguriert
}

Minimal — das OTel-SDK macht die Schwerarbeit (Export, Sampling, Batching usw.). Der Adapter übersetzt nur zwischen APIs.

Sampling

import { ParentBasedSampler, TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-base';

const provider = new NodeTracerProvider({
  sampler: new ParentBasedSampler({
    root: new TraceIdRatioBasedSampler(0.1),   // 10 % der Traces samplen
  }),
});

Für Hochdurchsatz-Systeme ist Sampling essenziell:

TraceIdRatioBasedSampler(0.1) — 10 % der Traces.
AlwaysOnSampler() — jeder Trace (Dev / niedrige Volumen).
AlwaysOffSampler() — keiner (nur Debugging).
ParentBasedSampler(...) — übernimm die Sampling- Entscheidung des Parents; sampelt nachgelagert eines bereits gesampelten Traces.

Das Framework zeichnet Spans in voller Rate auf; das SDK entscheidet, welche exportiert werden. Nicht gesampelte Spans propagieren weiterhin den Kontext für Korrelation, exportieren aber nicht — Null Backend-Kosten.

Exporter

OTel-SDK unterstützt viele Exporter:

Exporter	Backend
`@opentelemetry/exporter-trace-otlp-http`	OTLP (Tempo, Jaeger, generische Collector)
`@opentelemetry/exporter-trace-otlp-grpc`	OTLP via gRPC
`@opentelemetry/exporter-jaeger`	Jaeger nativ
`@opentelemetry/exporter-zipkin`	Zipkin
Anbieter-spezifisch	Datadog, New Relic, Honeycomb, …

Wähle nach dem bevorzugten Protokoll deines Backends. OTLP-über- HTTP ist am allgemeinsten — funktioniert mit dem OpenTelemetry-Collector, der dann zu jedem Backend routet.

Resource-Attribute

import { Resource } from '@opentelemetry/resources';

const provider = new NodeTracerProvider({
  resource: new Resource({
    'service.name':       'my-app',
    'service.version':    '1.2.3',
    'deployment.environment': 'production',
    'host.name':          process.env.HOSTNAME,
  }),
});

Resource-Attribute werden auf jedem Span gestempelt und sind der nützlichste Ort für globalen Kontext (Servicename, Version, Region, Pod-Name).

Peer-Dependencies

npm install @opentelemetry/api @opentelemetry/sdk-trace-node
# Plus ein Exporter:
npm install @opentelemetry/exporter-trace-otlp-http

Bring dein eigenes SDK + Exporter-Kombo — das Framework bündelt keines von beiden.

Kombination mit Metriken

// Tracer aufsetzen:
system.extension(TracingExtensionId).configure({
  tracer: new OtelTracerAdapter({ tracer: otelTrace.getTracer('actor-ts') }),
});

// Metriken aufsetzen:
const adapter = new OtelMetricsAdapter({
  source: metrics.registry,
  meter:  otelMetrics.getMeter('actor-ts'),
});
adapter.start();

Das OTel-SDK verbindet Traces, Metriken und Logs über geteilten Kontext. Siehe OTel-Metrics-Adapter.

// 1 Million msgs/sec × volles Tracing = unbrauchbares Backend

Bei hohem Durchsatz immer samplen. 10 % ist typisch; manche Teams gehen runter auf 0,1 %. Kombiniert mit Head-based-Sampling (früh droppen) bleiben Backend-Kosten handhabbar.

// @opentelemetry/api v1.x passt evtl. nicht zu sdk-trace-node v2.x

OpenTelemetry-SDK-Versionen müssen aligned sein — Major- Version-Mismatches brechen. Pinne beide auf kompatible Majors in package.json.

Wo es weitergeht

Tracer-API — das Interface, das dieser Adapter implementiert.
Recording-Tracer — Test-Alternative.
Actor-Tracing — die Auto-Spans des Frameworks.
OTel-Metrics-Adapter — Pendant für Metriken.