# traceStart() function · @imqueue/opentelemetry

Source: https://imqueue.org/api/opentelemetry/latest/opentelemetry.tracestart/
Published: 2026-08-01
Author: @imqueue maintainers (https://github.com/imqueue)
Package: @imqueue/opentelemetry 4.0.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/opentelemetry/latest/opentelemetry.traceend/) with the same name.

**Signature:**

```typescript
export declare function traceStart(name: string, tags?: TraceAttributes, tracerName?: string): void;
```

## Parameters


| Parameter | Type | Description |
| --- | --- | --- |
| name | string | span name, and the key [traceEnd()](https://imqueue.org/api/opentelemetry/latest/opentelemetry.traceend/) will close it by |
| tags | [TraceAttributes](https://imqueue.org/api/opentelemetry/latest/opentelemetry.traceattributes/) | _(Optional)_ attributes to set on the span at creation; values must be strings |
| tracerName | string | _(Optional)_ tracer to create the span with, `'basic'` by default |


**Returns:**

void

## Exceptions

TypeError if a span under this name is already open

## Remarks

Spans started here are held in a module-level registry keyed by `name`, which is what lets [traceEnd()](https://imqueue.org/api/opentelemetry/latest/opentelemetry.traceend/) find one from an unrelated call site. Two consequences follow, and both matter:

- A name may have only ONE span open at a time. Starting a second under a live name throws rather than silently replacing it, since replacing would leak the first span forever. - A span left unclosed is never exported. Prefer [traced()](https://imqueue.org/api/opentelemetry/latest/opentelemetry.traced/), or a `try`/`finally` around the [traceEnd()](https://imqueue.org/api/opentelemetry/latest/opentelemetry.traceend/) call, wherever the block can throw.

The span is created standalone, NOT as a child of whatever span is currently active, and it is not made active for the code in between. Use it to time a region, not to parent the spans that region creates.

## Example


```typescript
import {
    traceStart,
    traceEnd,
} from '@imqueue/opentelemetry';

traceStart('import-batch', { 'batch.size': String(rows.length) });

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