---
title: Logging
description: Structured query, cache, and error logs
icon: file-text
---

Configure logging through the official instrumentation extension:

```ts
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`.

```ts
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.
