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