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 |
|
9 | A Grafana Loki transport for the nodejs logging library Winston.
|
10 |
|
11 | ## Releases
|
12 |
|
13 | ### Latest
|
14 | The 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
|
17 | A stable, /fully/ tested version is `5.1.2`. Should work with Loki versions <=1.0.0.
|
18 |
|
19 | ## Usage
|
20 | This 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/)
|
23 | Several 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
|
26 | LokiTransport() 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
|
42 | With default formatting:
|
43 | ```js
|
44 | const { createLogger, transports } = require("winston");
|
45 | const LokiTransport = require("winston-loki");
|
46 | const options = {
|
47 | ...,
|
48 | transports: [
|
49 | new LokiTransport({
|
50 | host: "http://127.0.0.1:3100"
|
51 | })
|
52 | ]
|
53 | ...
|
54 | };
|
55 | const logger = createLogger(options);
|
56 | ```
|
57 |
|
58 | You can set custom labels in every log as well like this:
|
59 | ```js
|
60 | logger.debug({ message: 'test', labels: { 'key': 'value' } })
|
61 | ```
|
62 |
|
63 | TODO: Add custom formatting example
|
64 |
|
65 | ## Developing
|
66 | ### Requirements
|
67 | 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.
|
68 |
|
69 | Refer 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
|
73 | npm install
|
74 | npm link
|
75 | cd ~/your_project
|
76 | npm link winston-loki
|
77 | npm install
|
78 | ```
|
79 | And you should have a working, requirable winston-loki package under your project's node_modules.
|
80 | After 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
|
84 | npm test
|
85 | ```
|
86 |
|
87 | Write new ones under `/test`
|
88 |
|
\ | No newline at end of file |