# Logger API

Every export of kitr/logger, with its signature.

Every export of `kitr/logger`, read from the published type definitions. The [guide](/packages/logger) shows them in use.

## kitr/logger

### createLogger

```ts
function createLogger(options?: LoggerOptions): Logger;
```

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

### defineConfig

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

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

### loggerProvider

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

```ts
const silentLogger: Logger;
```

A logger that discards everything, for tests.

### Logger

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

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

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

```ts
type LoggerConfig = LoggerOptions;
```

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

### LogLevel

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

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

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->