Observability

Four plugins that ship with the engine. All built on the same plugin surface. None are wired up by default — register the ones you want.

#The four

Plugin	Use it for
`consoleLogger`	Local dev. One line per query to stdout.
`slowQueryLogger`	Production alerting. Fires a callback only when a query exceeds a latency threshold.
`structuredLogger`	Production log shipping. Emits a `LogRecord` per query for pino / winston / Datadog.
`openTelemetryPlugin`	Distributed tracing. Wraps every query in an OTel span.

#consoleLogger — dev

10 lines


1import { consoleLogger } from 'zanith';
2 
3await createZanith({
4  adapter, models,
5  plugins: [consoleLogger({ slowMs: 200 })],
6});
7 
8// · 4ms rows=10 SELECT id, email, name, created_at FROM users WHERE …
9// ⚠ slow 312ms rows=1000 SELECT … FROM orders ORDER BY created_at DESC
10// ✗ 12ms INSERT INTO users … — duplicate key value violates unique constraint

Option	Default	Effect
`slowMs`	200	Queries above this latency get a `⚠ slow` tag.
`truncate`	240	Truncate SQL longer than this in the printed line.

#slowQueryLogger — alerting

Healthy queries don't spam your logs. Only queries above thresholdMs fire the callback.

18 lines


1import { slowQueryLogger } from 'zanith';
2import * as Sentry from '@sentry/node';
3 
4plugins: [
5  slowQueryLogger({
6    thresholdMs: 500,
7    onSlow: (info) => {
8      Sentry.captureMessage('slow query', {
9        level: 'warning',
10        extra: {
11          sql: info.sql,
12          rowCount: info.rowCount,
13          elapsedMs: info.elapsedMs,
14        },
15      });
16    },
17  }),
18],

#structuredLogger — JSON line per query

Pass a sink and you get a LogRecord per query. Wrap your logger in the sink to inject request id, user id, or trace id from AsyncLocalStorage.

14 lines


1import pino from 'pino';
2import { structuredLogger } from 'zanith';
3 
4const log = pino();
5 
6plugins: [
7  structuredLogger({
8    sink: (record) => {
9      const ctx = requestContext.get();
10      log[record.level]({ ...record, requestId: ctx?.requestId });
11    },
12    warnAboveMs: 200,
13  }),
14],

#LogRecord shape

10 lines


1interface LogRecord {
2  level: 'info' | 'warn' | 'error';
3  event: 'query' | 'query_error';
4  sql: string;
5  paramCount: number;
6  rowCount?: number;
7  elapsedMs: number;
8  error?: { message: string; name: string };
9  context?: Record<string, unknown>;
10}

Option	Default	Effect
`sink`	required	Receives one record per query. Sync or async.
`warnAboveMs`	200	Latency above this becomes `level: 'warn'`.
`maxSqlLength`	1000	Truncate SQL longer than this in records.

#openTelemetryPlugin — tracing

The engine doesn't depend on @opentelemetry/api — pass in the tracer (or a wrapper around it) so version pinning stays on the application side.

11 lines


1import { trace } from '@opentelemetry/api';
2import { openTelemetryPlugin } from 'zanith';
3 
4plugins: [
5  openTelemetryPlugin({
6    tracer: trace.getTracer('zanith'),
7    spanName: 'db.query',
8    includeSql: true,
9    maxSqlLength: 2000,
10  }),
11],

#Span attributes

Attribute	Value
`db.system`	`'postgres'` / `'sqlite'` / dialect name
`db.operation_kind`	`'execute'` or `'executeRaw'`
`db.statement`	Truncated SQL — disabled with `includeSql: false`
`db.params.count`	Parameter count (not values)
`db.row_count`	Set on the result hook
`db.elapsed_ms`	Set on the result / error hook

#Compose them

Loggers compose freely — register every one you want. The engine runs them in registration order and a slow one slows the query, so prefer fire-and-forget sinks.

10 lines


1plugins: [
2  // Local console output, only when developing.
3  ...(process.env.NODE_ENV === 'development' ? [consoleLogger()] : []),
4  // Always shipped to the log aggregator.
5  structuredLogger({ sink: (r) => log.info(r) }),
6  // Always traced.
7  openTelemetryPlugin({ tracer: trace.getTracer('zanith') }),
8  // Slow path goes to Sentry too.
9  slowQueryLogger({ thresholdMs: 1000, onSlow: shipToSentry }),
10],