Class DurableTelemetryService

Emits OpenTelemetry spans for durable workflow execution. All methods are no-ops when no OTel SDK is registered — @opentelemetry/api returns a no-op tracer by default, so there is zero overhead without a configured exporter.

Span Categories

Span	When	Mode
WORKFLOW/START/{name}	First execution (not replay)	info
WORKFLOW/COMPLETE/{name}	Workflow returns successfully	info
WORKFLOW/ERROR/{name}	Workflow throws a fatal error	info
ACTIVITY/{name}	Real wall-clock activity execution on the worker	info
DISPATCH/{type}/{name}/{idx}	Operation dispatched (first execution only)	debug
RETURN/{type}/{name}/{idx}	Operation result returned (with ac/au duration)	debug

Gating

• isEnabled() — true when HMSH_TELEMETRY is set (any value)
• isVerbose() — true only when HMSH_TELEMETRY === 'debug'

In info mode, engine-layer spans (stream hops, DAG activity spans) are suppressed for durable workflows — only the spans above are emitted. This keeps dashboards clean and focused on the user's workflow story. Set HMSH_TELEMETRY=debug to also see engine internals and per-operation DISPATCH/RETURN spans.

Setup

Register an OTel SDK with a trace exporter before starting workers:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';

const sdk = new NodeSDK({
  resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: 'my-service' }),
  traceExporter: new OTLPTraceExporter({
    url: 'https://api.honeycomb.io/v1/traces',
    headers: { 'x-honeycomb-team': process.env.HONEYCOMB_API_KEY },
  }),
});
sdk.start();
Copy

# Concise workflow telemetry (recommended for production)
HMSH_TELEMETRY=info node worker.js

# Full operational detail (debugging)
HMSH_TELEMETRY=debug node worker.js
Copy