Presets #

A preset is a ready-made destination: you name it in transport and give its options, Kuzzle Logger configures the underlying Pino transport.

const logger = new KuzzleLogger({
  serviceName: 'my-service',
  transport: {
    preset: 'loki',
    level: 'info',
    presetOptions: { host: 'http://localhost:3100' },
  },
});

Preset	Writes to	Requires
`stdout` (default)	Standard output	`pino-pretty` in development
`file`	A file or a file descriptor	–
`loki`	Grafana Loki	`pino-loki` 2.5+ or 3
`kuzzle-elasticsearch`	Elasticsearch, in ECS	`pino-elasticsearch` 8 or 9, `pino-transport-ecs`

The transport packages are optional peer dependencies: install the ones your presets use. Every preset accepts a level (info by default). loki, file and kuzzle-elasticsearch throw an explicit error when their required option is missing.

To write to several destinations, or to use a Pino transport that has no preset, see Transport configuration. The option types are in Preset options.

stdout #

transport: {
  preset: 'stdout';
}

When NODE_ENV is development or not set, entries are pretty-printed with pino-pretty, which must be installed (npm install pino-pretty).
Otherwise, entries are written as JSON lines.

This is the preset used when transport is not set.

file #

transport: {
  preset: 'file',
  presetOptions: { destination: '/var/log/my-app.log' },
}

Option	Default	Description
`destination`	–	Required. File path, or file descriptor (`1` = stdout, `2` = stderr).
`mkdir`	`true`	Creates the directory if needed.
`append`	`true`	Appends to the file instead of overwriting it.

Entries are written as JSON lines.

loki #

transport: {
  preset: 'loki',
  presetOptions: {
    host: 'http://localhost:3100',
    labels: { environment: 'production' },
    propsToLabels: ['namespace'],
  },
}

Option	Default	Description
`host`	–	Required. Loki URL.
`labels`	–	Labels added to every stream. `service_name` is set from `serviceName`, unless `labels.service_name` is provided.
`propsToLabels`	–	Entry fields used as labels, e.g. `['namespace']`. Only use fields with few distinct values.
`headers`	–	HTTP headers of the requests, e.g. `{ Authorization: 'Bearer ...' }`.
`batching`	`true`	Sends entries in batches.
`interval`	`1`	Batching interval, in seconds.
`maxBufferSize`	`10000` (pino-loki 3)	Maximum number of buffered entries while Loki is unreachable; the oldest are dropped. Ignored by pino-loki 2.
`levelMap`	Pino levels, `warn` → `warning`	Mapping of Pino numeric levels to Loki level names.
`structuredMetaKey`	`false`	Entry field sent as Loki structured metadata, e.g. `'meta'`. Disabled by default, including with pino-loki 3.
`timeout`	`30000` (pino-loki default)	Timeout of the requests to Loki, in milliseconds.

The preset gives the same result with pino-loki 2 and 3: it passes interval and maxBufferSize in the batching object read by pino-loki 3, and keeps the top-level interval read by pino-loki 2.

See Grafana dashboards for queries and a ready-made dashboard.

kuzzle-elasticsearch #

transport: {
  preset: 'kuzzle-elasticsearch',
  presetOptions: { node: 'http://localhost:9200' },
}

Option	Default	Description
`node`	–	Required. Elasticsearch URL.
`index`	`&platform.logs`	Index the entries are written to.
`esVersion`	`8`	Elasticsearch major version.
`addKuzzleInfo`	`true`	Adds `_kuzzle_info` to each entry, like the documents written by Kuzzle.

Entries are formatted with the Elastic Common Schema (ECS).