Logging

Structured query, cache, warning, and error logs

Configure logging through the official instrumentation extension:

import { instrumentation } from "viborm/instrumentation";

const client = createClient({ schema, driver }).$extends(
  instrumentation({
    logging: {
      query: true,
      cache: true,
      warning: true,
      error: (event, log) => {
        errorTracker.capture(event.error);
        log();
      },
      includeSql: false,
      includeParams: false,
    },
  })
);

A level accepts true for the built-in pretty logger or a callback. A specific level overrides all.

instrumentation({
  logging: {
    all: (event, log) => {
      appLogger.info(event);
      log();
    },
    error: (event) => errorTracker.capture(event.error),
  },
});

Event facts

Log events can carry level, timestamp, duration, model, operation, correlation, a normalized error, disclosure-approved SQL/parameters, and allowlisted metadata. Callbacks receive a sanitized snapshot. They do not receive a mutable driver event, raw provider fields, cache keys, custom cache suffixes, or private lifecycle facts.

Query logs are emitted at the provider execution boundary. In a native array, N public statement units share one provider call and therefore produce one query log. Operation error logging selects one authoritative failure and keeps deduplication evidence when package boundaries normalize or add commit certainty to a successor error.

Cache logs preserve the canonical sequence for miss, fresh hit, stale hit, revalidation start/success/failure, and invalidation. A background failure is normalized and observed without changing the stale application result.

Disclosure and containment

Logging disclosure is independent from tracing and thrown-error diagnostics. Parameters are inspected once for all enabled logging/tracing/diagnostic channels before provider mutation, then each channel receives its approved snapshot.

A logging callback or console failure is contained. It cannot replace the application result or error, prevent another lifecycle consumer from running, alter commit, or become an unhandled rejection.