trace() function

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.

Signature:

export declare function trace(name: string, tags?: TraceTags): void;

Parameters

Returns:

void

Exceptions

TypeError if a span under this name is already open

Remarks

The span is registered under name in a module-level map, which is what lets traceEnd() close it from an unrelated call site. Two consequences follow:

• A name may have only ONE span open at a time. Starting a second under a live name throws rather than replacing the first, which would leak it. - A span never closed is never reported. Use try/finally wherever the block can throw, or reach for traced() instead.

Unlike the OpenTelemetry sibling of this package, the span DOES attach to the currently active span when there is one, so a manual span nests inside the RPC span that surrounds it rather than starting a separate trace.

Example

import { trace, traceEnd } from '@imqueue/datadog';

trace('import-batch', { 'batch.source': 'nightly' });

try {
    await importRows(rows);
} finally {
    traceEnd('import-batch');
}

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