Zum Inhalt springen
Deutsch

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 it
const 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.

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);
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.

Das OTel-SDK unterstützt viele Exporter:

ExporterBackend
@opentelemetry/exporter-trace-otlp-httpOTLP (Tempo, Jaeger, generische Collectors)
@opentelemetry/exporter-trace-otlp-grpcOTLP via gRPC
@opentelemetry/exporter-jaegerJaeger nativ
@opentelemetry/exporter-zipkinZipkin
Vendor-spezifischDatadog, 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.

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

Terminal-Fenster
npm install @opentelemetry/api @opentelemetry/sdk-trace-node
# Plus an exporter:
npm install @opentelemetry/exporter-trace-otlp-http

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

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.