Integrates OpenTelemetry tracing, metrics, and logging into iii workers. Use when setting up distributed tracing, Prometheus metrics, custom spans, or connecting to observability backends.
Comparable to: Datadog, Grafana, Honeycomb, Jaeger
Use the concepts below when they fit the task. Not every worker needs custom spans or metrics.
registerWorker() with otel config enables telemetry per workerwithSpan(name, opts, fn) wrap async work with trace contextgetMeter() create counters and histogramsThe worker SDK generates spans, metrics, and logs during function execution. These flow to the engine, which exports them via OTLP to a collector (Jaeger, Grafana, Datadog). The engine also exposes a Prometheus endpoint on port 9464 for scraping.
| Primitive | Purpose |
|---|---|
registerWorker(url, { otel }) | Connect worker with telemetry config |
withSpan(name, opts, fn) | Create a custom trace span |
getTracer() | Access OpenTelemetry Tracer directly |
getMeter() | Access OpenTelemetry Meter for custom metrics |
currentTraceId() | Get active trace ID for correlation |
injectTraceparent() | Inject W3C trace context into outbound calls |
onLog(callback, { level }) | Subscribe to log events |
shutdown_otel() | Graceful shutdown of telemetry pipeline |
See ../references/observability.js for the full working example — a worker with custom spans,
Also available in Python: ../references/observability.py
Also available in Rust: ../references/observability.rs metrics counters, trace propagation, and log subscriptions connected to an OTel collector.
Code using this pattern commonly includes, when relevant:
registerWorker('ws://localhost:49134', { otel: { enabled: true, serviceName: 'my-svc' } }) — enable telemetrywithSpan('validate-order', {}, async (span) => { span.setAttribute('order.id', id); ... }) — custom spangetMeter().createCounter('orders.processed') — custom counter metricgetMeter().createHistogram('request.duration') — custom histogram metriconLog((log) => { ... }, { level: 'warn' }) — subscribe to warnings and abovecurrentTraceId() — get active trace ID for correlation with external systemsinjectTraceparent() — propagate trace context to outbound HTTP callsregisterWorker(url, { otel: { enabled: false } }) or OTEL_ENABLED=falseUse the adaptations below when they apply to the task.
otel in registerWorker() config to start collecting traces automaticallycurrentTraceId() to correlate iii traces with external system logsiii-observability in iii-config.yaml for engine-side exporter, sampling ratio, and alertsiii-observability must be enabled in iii-config.yaml for engine-side traces, metrics, and logs. See ../references/iii-config.yaml for the full annotated config reference.
iii-engine-config.iii-functions-and-triggers.iii-observability when the primary problem is SDK-level telemetry: spans, metrics, logs, and trace propagation.iii-observability in the iii engine.