---
title: Tracing
description: OpenTelemetry spans from VibORM's lifecycle units
icon: radar
---

Either hand VibORM the tracer your runtime or application already holds (see
[Bring your own tracer](#bring-your-own-tracer); `@opentelemetry/api` is then
not needed), or install the optional OpenTelemetry API, configure its SDK,
and let VibORM find it:

```bash
npm install @opentelemetry/api
```

```ts
import { instrumentation } from "viborm/instrumentation";

const client = createClient({ schema, driver }).$extends(
  instrumentation({
    tracing: {
      includeSql: false,
      includeParams: false,
      ignoreSpanTypes: [/viborm\.cache\./],
    },
  })
);
```

| Option | Type | Default | Meaning |
|---|---|---|---|
| `includeSql` | `boolean` | `false` | Add rendered SQL to execute spans |
| `includeParams` | `boolean` | `false` | Add one attribute per snapshotted parameter |
| `ignoreSpanTypes` | `Array<string \| RegExp>` | `[]` | Skip matching exact span names |
| `tracer` | an object with `startActiveSpan(name, fn)` whose spans have `setAttribute` and `end` | auto-detected | Present spans through this tracer; VibORM then never imports `@opentelemetry/api` |

Ignoring a span does not redirect its late attributes to the active parent.
Cache hit/miss/TTL facts target only their exact cache span.

## Bring your own tracer

By default VibORM imports `@opentelemetry/api` itself, lazily, and asks the
registered global provider for a tracer. That import is a bet on your bundler
and runtime. Where the runtime supplies the tracer, hand it over instead.

On Cloudflare Workers the runtime tracer is `tracing` from `cloudflare:workers`
(the same object as `ctx.tracing`). Enable traces with
`observability.traces.enabled` in your Wrangler configuration, then:

```ts
import { tracing } from "cloudflare:workers";
import { instrumentation } from "viborm/instrumentation";

const client = createClient({ schema, driver }).$extends(
  instrumentation({ tracing: { tracer: tracing } })
);
```

Without it, a Worker's `@opentelemetry/api` has no registered provider, so
`trace.getTracer(...)` and VibORM's own auto-detection both yield no-op spans.

Any OpenTelemetry `Tracer` is accepted too, for example
`trace.getTracer("app")` where your application has registered a provider.

VibORM starts every span with the two-argument `tracer.startActiveSpan(name,
fn)`, the form both accept, and never imports `@opentelemetry/api` itself when
`tracer` is set. Tracing is ready at once: there is no first-operation load to
wait for. `includeSql`, `includeParams`, and `ignoreSpanTypes` apply as they do
without it. What changes:

- Spans nest under the span that is active when you call the client. The
  tracer decides the parent, so a cache revalidation span, which auto-detection
  starts as a new root, nests under the active span instead.
- Attributes are set on the span with `setAttribute` once it starts, rather
  than passed to its creation, and every span has the tracer's default kind.
- Status is set when the span has `setStatus` and failures are recorded when it
  has `recordException`. The Workers runtime span has no `setStatus` yet, so a
  failed operation's span there carries only its end (and the recorded
  exception, on runtimes that provide `recordException`).
- VibORM ends every span it is handed when the operation settles, as
  `startActiveSpan` requires on both platforms.

A tracer that throws, never calls back, calls back late, or calls back twice
cannot stop, skip, or repeat a database operation: the operation runs exactly
once, runs without a span if the tracer has not called back by then, and every
span a callback receives is ended once with the operation's outcome (a span
handed to several operations is ended once, by the first to settle). A span
method that throws, or returns a promise or thenable that rejects through its
own `then`, changes nothing, and VibORM never waits for one. A promise whose
`then` is replaced or whose `constructor` throws cannot be handed a rejection
handler, so its rejection stays unhandled.

## Span families

| Span | Boundary |
|---|---|
| `viborm.operation` | One logical model or raw operation |
| `viborm.execute` | One provider statement submission, or one native provider batch presentation |
| `viborm.transaction` | One real outer transaction |
| `viborm.savepoint` | One real nested savepoint |
| `viborm.batch` | One public array transaction |
| `viborm.connect` / `viborm.disconnect` | Connection lifecycle |
| `viborm.cache.*` | Cache get, set, invalidate, and revalidate work |

There are no separate validate, build, or parse spans. Those stages remain
inside the logical operation span. A native array is not represented as a
transaction. N public physical statement units can feed one native provider
execute span and one query log.

The `statement` unit, and its execute span, begin after statement rewriting
and rendering, immediately before provider execution, so the span records the
exact rewritten and rendered SQL when disclosure is enabled. Verbatim unsafe
raw is never rewritten; its physical execution is still traced, and its text
and parameters appear only where `includeSql` and `includeParams` disclose
them.

## Attributes and correlation

Spans use OpenTelemetry database semantic attributes where applicable:

- `db.system.name` and `db.system.driver`;
- `db.collection.name` and `db.operation.name` on attributed work;
- `viborm.correlation.id` across logical operation, execute, and cache spans;
- `db.query.text` and `db.query.parameter.<index>` only when enabled;
- cache result/TTL and progressive outcome facts on their exact owners.

The active span at each provider call is the corresponding execute span. Two
official clients can share one driver without sharing tracer context,
correlation, disclosure policy, or error attribution.

## Failure and commit semantics

Failed spans use OpenTelemetry error status and exception recording. The
application error remains authoritative and is logged once even when package
boundaries normalize or attach commit certainty to successor errors.

Transaction completion distinguishes acknowledged commit, dispatched but
unacknowledged commit, and pre-commit rollback. Savepoints never claim durable
commit certainty. A committed native provider result remains committed if
later result parsing, cache publication, or a second moment's post-work fails.

Tracing failures are contained. OTel setup, provider callbacks, span mutation,
or span completion cannot block provider release or alter the application.

## Graceful degradation

If `@opentelemetry/api` is not installed and no `tracer` is given, tracing
becomes a no-op and database operations continue. Diagnostics-only and
logging-only instrumentation do not allocate execute-span gates. Ignored execute spans do not read parameters.
