# @imqueue/datadog 3.2.0 · API reference

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

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:

```typescript
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:

```typescript
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()](https://imqueue.org/api/datadog/latest/datadog.trace/) / [traceEnd()](https://imqueue.org/api/datadog/latest/datadog.traceend/) and the [traced()](https://imqueue.org/api/datadog/latest/datadog.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](https://imqueue.org/api/datadog/latest/datadog.imqclientplugin/) | Traces outgoing `@imqueue` RPC calls — the CLIENT half of the `imq` integration, producing the `imq.request` span. |
| [ImqPlugin](https://imqueue.org/api/datadog/latest/datadog.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](https://imqueue.org/api/datadog/latest/datadog.imqserverplugin/) | Traces incoming `@imqueue` RPC calls — the SERVER half of the `imq` integration, producing the `imq.response` span. |


## Enumerations


| Enumeration | Description |
| --- | --- |
| [TraceKind](https://imqueue.org/api/datadog/latest/datadog.tracekind/) | Which side of a call a span describes. Reported as Datadog's `span.kind` tag. |


## Functions


| Function | Description |
| --- | --- |
| [allowPluginEnvConfig(id)](https://imqueue.org/api/datadog/latest/datadog.allowpluginenvconfig/) | 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()](https://imqueue.org/api/datadog/latest/datadog.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)](https://imqueue.org/api/datadog/latest/datadog.installhooks/) | 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()](https://imqueue.org/api/datadog/latest/datadog.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)](https://imqueue.org/api/datadog/latest/datadog.publishload/) | Announces a loaded module to the tracer's plugin manager, which is what makes it instantiate and configure the registered plugin. |
| [registerPlugin()](https://imqueue.org/api/datadog/latest/datadog.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)](https://imqueue.org/api/datadog/latest/datadog.trace/) | 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/datadog/latest/datadog.traceend/) with the same name. |
| [traced(options)](https://imqueue.org/api/datadog/latest/datadog.traced/) | 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)](https://imqueue.org/api/datadog/latest/datadog.traceend/) | Finishes the span [trace()](https://imqueue.org/api/datadog/latest/datadog.trace/) opened under this name and releases it, so the name can be reused. |


## Interfaces


| Interface | Description |
| --- | --- |
| [CallHooks](https://imqueue.org/api/datadog/latest/datadog.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](https://imqueue.org/api/datadog/latest/datadog.compositepluginconstructor/) | Static shape of a `CompositePlugin` subclass — an integration made of several named halves that can be configured independently. |
| [DDChannel](https://imqueue.org/api/datadog/latest/datadog.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](https://imqueue.org/api/datadog/latest/datadog.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](https://imqueue.org/api/datadog/latest/datadog.startspanoptions/) | Options accepted by `TracingPlugin#startSpan()`. |
| [TracedOptions](https://imqueue.org/api/datadog/latest/datadog.tracedoptions/) | Options for the [traced()](https://imqueue.org/api/datadog/latest/datadog.traced/) method decorator. Every field is optional at the call site — `traced()` takes a `Partial` of this and fills the rest in. |
| [TraceTags](https://imqueue.org/api/datadog/latest/datadog.tracetags/) | Datadog span tags as a flat string map. |
| [TracingPluginConstructor](https://imqueue.org/api/datadog/latest/datadog.tracingpluginconstructor/) | Static shape of a `TracingPlugin` subclass. The statics are how the tracer derives which channels a plugin subscribes to. |
| [TracingPluginType](https://imqueue.org/api/datadog/latest/datadog.tracingplugintype/) | Structural type of dd-trace's `TracingPlugin`. Only the members this package actually uses are described. |


## Variables


| Variable | Description |
| --- | --- |
| [CALL\_CONTEXT](https://imqueue.org/api/datadog/latest/datadog.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](https://imqueue.org/api/datadog/latest/datadog.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](https://imqueue.org/api/datadog/latest/datadog.client_operation/) | Operation traced on the calling side of an imq RPC call. |
| [clientChannels](https://imqueue.org/api/datadog/latest/datadog.clientchannels/) | Channels carrying client-side (outgoing call) events. |
| [clientHooks](https://imqueue.org/api/datadog/latest/datadog.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](https://imqueue.org/api/datadog/latest/datadog.compositeplugin/) | Base class grouping several plugins under a single integration name. |
| [IMQ\_COMPONENT](https://imqueue.org/api/datadog/latest/datadog.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](https://imqueue.org/api/datadog/latest/datadog.load_channel/) | Name of the diagnostics channel the tracer's plugin manager listens on to learn that an instrumented module has been loaded. |
| [pluginRegistry](https://imqueue.org/api/datadog/latest/datadog.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](https://imqueue.org/api/datadog/latest/datadog.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](https://imqueue.org/api/datadog/latest/datadog.server_operation/) | Operation traced on the handling side of an imq RPC call. |
| [serverChannels](https://imqueue.org/api/datadog/latest/datadog.serverchannels/) | Channels carrying server-side (incoming call) events. |
| [serverHooks](https://imqueue.org/api/datadog/latest/datadog.serverhooks/) | Hooks tracing incoming calls, reading the propagated context from the request. `this` is the `IMQService` instance, whose `name` identifies it. |
| [TracingPlugin](https://imqueue.org/api/datadog/latest/datadog.tracingplugin/) | Base class every tracing plugin derives from. |