winston-loki

A Grafana Loki transport for the nodejs logging library Winston.

Releases

Latest

The latest version, which might not be fully tested, but should be compatible with the latest Grafana Loki, is 6.0.0-rc.3. It is recommended to use this one if you're using the latest version of Loki.

Stable

A stable, /fully/ tested version is 5.1.2.

Usage

This Winston transport is used similarly to other Winston transports. Require winston and define a new LokiTransport() inside its options when creating it.

Examples

Several usage examples with a test configuration for Grafana+Loki+Promtail reside under examples/. If you want the simplest possible configuration, that's probably the place to check out. By defining json: true and giving winston-loki the correct host address for Loki is enough for most.

Options

LokiTransport() takes a Javascript object as an input. These are the options that are available, required in bold:

| Parameter | Description | Example | Default | | ------------------ | --------------------------------------------------------- | -----------------------| ------------- | | host | URL for Grafana Loki | http://127.0.0.1:3100 | null | | interval | The interval at which batched logs are sent in seconds | 30 | 5 | | json | Use JSON instead of Protobuf for transport | true | false | | batching | If batching is not used, the logs are sent as they come | true | true | | clearOnError | Discard any logs that result in an error during transport | true | false | | replaceTimestamp | Replace any log timestamps with Date.now() | true | false | | labels | custom labels, key-value pairs | { module: 'http' } | null | | format | winston format (https://github.com/winstonjs/winston#formats) | simple() | null | | gracefulShutdown | Enable/disable graceful shutdown (wait for any unsent batches) | false | true |

Example

With default formatting:

const { createLogger, transports } = require("winston");
const LokiTransport = require("winston-loki");
const options = {
  ...,
  transports: [
    new LokiTransport({
      host: "http://127.0.0.1:3100"
    })
  ]
  ...
};
const logger = createLogger(options);

You can set custom labels in every log as well like this:

logger.debug({ message: 'test', labels: { 'key': 'value' } })

TODO: Add custom formatting example

Developing

Requirements

Running a local Loki for testing is probably required, and the easiest way to do that is to follow this guide: https://github.com/grafana/loki/tree/master/production#run-locally-using-docker. After that, Grafana Loki instance is available at http://localhost:3100, with a Grafana instance running at http://localhost:3000. Username admin, password admin. Add the Loki source with the URL http://loki:3100, and the explorer should work.

Refer to https://github.com/grafana/loki/blob/master/docs/api.md for documentation about the available endpoints, data formats etc.

Example

npm install
npm link
cd ~/your_project
npm link winston-loki
npm install

And you should have a working, requirable winston-loki package under your project's node_modules. After the link has been established, any changes to winston-loki should show on rerun of the software that uses it.

Run tests

npm test

Write new ones under /test