# @imqueue/opentelemetry 4.0.0 · API reference

Source: https://imqueue.org/api/opentelemetry/latest/
Published: 2026-08-01
Author: @imqueue maintainers (https://github.com/imqueue)
Package: @imqueue/opentelemetry 4.0.0 — generated reference, not hand-written

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

Register [ImqueueInstrumentation](https://imqueue.org/api/opentelemetry/latest/opentelemetry.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()](https://imqueue.org/api/opentelemetry/latest/opentelemetry.traced/) method decorator, and the [traceStart()](https://imqueue.org/api/opentelemetry/latest/opentelemetry.tracestart/)/[traceEnd()](https://imqueue.org/api/opentelemetry/latest/opentelemetry.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](https://imqueue.org/api/opentelemetry/latest/opentelemetry.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


```typescript
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](https://imqueue.org/api/opentelemetry/latest/opentelemetry.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](https://imqueue.org/api/opentelemetry/latest/opentelemetry.attributenames/) | Attribute keys this package sets on every span it creates. |
| [SpanNames](https://imqueue.org/api/opentelemetry/latest/opentelemetry.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](https://imqueue.org/api/opentelemetry/latest/opentelemetry.attributenames/)). |
| [TraceKind](https://imqueue.org/api/opentelemetry/latest/opentelemetry.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)](https://imqueue.org/api/opentelemetry/latest/opentelemetry.traced/) | 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)](https://imqueue.org/api/opentelemetry/latest/opentelemetry.traceend/) | Ends the span [traceStart()](https://imqueue.org/api/opentelemetry/latest/opentelemetry.tracestart/) opened under this name and releases it, so the name can be reused. |
| [traceStart(name, tags, tracerName)](https://imqueue.org/api/opentelemetry/latest/opentelemetry.tracestart/) | Starts a named span for tracing a block of code that no decorator can wrap, to be closed later by [traceEnd()](https://imqueue.org/api/opentelemetry/latest/opentelemetry.traceend/) with the same name. |


## Interfaces


| Interface | Description |
| --- | --- |
| [IMQCallHooks](https://imqueue.org/api/opentelemetry/latest/opentelemetry.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](https://imqueue.org/api/opentelemetry/latest/opentelemetry.rpcmodule/) | The `@imqueue/rpc` default option singletons this instrumentation patches. |
| [TraceAttributes](https://imqueue.org/api/opentelemetry/latest/opentelemetry.traceattributes/) | Span attributes as a flat string map. |
| [TracedOptions](https://imqueue.org/api/opentelemetry/latest/opentelemetry.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. |