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 chain-owned context. Authenticated execution context carries 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 and trusted handler. The generic lifecycle contract, completion onion, identity registry, and contained runner live only in src/extensions/observation.ts. 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. Their failures are isolated at the call boundary. 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 events and spans
• L6-L8 (Execution): Emits protected operation, statement, transaction, batch, segment, connection, and cache lifecycle facts

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.