---
title: L11 - Instrumentation
description: Observe VibORM operations without changing their query semantics
icon: activity
---

**Location:** `src/instrumentation/`

## Why This Layer Exists

Production database work needs tracing, structured logs, and safe diagnostics.
L11 creates the instrumentation context shared by the client, query engine,
cache, and drivers so one operation can be followed across layer boundaries.

Instrumentation is optional. When disabled—or when OpenTelemetry is not
installed—the underlying operation still executes with the same result and
error behavior.

## Boundary

L11 records what happened; it does not decide what query to run, alter cache
policy, translate SQL, or recover from failures. SQL and parameter disclosure
remain explicit configuration choices because they may expose sensitive data.
Both `includeSql` and `includeParams` default to `false`.

The public configuration crosses its trust boundary once in the official
`instrumentation()` extension. VibORM copies and freezes disclosure flags,
handlers, and cloned ignore patterns into one context its `unit` part holds.
Authenticated execution context carries the chain that holds it through the
query engine to cache and driver work;
shared drivers never store or choose a client's instrumentation context.

`src/instrumentation/extension.ts` owns that official factory. It is an
ordinary extension: a `unit` part over every unit kind, reading the facts it
discloses through the public words, and a `disclosure` part for thrown
errors. Client, query-engine, cache, executor, and driver code retain only the
lifecycle facts and trigger points each layer alone can know.

User log callbacks, console methods, diagnostic values, and the optional
OpenTelemetry API/provider remain untrusted. Instrumentation isolates their
failures itself: core does not contain the failures of a `unit` part. The tracer wrapper owns exact-once callback execution and keeps
the application result or error authoritative even when a provider span method
fails.

See [Instrumentation](/docs/extensions/instrumentation) for logging, tracing,
and privacy configuration.

## Connection to Other Layers

- **L9 (Client)**: Applies the official extension and creates operation context
- **L10 (Cache)**: Emits `cache` units, with the notes the instrumentation presents as spans and logs
- **L6-L8 (Execution)**: Emits operation, statement, transaction, batch and
  connection units; the cache emits its own `cache` units

## Verification

`pnpm test:layer:instrumentation` runs the fast runtime and public type
contracts. `pnpm test:coverage:instrumentation` runs one worker with a bounded
heap and wall time, writes `coverage/instrumentation`, and enforces 100%
statements, lines, functions, and branches for `src/instrumentation/**/*.ts`.
