Skip to content
VibORM
Esc
↑↓navigate↵open⌘Jpreview
On this page

L11 - Instrumentation

Observe VibORM operations without changing their query semantics

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 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.

Was this page helpful?