winston-loki
    TypeScript icon, indicating that this package has built-in type declarations

    6.0.1 • Public • Published

    winston-loki

    npm version install size Build Status Coverage Status Maintainability

    A Grafana Loki transport for the nodejs logging library Winston.

    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
    timeout timeout for requests to grafana loki in ms 30000 null

    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

    Install

    npm i winston-loki

    DownloadsWeekly Downloads

    1,879

    Version

    6.0.1

    License

    MIT

    Unpacked Size

    222 kB

    Total Files

    16

    Last publish

    Collaborators

    • avatar