Instrumentation
Official tracing, logging, and diagnostic disclosure
Instrumentation is an official client extension. It presents tracing and
structured logging from VibORM’s lifecycle units, read through a unit part,
and contains its own failures, so telemetry never changes the application.
Its diagnostics go to a disclosure
part, which says what an error thrown by a call of the chain may carry; with
neither tracing nor logging, the extension is that part alone.
import { createClient } from "viborm";
import { instrumentation } from "viborm/instrumentation";
const client = createClient({ schema, driver }).$extends(
instrumentation({
tracing: { includeSql: false, includeParams: false },
logging: {
query: true,
cache: true,
error: true,
},
diagnostics: { includeSql: false, includeParams: false },
})
);
createClient({ instrumentation: ... }) is not a supported configuration.
The fixed-name instrumentation() extension is the sole public owner.
Independent disclosure channels
Tracing, logging, and thrown-error diagnostics each own separate SQL and
parameter disclosure settings. Both default to false. Enabling disclosure
for one channel does not enable it for another.
VibORM snapshots hostile inputs once at the disclosure boundary. Raw provider messages and undeclared fields are redacted by default; stable provider codes remain available for retry and incident classification. Cache keys and custom cache suffixes never appear in public units, spans, or logs.
For incident diagnosis, enable the existing diagnostic channel explicitly:
instrumentation({
diagnostics: { includeProviderDetails: true, includeCallsite: true },
logging: { error: event => console.error(JSON.stringify(event)) },
})
Both flags default to false. includeProviderDetails retains bounded own-data
provider message, detail, and hint values in the sanitized cause, with URL
credentials, named passwords/tokens, and bearer credentials redacted. Provider
text can still contain application data, so choose disclosure deliberately.
Migration commands of a client extended with this extension
(createMigrationClient(client)) disclose their failures under the same
diagnostics; only its diagnostics, never its units, reach migration
statements.
includeCallsite captures meta.callsite when a deferred raw or model operation
is created, before its later await; ordinary operations allocate no diagnostic
stack. The selected details and callsite survive official error logs and JSON
serialization. SQL and parameter disclosure remain independent per channel.
Serialized validation errors retain the canonical class, message, boundary, and
issue paths. Standard error.cause and originalCause reference the same
sanitized underlying error. Failure spans retain error.type,
viborm.error.code, and an available db.response.sqlstate, without provider
messages or parameter values.
Lifecycle coverage
Official instrumentation reads the same real units any unit part sees:
logical operation, physical statement, public array batch, transaction,
savepoint, connection, and the cache units the cache emits.
- A native array produces one batch, N logical operations, and one statement unit for its one provider submission. It produces no fictional transaction.
- A fallback array uses the real transaction or savepoint lifecycle.
- Cache revalidation contains the nested cache set and marker cleanup while the stale application result stays authoritative.
- Connect and disconnect each produce one connection lifecycle.
Logical operation spans begin before the first moments of the extensions’
call parts and finish after their second moments’ post-work. Execute spans
begin at the provider dispatch boundary, after statement rewriting, rendering
and client acquisition. Correlation
is carried by the authenticated execution context, so clients sharing a driver
or cache keep isolated spans and logs.
Present your own units
The instrumentation presents what an extension notes on a unit, whoever
noted it: it knows no extension’s units by name. The cache presents its
cache units this way. A note is a plain object (InstrumentationNote,
from viborm/instrumentation):
| Member | When it is read | What is presented |
|---|---|---|
span |
On a unit of your own kind (work), as the unit starts: give it as work’s note |
The unit is traced as a span of that name, a root span if root, with the db.* attributes of database (what database(x) gives), the call’s correlation and attributes |
attributes |
Noted later on that unit | Set on its span when the unit ends; an attribute given undefined is left out, the correlation’s included |
log |
On a unit of your own kind: as it starts if noted by then, else when it ends. On the call’s own unit (a note on c or run): "cache" only, after the call ends |
A log event at that level ("query", "cache", "error"), at at, naming model and operation (the unit’s own by default), with error and meta |
import { around, extension, note, work } from "viborm";
const lookups = extension(
"lookups",
around(() => async (run) => {
await work(
run,
{
kind: "lookup",
operation: "hint",
note: { span: "app.lookup", attributes: { "lookup.source": "edge" } },
},
async (u) => {
note(u, { attributes: { "lookup.result": "warm" } });
}
);
note(run, { log: "cache", at: Date.now(), meta: { event: "hit" } });
return run();
})
);
What a note may not set is dropped, never refused: telemetry never fails the call it observes.
- Span names of a call.
viborm.operation,viborm.execute,viborm.transaction,viborm.connectandviborm.disconnectname the spans the library presents for a call’s own units. A note naming one leaves its unit without a span (its logs are still presented), exceptviborm.operationwithroot: true: an operation of your own outside any call’s trace, as the cache’s background revalidation is. Any other name is yours,viborm.cache.*included: the instrumentation does not know the cache’s names. - Statement attributes. Every attribute under
db.query.(db.query.text,db.query.summary,db.query.parameter.*) is dropped from a note, whateverincludeSqlandincludeParamssay: only the library presents a statement’s text and parameters, from the statement it sent, and only as those settings let it. WithincludeSqloff no span or log carries statement text; withincludeParamsoff none carries parameters; a note cannot change that. - Logs of a call. A call’s
queryanderrorlogs are the library’s account of its work: a note on the call’s own unit cannot add one, so a call that succeeded never logs an error. Notes on a unit of your own kind may log at any level. - Status. A span ends failed when its unit fails, sanitized as every span’s failure is. A note cannot change the status of any span: on your own unit, fail the work instead.
- Errors and metadata. A note’s
erroris presented throughdisclosed, as the errors of the library’s own logs are (an error that is not VibORM’s has its details redacted); itsmetakeeps only the log metadata vocabulary (event:"bypass","hit","miss","revalidate";status:"cache-set-failed","error","fresh","stale","start","success"); any other key or value is dropped.
Any other attribute is presented as given, under any disclosure setting:
what it holds is the extension author’s responsibility. Do not put
statement text, parameter values or anything your application treats as
secret under a name of your own (lookup.query, lookup.user): the
instrumentation cannot tell it is a statement or a parameter.
Failure containment
Telemetry is observational. Instrumentation contains its own failures: a logger callback, console method, OTel provider, or dynamic OTel import can throw, reject, or never settle without changing the application value, application error, transaction outcome, or commit certainty. The core selects and deduplicates the application error; instrumentation presents only normalized and disclosure-approved facts.
A unit part of your own has no such containment: VibORM awaits it, and what
it throws fails the call. It reads the facts it needs through words
(text(u), parameters(u), failure(u), …), produced only when read, and
presents a failure through disclosed, as this extension does; see
Create an extension.
Optional OpenTelemetry dependency
@opentelemetry/api is an optional peer dependency. When you hand the
extension a tracer (tracing: { tracer }, for example Cloudflare Workers’
tracing from cloudflare:workers), VibORM never imports the package and
tracing is ready at once. Otherwise the package is loaded dynamically; if it is
absent or setup fails, database work proceeds normally. The first operation
waits for that load inside its operation unit, so it still enters the
correct active context; later operations do not wait. See Tracing.