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

Logging

Structured query, cache, 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,
      error: (event, log) => {
        errorTracker.capture(event.error);
        log();
      },
      includeSql: false,
      includeParams: false,
    },
  })
);
Option Meaning
all Fallback handler for every enabled level
query Physical provider execution
cache Cache hit, miss, stale, bypass, set, and revalidation events
error One selected normalized operation failure
includeSql Disclose rendered SQL to logging only
includeParams Disclose snapshotted parameters to logging only

A level accepts true for plain console output or a callback. The built-in logger adds no ANSI escape codes, so captured logs remain readable. A callback can pass the sanitized event to a JSON logger. Durations are milliseconds; the current lifecycle clock has millisecond resolution. 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.

Was this page helpful?