opentelemetry package

OpenTelemetry instrumentation for @imqueue/rpc — distributed traces across IMQ service calls, with no changes to service or client code.

Register ImqueueInstrumentation once at start-up and every RPC made through @imqueue/rpc produces a CLIENT span on the calling side and a SERVER span on the handling side, linked into one trace. For anything the automatic spans do not cover there are two manual tools: the traced() method decorator, and the traceStart()/traceEnd() pair for an arbitrary block of code.

Remarks

Trace context travels in the IMQ request metadata, so a call chain stays a single trace across processes and queues. The instrumentation works by mutating @imqueue/rpc's exported default option singletons rather than by hooking module loading — see ImqueueInstrumentation for why that matters and what it implies.

This package only *produces* spans. Exporting them is the host application's job: register a tracer provider from the OpenTelemetry SDK, or the spans go nowhere.

Example

import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { ImqueueInstrumentation } from '@imqueue/opentelemetry';

new NodeTracerProvider().register();

registerInstrumentations({
    instrumentations: [new ImqueueInstrumentation()],
});

Classes

Class

Description

ImqueueInstrumentation

OpenTelemetry instrumentation for @imqueue/rpc.

@imqueue/rpc exposes its default client/service options as mutable singletons and calls their beforeCall/afterCall/wrapCall hooks around every RPC. Rather than intercepting module loading (which, for an ESM package, needs import-in-the-middle and rewrites the whole module graph), this patches those singletons directly on enable() — robust and free of ESM-hook fragility.

Client calls use beforeCall/afterCall: a CLIENT span is started as a child of the active context and its trace context is injected into the request metadata for propagation, then ended on response. - Service calls use wrapCall (the around-hook): the SERVER span is started from the propagated parent and the handler is run **inside** that span's context (context.with), so any spans it or its downstream calls create nest correctly.

Two consequences of patching singletons rather than intercepting imports. Clients and services constructed BEFORE enable() copy the defaults at construction time and are not traced — so register the instrumentation before building any of them, which registerInstrumentations at start-up does naturally. And if the @imqueue/rpc this resolves is a different copy from the one the application imported (duplicate installs at different tree depths), the patch lands on the wrong singletons and no spans appear.

Enumerations

Enumeration	Description
AttributeNames	Attribute keys this package sets on every span it creates.
SpanNames	The span names this package emits. There are only three, and they identify the KIND of operation, not which method ran — the specific method is carried by the `resource.name` attribute (AttributeNames.RESOURCE_NAME).
TraceKind	Which side of a call a span describes. Written to the `span.kind` attribute, and mapped onto OpenTelemetry's own `SpanKind` when the span is created.

Functions

Function	Description
traced(options)	Builds a method decorator that wraps each call to the decorated method in its own span, ending it when the method returns — or when the promise it returned settles.
traceEnd(name)	Ends the span traceStart() opened under this name and releases it, so the name can be reused.
traceStart(name, tags, tracerName)	Starts a named span for tracing a block of code that no decorator can wrap, to be closed later by traceEnd() with the same name.

Interfaces

Interface	Description
IMQCallHooks	The subset of `@imqueue/rpc`'s default option singletons this instrumentation mutates. `beforeCall`/`afterCall` are used on the client; `wrapCall` (the around-hook) is used on the service so the handler runs inside the span's OpenTelemetry context.
RpcModule	The `@imqueue/rpc` default option singletons this instrumentation patches.
TraceAttributes	Span attributes as a flat string map.
TracedOptions	Options for the `traced` method decorator. Every field is optional at the call site — `traced()` takes a `Partial` of this and fills the rest in.

Read this page as plain markdown — no HTML, no navigation. For pasting into an LLM, or for an agent to fetch.