OTel-Tracing-Adapter
Der OpenTelemetry-Adapter ist der produktionstaugliche Tracer. Er
überbrückt das Tracer-
Interface des Frameworks zur OpenTelemetry-API, sodass Spans zu dem
Backend fließen, das du konfiguriert hast (Jaeger, Tempo,
Honeycomb, Datadog, New Relic, Grafana Cloud).
enableOtel(...) auf der Tracing-Extension baut ihn und
installiert ihn — du übergibst die @opentelemetry/api-Namespace
(via OtelAdapterOptions):
import * as otel from '@opentelemetry/api';import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';import { ActorSystem } from 'actor-ts';import { TracingExtensionId, OtelAdapterOptions } from 'actor-ts/tracing';
// 1. Set up the OTel SDK (exports spans to your backend)const provider = new NodeTracerProvider({ spanProcessors: [new BatchSpanProcessor( new OTLPTraceExporter({ url: 'https://otel-collector.example.com/v1/traces' }), )],});provider.register();
// 2. Build the framework tracer from the @opentelemetry/api namespace and install itconst system = ActorSystem.create('my-app');const otelAdapterOptions = OtelAdapterOptions.create().withApi(otel);system.extension(TracingExtensionId).enableOtel(otelAdapterOptions);Damit fließen die Auto-Spans des Frameworks (einer pro
Actor-Nachricht) zu deinem Tracing-Backend, über Cluster-Nodes
hinweg mit W3C-traceparent-Kontext verbunden. Sie kommen unter
dem Tracer-Namen actor-ts an, dem Instrumentation Scope, unter dem
dein Backend sie ablegt — es sei denn, du benennst den Tracer selbst,
im Code oder in deiner Config-Datei, siehe
Konfiguration.
Konfiguration
Abschnitt betitelt „Konfiguration“enableOtel nimmt ein OtelAdapterOptions — den Builder oder das
schlichte Objekt. withApi ist Pflicht: der Adapter
delegiert an das, was du übergibst, und dank struktureller
Typisierung importiert das Framework @opentelemetry/api nie
selbst.
type OtelAdapterOptionsType = { api: OtelApiLike; // the @opentelemetry/api namespace (required) tracer?: OtelTracerLike; // pre-built tracer; else api.trace.getTracer(...) tracerName?: string; // passed to getTracer; default 'actor-ts' tracerVersion?: string; // passed to getTracer; default: none};Name und Version können auch aus einer Config-Datei kommen, als
Block actor-ts.tracing:
actor-ts.tracing { tracer-name = "billing" tracer-version = "2.4.0"}enableOtel legt den Block pro Feld unter seine Optionen: Eine
Option, die du übergibst, gewinnt, die Datei füllt, was du offen
lässt, und der eingebaute Default — der Name actor-ts, keine
Version — ist der Boden. Ein withTracerName('svc') im Code lässt
eine konfigurierte tracer-version also stehen. Setze die Version
in Anführungszeichen: Ein 1.0 ohne Anführungszeichen ist für HOCON
eine Zahl und kommt als "1" an. api und tracer haben keinen
Key: Beides sind lebende Objekte, die eine Config-Datei nicht halten
kann.
otelTracer(options) ist der reine Weg darunter. Es bekommt kein
ActorSystem und liest keine Config, der Tracer, den es zurückgibt,
verhält sich also genau so, wie seine Optionen sagen — installiere
ihn selbst:
const pureOptions = OtelAdapterOptions.create().withApi(otel);system.extension(TracingExtensionId).enable(otelTracer(pureOptions));Das OTel-SDK erledigt die Schwerarbeit (Export, Sampling,
Batching); der Adapter übersetzt nur zwischen dem Tracer des
Frameworks und der OTel-API. Du kannst statt Name/Version auch
einen vorgefertigten tracer übergeben. Er wird so verwendet, wie
er ist, ein Name in deinen Optionen erreicht ihn also ebenso wenig
wie einer in deiner Config-Datei:
const prebuiltOptions = OtelAdapterOptions.create() .withApi(otel) .withTracer(otel.trace.getTracer('actor-ts', '1.0.0'));system.extension(TracingExtensionId).enableOtel(prebuiltOptions);Sampling
Abschnitt betitelt „Sampling“import { ParentBasedSampler, TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-base';
const provider = new NodeTracerProvider({ sampler: new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(0.1), // sample 10 % of traces }),});Für Systeme mit hohem Durchsatz ist Sampling essenziell. Es wird auf dem OTel-SDK konfiguriert, nicht auf dem Adapter:
TraceIdRatioBasedSampler(0.1)— 10 % der Traces.AlwaysOnSampler()— jeder Trace (Dev / geringes Volumen).AlwaysOffSampler()— keiner (nur zum Debuggen).ParentBasedSampler(...)— folge der Sampling-Entscheidung des Parents; sampelt stromabwärts eines bereits gesampelten Traces.
Das Framework zeichnet Spans mit voller Rate auf; das SDK entscheidet, welche exportiert werden. Ungesampelte Spans propagieren weiterhin Kontext zur Korrelation, exportieren aber nicht — null Backend-Kosten.
Exporter
Abschnitt betitelt „Exporter“Das OTel-SDK unterstützt viele Exporter:
| Exporter | Backend |
|---|---|
@opentelemetry/exporter-trace-otlp-http | OTLP (Tempo, Jaeger, generische Collectors) |
@opentelemetry/exporter-trace-otlp-grpc | OTLP via gRPC |
@opentelemetry/exporter-jaeger | Jaeger nativ |
@opentelemetry/exporter-zipkin | Zipkin |
| Vendor-spezifisch | Datadog, New Relic, Honeycomb, … |
Wähle nach dem bevorzugten Protokoll deines Backends. OTLP-über-HTTP ist am universellsten — funktioniert mit dem OpenTelemetry Collector, der dann an jedes Backend routet.
Resource-Attribute
Abschnitt betitelt „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 jeden Span gestempelt und sind der nützlichste Ort für globalen Kontext (Service-Name, Version, Region, Pod-Name).
Peer-Dependencies
Abschnitt betitelt „Peer-Dependencies“npm install @opentelemetry/api @opentelemetry/sdk-trace-node# Plus an exporter:npm install @opentelemetry/exporter-trace-otlp-httpBring deine eigene SDK-+-Exporter-Kombi mit — das Framework bündelt
keines von beidem. Es braucht nur die @opentelemetry/api-
Namespace, die du an withApi übergibst.
Metriken und Logs
Abschnitt betitelt „Metriken und Logs“Das OTel-SDK verbindet Traces, Metriken und Logs über gemeinsamen Kontext — aber das Framework liefert keine OTel-Metrik-Brücke. Nutze für Metriken den Prometheus-Exporter des Frameworks (scrape ihn in einen OpenTelemetry Collector, wenn du ihn in deiner OTLP-Pipeline willst) oder den prom-client-Adapter.
Für Logs gibt es eine OTel-Brücke, mit derselben
Namespace-übergeben-Form. ActorSystemOptions.withOtelLogs(...) ist
das Logging-Pendant zu enableOtel: Das System baut den Logger aus
dem @opentelemetry/api-logs-Namespace, den du ihm gibst, und benennt
ihn nach den Leaves logger-name und logger-version desselben
actor-ts.tracing-Blocks,
unter den Optionen auf dieselbe Feld-für-Feld-Weise. otelLogger(...),
das Pendant zu otelTracer, ist der reine Weg darunter. Siehe die
OTLP-Logs-Pipeline.
Wo es weitergeht
Abschnitt betitelt „Wo es weitergeht“- Tracer-API — das Interface, das dieser Adapter implementiert.
- Recording-Tracer — die Test-Alternative.
- Actor-Tracing — die Auto-Spans des Frameworks.
- Prometheus-Exporter — der Metrik-Pfad (es gibt keine OTel-Metrik-Brücke).
