Logstash Client

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` in an ECMAScript module (.mjs file or `type: module` in package.json).
  fix This package is CommonJS-only. Convert your project to CommonJS, or use a modern Logstash client that supports ES modules. If you must use this package in an ESM context, consider a wrapper function or a build step like Webpack/Rollup that can handle CJS modules.

• Error: connect ECONNREFUSED <host>:<port>

  cause The client could not establish a connection to the Logstash server. This usually means Logstash is not running, is not listening on the specified host/port, or a firewall is blocking the connection.
  fix Verify that your Logstash instance is running and has an input configured for the specified type (UDP/TCP) on the correct host and port. Check firewall rules between your Node.js application and the Logstash server.

• Messages not appearing in Logstash when using TCP, or appearing concatenated/malformed.

  cause Before version 1.0.2, the TCP transport did not automatically add a newline, which is crucial for Logstash's `json_lines` codec to correctly parse individual JSON events. Custom formatters might also omit the newline.
  fix Ensure you are using `logstash-client` version 1.0.2 or newer. If you provide a custom `format` function, ensure it appends a newline character (`\n`) after stringifying your JSON message (e.g., `return JSON.stringify(message) + '\n';`). Confirm your Logstash input configuration uses `codec => json_lines {}`.

Warnings

• breaking Version 1.0.2 introduced a fix to add a newline character to TCP transport's `socket.write()` call. If you were relying on concatenated messages or custom handling of JSON streams without explicit newlines in previous versions, this change will alter the message framing.
  Fix: Ensure your Logstash TCP input codec is configured to handle newline-delimited JSON (e.g., `json_lines {}`). If you have a custom `format` function, remove any manually added newlines to avoid double newlines, or adjust your Logstash configuration accordingly.
• gotcha This package is abandoned and has not been updated since 2016. It does not support modern JavaScript features like ES modules and may have compatibility issues with newer Node.js versions or recent Logstash releases. It also lacks security updates.
  Fix: It is highly recommended to migrate to a modern, actively maintained Logstash client or a general-purpose logging library with Logstash transport support (e.g., Winston, Pino, Bunyan with their respective Logstash transports) for better compatibility, performance, and security.
• gotcha Messages sent via UDP transport have a maximum size limit, typically around 64KB, which is dependent on the underlying network and OS. Exceeding this limit can result in silent message truncation or loss without an error being reported by the client.
  Fix: For larger messages, use the TCP transport, which handles message streaming more robustly. If UDP must be used, ensure messages are kept small and consider implementing application-level message chunking and reassembly if necessary.
• gotcha If the Logstash server is unreachable or misconfigured, the client's `send` method, when called without a callback, will not report delivery failures. This can lead to silent message loss, especially with UDP where delivery is inherently unreliable.
  Fix: Always provide a callback function to the `send` method to handle potential errors and ensure message delivery status is monitored. Implement retry mechanisms or dead-letter queues at the application level for critical logs.

Install

• npm install logstash-client npm
• yarn add logstash-client yarn
• pnpm add logstash-client pnpm

Imports

• Logstash
  wrong:

  import Logstash from 'logstash-client'; // This package is CommonJS-only
  import { Logstash } from 'logstash-client';

  correct:

  const Logstash = require('logstash-client');

  This package is CommonJS-only and does not support ES modules. Use `require()` for importing.

Quickstart

This quickstart demonstrates setting up both UDP and TCP clients for logstash-client, sending a simple message with and without a custom formatter, and handling potential errors.

const Logstash = require('logstash-client');

// Configure a UDP client to send messages to Logstash
const logstashUdp = new Logstash({
  type: 'udp',
  host: 'localhost', // Replace with your Logstash host
  port: 13333 // Replace with your Logstash UDP input port
});

// Send a basic log message
logstashUdp.send({
  '@timestamp': new Date().toISOString(),
  'message': 'Hello from logstash-client UDP!',
  'level': 'info',
  'service': 'my-node-app'
}, (err) => {
  if (err) {
    console.error('Error sending UDP message:', err);
  } else {
    console.log('UDP message sent successfully.');
  }
});

// Configure a TCP client (requires a Logstash TCP input, e.g., on port 8099)
const logstashTcp = new Logstash({
  type: 'tcp',
  host: 'localhost', // Replace with your Logstash host
  port: 8099, // Replace with your Logstash TCP input port
  format: (message) => {
    // Custom formatter: add a timestamp and filter sensitive data
    message.formattedAt = new Date().toISOString();
    message.apiKey = '[FILTERED]';
    return JSON.stringify(message) + '\n'; // Ensure newline for TCP streams
  }
});

logstashTcp.send({
  'event': 'user_login',
  'userId': 123,
  'apiKey': process.env.API_KEY ?? 'secret_key_if_not_set',
  'status': 'success'
}, (err) => {
  if (err) {
    console.error('Error sending TCP message:', err);
  } else {
    console.log('TCP message sent successfully.');
  }
});