# winston-loki

> A Winston transport for Grafana Loki

Latest version **6.1.7** (published 2026-08-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install winston-loki
pnpm add winston-loki
yarn add winston-loki
bun add winston-loki
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 6.1.7 |
| Published | 2026-08-11 |
| First published | 2019-01-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 227.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 170 |
| Author | Jani Anttonen |
| Maintainers | janianttonen |
| Keywords | winston, winston-transport, transport, loki, grafana, logging, plugin, SRE, site reliability engineering, grafana loki |

## Links

- npm: https://www.npmjs.com/package/winston-loki
- Repository: https://github.com/JaniAnttonen/winston-loki
- Homepage: https://github.com/JaniAnttonen/winston-loki#readme
- Issues: https://github.com/JaniAnttonen/winston-loki/issues
- npm.io page: https://npm.io/package/winston-loki

## Dependencies (5)

- [btoa](https://npm.io/package/btoa.md) ^1.2.1
- [protobufjs](https://npm.io/package/protobufjs.md) ^7.2.4
- [url-polyfill](https://npm.io/package/url-polyfill.md) ^1.1.12
- [async-exit-hook](https://npm.io/package/async-exit-hook.md) 2.0.1
- [winston-transport](https://npm.io/package/winston-transport.md) ^4.3.0

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 6.1.7 (latest) — 2026-08-11
- 6.0.7-rc2 (next) — 2023-04-06
- 6.1.6 — 2026-07-27
- 6.1.5 — 2026-07-15
- 6.1.4 — 2026-02-12
- 6.1.3 — 2024-10-15
- 6.1.2 — 2024-04-24
- 6.1.1 — 2024-04-15
- 6.1.0 — 2024-04-09
- 6.0.8 — 2023-10-18
- 6.0.7 — 2023-08-01
- 6.0.7-rc1 — 2022-11-17
- 6.0.6 — 2022-08-22
- 6.0.5 — 2022-02-11
- 6.0.4 — 2022-02-01
- … 42 more at https://npm.io/package/winston-loki/versions

## README

# winston-loki

[![npm version](https://badge.fury.io/js/winston-loki.svg)](https://badge.fury.io/js/winston-loki)
[![install size](https://packagephobia.now.sh/badge?p=winston-loki)](https://packagephobia.now.sh/result?p=winston-loki)
[![Build Status](https://travis-ci.com/JaniAnttonen/winston-loki.svg?branch=master)](https://travis-ci.com/JaniAnttonen/winston-loki)
[![Coverage Status](https://coveralls.io/repos/github/JaniAnttonen/winston-loki/badge.svg?branch=master)](https://coveralls.io/github/JaniAnttonen/winston-loki?branch=master)
[![Maintainability](https://api.codeclimate.com/v1/badges/17a55cce14d581c308bc/maintainability)](https://codeclimate.com/github/JaniAnttonen/winston-loki/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](./examples/)
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.

### 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(). Warning: Disabling `replaceTimestamp` may result in logs failing to upload due to recent changes in the upstream Loki project. It is recommended to leave this option enabled unless you have a specific reason to disable it. | true                   | true          |
| `labels`           | custom labels, key-value pairs                            | { module: 'http' }     | undefined     |
| `format`           | winston format (https://github.com/winstonjs/winston#formats) | simple()           | undefined     |
| `gracefulShutdown` | Enable/disable graceful shutdown (wait for any unsent batches) | false             | true          |
| `timeout`          | timeout for requests to grafana loki in ms                | 30000                  | undefined     | 
| `basicAuth`        | basic authentication credentials to access Loki over HTTP | username:password      | undefined     | 
| `onConnectionError`| Loki error connection handler                        | (err) => console.error(err) | undefined     | 
| `useWinstonMetaAsLabels` | Use Winston's "meta" (such as defaultMeta values) as Loki labels | true        | false         |
| `ignoredMeta`      | When useWinstonMetaAsLabels is enabled, a list of meta values to ignore | ["error_description"]  | undefined |

### Example (Running Loki Locally)
With default formatting:
```js
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:
```js
logger.debug({ message: 'test', labels: { 'key': 'value' } })
```

TODO: Add custom formatting example

### Example (Grafana Cloud Loki)

**Important**: this snippet requires the following values, here are the instructions for how you can find them.

* `LOKI_HOST`: find this in your Grafana Cloud instance by checking Connections > Data Sources, find the right Loki connection, and copy its URL, which may look like `https://logs-prod-006.grafana.net`
* `USER_ID`: the user number in the same data source definition, it will be a multi-digit number like `372040`
* `GRAFANA_CLOUD_TOKEN`: In Grafana Cloud, search for Cloud Access Policies. Create a new Cloud Access Policy, ensuring its scopes include `logs:write`.  Generate a token for this cloud access policy, and use this value here.

```js
const { createLogger, transports } = require("winston");
const LokiTransport = require("winston-loki");
const options = {
  ...,
  transports: [
    new LokiTransport({
        host: 'LOKI_HOST',
        labels: { app: 'my-app' },
        json: true,
        basicAuth: 'USER_ID:GRAFANA_CLOUD_TOKEN',
        format: winston.format.json(),
        replaceTimestamp: true,
        onConnectionError: (err) => console.error(err),
    })
  ]
  ...
};
const logger = createLogger(options);
logger.debug({ message: 'test', labels: { 'key': 'value' } })
```


## 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://grafana.com/docs/loki/latest/api/ for documentation about the available endpoints, data formats etc.

### Example
```sh
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
```sh
npm test
```

Write new ones under `/test`

---
_Source: https://npm.io/package/winston-loki · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._