コンテンツにスキップ
日本語

OTel tracing adapter

このコンテンツはまだ日本語訳がありません。

The OpenTelemetry adapter is the production-grade tracer. It bridges the framework’s Tracer interface to the OpenTelemetry API, so spans flow to whatever backend you’ve configured (Jaeger, Tempo, Honeycomb, Datadog, New Relic, Grafana Cloud).

enableOtel(...) on the tracing extension builds it and installs it — you hand it the @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);

With this set up, the framework’s auto-spans (one per actor message) flow to your tracing backend, joined with W3C traceparent context across cluster nodes. They arrive under the tracer name actor-ts, the instrumentation scope your backend files them under, unless you name the tracer yourself — in code or in your config file, see Configuration.

enableOtel takes an OtelAdapterOptions — the builder or the plain object. withApi is mandatory: the adapter delegates to whatever you pass, and structural typing means the framework never imports @opentelemetry/api itself.

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
};

The name and version can also come from a config file, as the actor-ts.tracing block:

actor-ts.tracing {
tracer-name = "billing"
tracer-version = "2.4.0"
}

enableOtel layers the block under its options, per field: an option you pass wins, the file fills what you leave unset, and the built-in default — the name actor-ts, no version — is the floor. So a withTracerName('svc') in code keeps a configured tracer-version. Quote the version: an unquoted 1.0 is a number to HOCON and arrives as "1". api and tracer have no key: both are live objects a config file cannot hold.

otelTracer(options) is the pure path underneath. It takes no ActorSystem and reads no config, so the tracer it returns behaves exactly as its options say — install it yourself:

const pureOptions = OtelAdapterOptions.create().withApi(otel);
system.extension(TracingExtensionId).enable(otelTracer(pureOptions));

The OTel SDK does the heavy lifting (export, sampling, batching); the adapter just translates between the framework’s Tracer and the OTel API. You can also pass a pre-built tracer instead of a name/version. It is used as it is, so neither a name in your options nor one in your config file reaches it:

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
}),
});

For high-throughput systems, sampling is essential. It’s configured on the OTel SDK, not the adapter:

  • TraceIdRatioBasedSampler(0.1) — 10 % of traces.
  • AlwaysOnSampler() — every trace (dev / low-volume).
  • AlwaysOffSampler() — none (debugging only).
  • ParentBasedSampler(...) — defer to parent’s sampling decision; samples downstream of an already-sampled trace.

The framework records spans at full rate; the SDK decides which to export. Unsampled spans still propagate context for correlation but don’t export — zero backend cost.

OTel SDK supports many exporters:

ExporterBackend
@opentelemetry/exporter-trace-otlp-httpOTLP (Tempo, Jaeger, generic collectors)
@opentelemetry/exporter-trace-otlp-grpcOTLP via gRPC
@opentelemetry/exporter-jaegerJaeger native
@opentelemetry/exporter-zipkinZipkin
Vendor-specificDatadog, New Relic, Honeycomb, …

Pick by your backend’s preferred protocol. OTLP-over-HTTP is the most general — works with the OpenTelemetry Collector, which then routes to any backend.

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 attributes are stamped on every span and the most useful place to put global context (service name, version, region, pod name).

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

Bring your own SDK + exporter combo — the framework doesn’t bundle either. It only needs the @opentelemetry/api namespace you pass to withApi.

The OTel SDK ties traces, metrics, and logs together via shared context — but the framework ships no OTel metrics bridge. For metrics, use the framework’s Prometheus exporter (scrape it into an OpenTelemetry Collector if you want it in your OTLP pipeline) or the prom-client adapter.

For logs, there is an OTel bridge, with the same pass-in-the-namespace shape. ActorSystemOptions.withOtelLogs(...) is the logging counterpart to enableOtel: the system builds the logger from the @opentelemetry/api-logs namespace you hand it, and names it from the logger-name and logger-version leaves of the same actor-ts.tracing block, under the options in the same per-field way. otelLogger(...), the counterpart to otelTracer, is the pure path beneath it. See the OTLP-Logs pipeline.