# winston-logstash

> A Logstash transport for winston

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

## Install

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

## 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 | 2.1.1 |
| Published | 2026-08-08 |
| First published | 2013-05-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=18 |
| Dependencies | 1 |
| Unpacked size | 34.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 129 |
| Author | Jaakko Suutarla |
| Maintainers | jaakkos |
| Keywords | logging, sysadmin, tools |

## Links

- npm: https://www.npmjs.com/package/winston-logstash
- Repository: https://github.com/jaakkos/winston-logstash
- Issues: https://github.com/jaakkos/winston-logstash/issues
- npm.io page: https://npm.io/package/winston-logstash

## Dependencies (1)

- [winston-transport](https://npm.io/package/winston-transport.md) ^4.9.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

- 2.1.1 (latest) — 2026-08-08
- 2.1.0 — 2026-07-23
- 2.0.5 — 2026-05-12
- 2.0.4 — 2026-03-26
- 2.0.3 — 2026-01-24
- 2.0.2 — 2026-01-24
- 2.0.1 — 2026-01-24
- 2.0.0 — 2026-01-24
- 1.2.1 — 2023-07-30
- 1.2.0 — 2023-03-27
- 1.1.0 — 2022-12-03
- 1.0.2 — 2022-11-09
- 1.0.1 — 2022-11-07
- 1.0.0 — 2022-11-05
- 0.4.0 — 2017-11-24
- … 14 more at https://npm.io/package/winston-logstash/versions

## README

# winston-logstash

[![Build Status](https://github.com/jaakkos/winston-logstash/actions/workflows/build-test.yaml/badge.svg)](https://github.com/jaakkos/winston-logstash/actions/workflows/build-test.yaml)
[![Integration tests with Logstash instance](https://github.com/jaakkos/winston-logstash/actions/workflows/integration-test.yaml/badge.svg?branch=main)](https://github.com/jaakkos/winston-logstash/actions/workflows/integration-test.yaml)
[![npm version](https://img.shields.io/npm/v/winston-logstash.svg)](https://www.npmjs.com/package/winston-logstash)
[![node](https://img.shields.io/node/v/winston-logstash.svg)](https://www.npmjs.com/package/winston-logstash)
[![Test Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen.svg)](https://github.com/jaakkos/winston-logstash)

A [Logstash TCP][0] transport for [winston][1].

**Requirements:** Node.js >= 18

## Usage

### Winston 2.x

``` js
// See test cases from test-bench/winston-2x/test/smoke_test.js
const winston = require("winston");
const transports = require("winston-logstash");

const logger = new winston.Logger({
  transports: [
    new transports.Logstash({
      port: 28777,
      node_name: "my node name",
      host: "127.0.0.1",
    }),
  ],
});

logger.info("Hello world!");
```

### Winston 3.x

``` js
// See test cases from test-bench/winston-3x/test/smoke_test.js
const winston = require("winston");
const LogstashTransport = require("winston-logstash/lib/winston-logstash-latest");

const logger = winston.createLogger({
  transports: [
    new LogstashTransport({
      port: 28777,
      node_name: "my node name",
      host: "127.0.0.1",
    }),
  ],
});

logger.info("Hello world!");
```

### Logstash config

``` ruby
# See example from test-bench/logstash/logstash/pipeline/default.conf
input {
  # Sample input over TCP
  tcp { port => 28777 type=>"sample" }
}
output {
  stdout { debug => true }
}

filter {
  json {
    source => "message"
  }
}
```

## FAQ

### Error handling with the transport

While this is a relatively complex transport with an internal state and IO, I think the current solution is the yet best approach to network failure. Transport is transparent about the errors and lets the user decide what to do in the case of an error. Suppose the developer chooses not to address them, it fallback to a safe default, an exception that stops the process. I think this way; it's simple but not always easy.

You can check the test case from `test-bench` folder where is the test case per Winston's version. The simplest ways to write the error logic would be:

#### Winston 2.x

For Winston 2.x you have to add the error listener to the transport.

``` js
const logstashTransport =  new LogstashTransport({...});

logstashTransport.on('error', (error) => {
  // Make the decission in here
  throw new Error('Stop the press, logging not working');
});

```

#### Winston 3.x

For Winston 3.x you have to add the error listener to the logger. Remember that there might be also other errors which are not originated from LogstashTransport.

``` js
const logger = winston.createLogger({
      transports: [
        new LogstashTransport({
              ...
               max_connect_retries: -1
              ...
              })]});

logger.on('error', (error) => {
  // Make the decission in here
  throw new Error('Stop the press, logging not working');
});
```

### What configuration options are available?

See documentation from [docs/configuration](docs/configuration.md)

### How to keep the connection open while Logstash is restarting?

It's possible to set max_connect_retries to -1 (infinite) so the client keeps trying to connect to the Logstash. So when Logstash is restarted the retry logic will reconnect when it comes back online.

``` js
    const logger = winston.createLogger({
      transports: [
        new LogstashTransport({
              ...
               max_connect_retries: -1
              ...
              })]});
```

## Run Tests

```shell
  npm test
```

## Run integration tests with Logstash

```shell
# Start Logstash
cd test-bench/logstash
docker compose up -d

# Run Winston 2.x tests
cd ../winston-2x
npm install && npm test

# Run Winston 3.x tests
cd ../winston-3x
npm install && npm test

# Stop Logstash
cd ../logstash
docker compose down
```

## Inspiration

[winston-loggly][2]

## Author: [Jaakko Suutarla](https://github.com/jaakkos)

## License: MIT

See LICENSE for the full license text.

[0]: http://logstash.net/
[1]: https://github.com/flatiron/winston
[2]: https://github.com/indexzero/winston-loggly

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