# trace() function · @imqueue/datadog

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

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.

**Signature:**

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

## Parameters


| Parameter | Type | Description |
| --- | --- | --- |
| name | string | span name, and the key [traceEnd()](https://imqueue.org/api/datadog/latest/datadog.traceend/) will close it by |
| tags | [TraceTags](https://imqueue.org/api/datadog/latest/datadog.tracetags/) | _(Optional)_ tags to set on the span at creation |


**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()](https://imqueue.org/api/datadog/latest/datadog.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()](https://imqueue.org/api/datadog/latest/datadog.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


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

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

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