{"id":14972055,"url":"https://github.com/janianttonen/winston-loki","last_synced_at":"2025-04-14T08:57:18.755Z","repository":{"id":33975190,"uuid":"164610557","full_name":"JaniAnttonen/winston-loki","owner":"JaniAnttonen","description":"Grafana Loki transport for the nodejs logging library Winston.","archived":false,"fork":false,"pushed_at":"2024-10-15T15:59:41.000Z","size":769,"stargazers_count":145,"open_issues_count":29,"forks_count":54,"subscribers_count":3,"default_branch":"development","last_synced_at":"2024-10-29T17:14:00.546Z","etag":null,"topics":["grafana-loki","logging","loki","winston-loki","winston-transport"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JaniAnttonen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-08T09:15:14.000Z","updated_at":"2024-10-20T11:39:57.000Z","dependencies_parsed_at":"2023-01-15T03:44:44.776Z","dependency_job_id":"3a7dea58-6d8d-4f80-ab5a-d8d2348e8919","html_url":"https://github.com/JaniAnttonen/winston-loki","commit_stats":{"total_commits":238,"total_committers":29,"mean_commits":8.206896551724139,"dds":"0.46638655462184875","last_synced_commit":"57b594d421cfd20cb755d099e062654fd16dbdd5"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaniAnttonen%2Fwinston-loki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaniAnttonen%2Fwinston-loki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaniAnttonen%2Fwinston-loki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JaniAnttonen%2Fwinston-loki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JaniAnttonen","download_url":"https://codeload.github.com/JaniAnttonen/winston-loki/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248852122,"owners_count":21171839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grafana-loki","logging","loki","winston-loki","winston-transport"],"created_at":"2024-09-24T13:46:18.307Z","updated_at":"2025-04-14T08:57:18.737Z","avatar_url":"https://github.com/JaniAnttonen.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# winston-loki\n\n[![npm version](https://badge.fury.io/js/winston-loki.svg)](https://badge.fury.io/js/winston-loki)\n[![install size](https://packagephobia.now.sh/badge?p=winston-loki)](https://packagephobia.now.sh/result?p=winston-loki)\n[![Build Status](https://travis-ci.com/JaniAnttonen/winston-loki.svg?branch=master)](https://travis-ci.com/JaniAnttonen/winston-loki)\n[![Coverage Status](https://coveralls.io/repos/github/JaniAnttonen/winston-loki/badge.svg?branch=master)](https://coveralls.io/github/JaniAnttonen/winston-loki?branch=master)\n[![Maintainability](https://api.codeclimate.com/v1/badges/17a55cce14d581c308bc/maintainability)](https://codeclimate.com/github/JaniAnttonen/winston-loki/maintainability)\n\nA Grafana Loki transport for the nodejs logging library Winston.\n\n## Usage\nThis Winston transport is used similarly to other Winston transports. Require winston and define a new LokiTransport() inside its options when creating it.\n\n### [Examples](./examples/)\nSeveral 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.\n\n### Options\nLokiTransport() takes a Javascript object as an input. These are the options that are available, __required in bold__:\n\n| **Parameter**      | **Description**                                           | **Example**            | **Default**   |\n| ------------------ | --------------------------------------------------------- | -----------------------| ------------- |\n| __`host`__         | URL for Grafana Loki                                      | http://127.0.0.1:3100  | null          |\n| `interval`         | The interval at which batched logs are sent in seconds    | 30                     | 5             |\n| `json`             | Use JSON instead of Protobuf for transport                | true                   | false         |\n| `batching`         | If batching is not used, the logs are sent as they come   | true                   | true          |\n| `clearOnError`     | Discard any logs that result in an error during transport | true                   | false         |\n| `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          |\n| `labels`           | custom labels, key-value pairs                            | { module: 'http' }     | undefined     |\n| `format`           | winston format (https://github.com/winstonjs/winston#formats) | simple()           | undefined     |\n| `gracefulShutdown` | Enable/disable graceful shutdown (wait for any unsent batches) | false             | true          |\n| `timeout`          | timeout for requests to grafana loki in ms                | 30000                  | undefined     | \n| `basicAuth`        | basic authentication credentials to access Loki over HTTP | username:password      | undefined     | \n| `onConnectionError`| Loki error connection handler                        | (err) =\u003e console.error(err) | undefined     | \n| `useWinstonMetaAsLabels` | Use Winston's \"meta\" (such as defaultMeta values) as Loki labels | true        | false         |\n| `ignoredMeta`      | When useWinstonMetaAsLabels is enabled, a list of meta values to ignore | [\"error_description\"]  | undefined |\n\n### Example (Running Loki Locally)\nWith default formatting:\n```js\nconst { createLogger, transports } = require(\"winston\");\nconst LokiTransport = require(\"winston-loki\");\nconst options = {\n  ...,\n  transports: [\n    new LokiTransport({\n      host: \"http://127.0.0.1:3100\"\n    })\n  ]\n  ...\n};\nconst logger = createLogger(options);\n```\n\nYou can set custom labels in every log as well like this:\n```js\nlogger.debug({ message: 'test', labels: { 'key': 'value' } })\n```\n\nTODO: Add custom formatting example\n\n### Example (Grafana Cloud Loki)\n\n**Important**: this snippet requires the following values, here are the instructions for how you can find them.\n\n* `LOKI_HOST`: find this in your Grafana Cloud instance by checking Connections \u003e Data Sources, find the right Loki connection, and copy its URL, which may look like `https://logs-prod-006.grafana.net`\n* `USER_ID`: the user number in the same data source definition, it will be a multi-digit number like `372040`\n* `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.\n\n```js\nconst { createLogger, transports } = require(\"winston\");\nconst LokiTransport = require(\"winston-loki\");\nconst options = {\n  ...,\n  transports: [\n    new LokiTransport({\n        host: 'LOKI_HOST',\n        labels: { app: 'my-app' },\n        json: true,\n        basicAuth: 'USER_ID:GRAFANA_CLOUD_TOKEN',\n        format: winston.format.json(),\n        replaceTimestamp: true,\n        onConnectionError: (err) =\u003e console.error(err),\n    })\n  ]\n  ...\n};\nconst logger = createLogger(options);\nlogger.debug({ message: 'test', labels: { 'key': 'value' } })\n```\n\n\n## Developing\n### Requirements\nRunning 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.\n\nRefer to https://grafana.com/docs/loki/latest/api/ for documentation about the available endpoints, data formats etc.\n\n### Example\n```sh\nnpm install\nnpm link\ncd ~/your_project\nnpm link winston-loki\nnpm install\n```\nAnd you should have a working, requirable winston-loki package under your project's node_modules.\nAfter the link has been established, any changes to winston-loki should show on rerun of the software that uses it.\n\n### Run tests\n```sh\nnpm test\n```\n\nWrite new ones under `/test`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjanianttonen%2Fwinston-loki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjanianttonen%2Fwinston-loki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjanianttonen%2Fwinston-loki/lists"}