datadog package

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

Import this package instead of dd-trace and call init() as usual. Every RPC then produces an imq.request span on the calling side and an imq.response span on the handling side, linked into one trace:

import tracer from '@imqueue/datadog';

tracer.init();

export default tracer;

Remarks

The default export IS the dd-trace tracer, and this package re-exports everything dd-trace does, so it is a drop-in replacement — every dd-trace API and option keeps working. What it adds is an imq integration registered with the tracer, plus the manual tools below.

Both halves of the integration can be configured like any other dd-trace plugin, together or separately:

tracer.use('imq', { client: false });     // trace incoming calls only
tracer.use('imq', { service: 'my-api' }); // report both halves as `my-api`

Ordering matters in one direction only. The hooks are installed at IMPORT time, before init(), because @imqueue/rpc reads its default options when a client or service is constructed — so any client or service built after the import is traced. init() is what enables the integration and starts reporting.

An ES module, as @imqueue/rpc is from v3 on: import it, do not require it. Needs @imqueue/rpc 3.x and dd-trace 6.x.

For manual spans inside application code there are trace() / traceEnd() and the traced() method decorator. Setting DISABLE_DD_SELF_TRACES=1 stops the agent tracing its own HTTP calls to Datadog while leaving other outbound requests traced.

Classes

Class	Description
ImqClientPlugin	Traces outgoing `@imqueue` RPC calls — the CLIENT half of the `imq` integration, producing the `imq.request` span.
ImqPlugin	The `imq` integration, grouping both halves of an RPC call under a single name so that they share configuration and can be switched independently.
ImqServerPlugin	Traces incoming `@imqueue` RPC calls — the SERVER half of the `imq` integration, producing the `imq.response` span.

Enumerations

Enumeration	Description
TraceKind	Which side of a call a span describes. Reported as Datadog's `span.kind` tag.

Functions

Function	Description
allowPluginEnvConfig(id)	Adds `DD_TRACE_<ID>_ENABLED` to the tracer's configuration allow-list. The plugin manager reads that variable while enabling any plugin, and dd-trace throws a "Missing env/configuration in supported-configurations.json" error for every name it does not know — which would take the whole process down through an uncaught exception, since the lookup happens inside a diagnostics channel subscriber.
enablePlugin()	Enables the registered plugin. Separate from registration because the tracer's plugin manager ignores the announcement until it has a configuration, which `tracer.init()` gives it.
installHooks(options, hooks)	Installs the hooks into an `@imqueue/rpc` default options object. Hooks the user configured themselves are preserved and invoked after the tracing ones, so enabling tracing never silently drops application behaviour. Calling this twice on the same object is a no-op.
instrument()	Installs the tracing hooks into `@imqueue/rpc`. The hooks land on the default client and service options, so every client and service created afterwards is traced without touching application code. This deliberately does not use dd-trace's automatic module patching: that path needs the tracer loaded before `@imqueue/rpc`, which cannot be guaranteed for an ESM application, whereas the default options are read when a client or service is constructed — always after this call.
publishLoad(name)	Announces a loaded module to the tracer's plugin manager, which is what makes it instantiate and configure the registered plugin.
registerPlugin()	Registers the `imq` integration with the tracer. Safe to call more than once, and safe to call before `tracer.init()` — the tracer only instantiates the plugin once it has been configured.
trace(name, tags)	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.
traced(options)	Builds a method decorator that wraps each call to the decorated method in its own span, finishing it when the method returns — or when the promise it returned settles.
traceEnd(name)	Finishes the span trace() opened under this name and releases it, so the name can be reused.

Interfaces

Interface	Description
CallHooks	The pair of hooks `@imqueue/rpc` invokes around a call. Structurally equal to `IMQBeforeCall`/`IMQAfterCall`, but expressed without a type parameter so the same shape works for both client and service option objects.
CompositePluginConstructor	Static shape of a `CompositePlugin` subclass — an integration made of several named halves that can be configured independently.
DDChannel	The subset of a diagnostics channel this package relies on. Channels are taken from dd-trace itself rather than from `node:diagnostics_channel` so that publisher and subscriber are guaranteed to be the very same channel object the tracer's plugins subscribe to.
ImqCallContext	Everything the plugins need to describe a call. Instances are created by the instrumentation in `./instrumentation` and travel through the channels; the plugins add `span` to them and read it back when the call completes.
StartSpanOptions	Options accepted by `TracingPlugin#startSpan()`.
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.
TraceTags	Datadog span tags as a flat string map.
TracingPluginConstructor	Static shape of a `TracingPlugin` subclass. The statics are how the tracer derives which channels a plugin subscribes to.
TracingPluginType	Structural type of dd-trace's `TracingPlugin`. Only the members this package actually uses are described.

Variables

Variable	Description
CALL_CONTEXT	Property an in-flight call's context is kept under, on the request itself, so that `afterCall` can finish the span `beforeCall` started. Never serialized, see `hideContextFromJson()`.
CARRIER_KEY	Key inside `request.metadata` the propagated trace context travels in. Kept as it always was, so a service running this package still understands calls made by a client running an older release, and the other way round.
CLIENT_OPERATION	Operation traced on the calling side of an imq RPC call.
clientChannels	Channels carrying client-side (outgoing call) events.
clientHooks	Hooks tracing outgoing calls, injecting the current context into the request. `this` is the `IMQClient` instance, whose `serviceName` names the service being called.
CompositePlugin	Base class grouping several plugins under a single integration name.
IMQ_COMPONENT	Integration name. Together with the operation it forms the channel prefix dd-trace plugins subscribe to (`apm:<component>:<operation>:<event>`), so it has to stay in sync with the plugin classes in `./client` and `./server`.
LOAD_CHANNEL	Name of the diagnostics channel the tracer's plugin manager listens on to learn that an instrumented module has been loaded.
pluginRegistry	The tracer's plugin registry, keyed by the module name the load event is published for. Assigning into it is the only way for a package that does not live inside dd-trace to make its plugin discoverable.
REGISTRY_KEY	Registry key the plugin is announced under. It is the name of the traced package, matching what dd-trace uses for its own integrations.
SERVER_OPERATION	Operation traced on the handling side of an imq RPC call.
serverChannels	Channels carrying server-side (incoming call) events.
serverHooks	Hooks tracing incoming calls, reading the propagated context from the request. `this` is the `IMQService` instance, whose `name` identifies it.
TracingPlugin	Base class every tracing plugin derives from.

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