UNPKG

4.74 kBMarkdownView Raw
1# winston-loki
2
3[![npm version](https://badge.fury.io/js/winston-loki.svg)](https://badge.fury.io/js/winston-loki)
4[![install size](https://packagephobia.now.sh/badge?p=winston-loki)](https://packagephobia.now.sh/result?p=winston-loki)
5[![Build Status](https://travis-ci.com/JaniAnttonen/winston-loki.svg?branch=master)](https://travis-ci.com/JaniAnttonen/winston-loki)
6[![Coverage Status](https://coveralls.io/repos/github/JaniAnttonen/winston-loki/badge.svg?branch=master)](https://coveralls.io/github/JaniAnttonen/winston-loki?branch=master)
7[![Maintainability](https://api.codeclimate.com/v1/badges/17a55cce14d581c308bc/maintainability)](https://codeclimate.com/github/JaniAnttonen/winston-loki/maintainability)
8
9A Grafana Loki transport for the nodejs logging library Winston.
10
11## Releases
12
13### Latest
14The latest version, which might not be fully tested, but should be compatible with the latest Grafana Loki, is `6.0.0-rc.9`. It is recommended to use this one if you're using the latest version of Loki. _Last tested working with Loki 1.4.1_
15
16### Stable
17A stable, /fully/ tested version is `5.1.2`. Should work with Loki versions <=1.0.0.
18
19## Usage
20This Winston transport is used similarly to other Winston transports. Require winston and define a new LokiTransport() inside its options when creating it.
21
22### [Examples](./examples/)
23Several usage examples with a test configuration for Grafana+Loki+Promtail reside under [`examples/`](./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.
24
25### Options
26LokiTransport() takes a Javascript object as an input. These are the options that are available, __required in bold__:
27
28| **Parameter** | **Description** | **Example** | **Default** |
29| ------------------ | --------------------------------------------------------- | -----------------------| ------------- |
30| __`host`__ | URL for Grafana Loki | http://127.0.0.1:3100 | null |
31| `interval` | The interval at which batched logs are sent in seconds | 30 | 5 |
32| `json` | Use JSON instead of Protobuf for transport | true | false |
33| `batching` | If batching is not used, the logs are sent as they come | true | true |
34| `clearOnError` | Discard any logs that result in an error during transport | true | false |
35| `replaceTimestamp` | Replace any log timestamps with Date.now() | true | false |
36| `labels` | custom labels, key-value pairs | { module: 'http' } | null |
37| `format` | winston format (https://github.com/winstonjs/winston#formats) | simple() | null |
38| `gracefulShutdown` | Enable/disable graceful shutdown (wait for any unsent batches) | false | true |
39| `timeout` | timeout for requests to grafana loki in ms | 30000 | null |
40
41### Example
42With default formatting:
43```js
44const { createLogger, transports } = require("winston");
45const LokiTransport = require("winston-loki");
46const options = {
47 ...,
48 transports: [
49 new LokiTransport({
50 host: "http://127.0.0.1:3100"
51 })
52 ]
53 ...
54};
55const logger = createLogger(options);
56```
57
58You can set custom labels in every log as well like this:
59```js
60logger.debug({ message: 'test', labels: { 'key': 'value' } })
61```
62
63TODO: Add custom formatting example
64
65## Developing
66### Requirements
67Running 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.
68
69Refer to https://github.com/grafana/loki/blob/master/docs/api.md for documentation about the available endpoints, data formats etc.
70
71### Example
72```sh
73npm install
74npm link
75cd ~/your_project
76npm link winston-loki
77npm install
78```
79And you should have a working, requirable winston-loki package under your project's node_modules.
80After the link has been established, any changes to winston-loki should show on rerun of the software that uses it.
81
82### Run tests
83```sh
84npm test
85```
86
87Write new ones under `/test`
88
\No newline at end of file