logger

Every export of @kitr/logger, read from the published type definitions. The guide shows them in use.

@kitr/logger

createLogger

function createLogger(options?: LoggerOptions): Logger;

Create a logger without the provider, for scripts, packages and tests.

defineConfig

const defineConfig: <const C extends LoggerOptions>(config: C) => C;

Types config/logger.ts. Returns its argument unchanged.

loggerProvider

const loggerProvider: import("@kitr/core").KitrProvider;

Binds logger into the container from config/logger.ts, on the server and in the browser. In development with devtools, every record is also mirrored to the Log panel.

silentLogger

const silentLogger: Logger;

A logger that discards everything, for tests.

Logger

interface Logger {
  /** The lowest level written. Settable at run time; children copy it when created. */
  level: LogLevel;
  /** Write at `trace`: step-by-step detail. */
  trace(msg: string, fields?: Record<string, unknown>): void;
  /** Write at `debug`: detail for development. */
  debug(msg: string, fields?: Record<string, unknown>): void;
  /** Write at `info`: something that happened. */
  info(msg: string, fields?: Record<string, unknown>): void;
  /** Write at `warn`: something odd that did not fail. */
  warn(msg: string, fields?: Record<string, unknown>): void;
  /** Write at `error`. Pass an `Error` to keep its name, message, stack and code under `err`. */
  error(msg: string | Error, fields?: Record<string, unknown>): void;
  /** Write at `fatal`. Pass an `Error` to keep its name, message, stack and code under `err`. */
  fatal(msg: string | Error, fields?: Record<string, unknown>): void;
  /** A logger that adds `bindings` to every record, optionally under another name. */
  child(bindings: Record<string, unknown>, name?: string): Logger;
  /** Run `fn`, then log `msg` at info with `durationMs`, even when it throws; returns its result. */
  time<T>(msg: string, fn: () => Promise<T>, fields?: Record<string, unknown>): Promise<T>;
}

A logger: one method per level, child loggers that carry fields, and timing. Bound as logger by the provider.

LoggerOptions

interface LoggerOptions {
  /** The lowest level written. Default `info`. */
  level?: LogLevel;
  /** Shown as `[name]` in pretty output and as `name` in JSON. */
  name?: string;
  /** 'pretty' for terminals, 'json' for production. Default: pretty in dev, json otherwise. */
  format?: 'pretty' | 'json';
  /** Fields merged into every record (e.g. requestId). */
  bindings?: Record<string, unknown>;
  /** Where lines go. Default: console. */
  write?: (line: string, record: LogRecord) => void;
}

Options for createLogger, and the shape of config/logger.ts.

LogRecord

interface LogRecord {
  /** The level it was written at. */
  level: LogLevel;
  /** When it was written, as an ISO 8601 string. */
  time: string;
  /** The logger's name, when it has one. */
  name?: string;
  /** The message, or the error's message. */
  msg: string;
  /** Bindings, fields, `err` for errors and `durationMs` from `time()`. */
  [key: string]: unknown;
}

One log line as an object: what write receives and what json format serialises.

LoggerConfig

type LoggerConfig = LoggerOptions;

The options in config/logger.ts; the same as LoggerOptions.

LogLevel

type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';

A log level, lowest to highest; silent drops everything and is for configuration only.