{"id":15692,"library":"logstash-client","title":"Logstash Client","description":"logstash-client is a general-purpose Node.js library for sending logs to Logstash instances. It provides support for UDP, TCP, and in-memory transports, designed to be independent of specific logging frameworks like Winston or Bunyan. The package's current stable version is 1.1.1, which was published in 2016. Due to its age and lack of updates, the release cadence is inactive, and the library is no longer under active development. Key differentiators at the time of its development included its transport flexibility and independence from specific logger implementations, allowing it to integrate with various Node.js applications. However, this also means it predates modern JavaScript features and best practices.","status":"abandoned","version":"1.1.1","language":"javascript","source_language":"en","source_url":"git://github.com/purposeindustries/node-logstash-client","tags":["javascript","logstash","logging","amqp"],"install":[{"cmd":"npm install logstash-client","lang":"bash","label":"npm"},{"cmd":"yarn add logstash-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add logstash-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used by the TCP transport for handling automatic reconnection to the Logstash server.","package":"reconnect-net","optional":false},{"reason":"Utility for merging objects, likely used for configuration or message processing.","package":"lodash.merge","optional":false}],"imports":[{"note":"This package is CommonJS-only and does not support ES modules. Use `require()` for importing.","wrong":"import Logstash from 'logstash-client'; // This package is CommonJS-only\nimport { Logstash } from 'logstash-client';","symbol":"Logstash","correct":"const Logstash = require('logstash-client');"}],"quickstart":{"code":"const Logstash = require('logstash-client');\n\n// Configure a UDP client to send messages to Logstash\nconst logstashUdp = new Logstash({\n  type: 'udp',\n  host: 'localhost', // Replace with your Logstash host\n  port: 13333 // Replace with your Logstash UDP input port\n});\n\n// Send a basic log message\nlogstashUdp.send({\n  '@timestamp': new Date().toISOString(),\n  'message': 'Hello from logstash-client UDP!',\n  'level': 'info',\n  'service': 'my-node-app'\n}, (err) => {\n  if (err) {\n    console.error('Error sending UDP message:', err);\n  } else {\n    console.log('UDP message sent successfully.');\n  }\n});\n\n// Configure a TCP client (requires a Logstash TCP input, e.g., on port 8099)\nconst logstashTcp = new Logstash({\n  type: 'tcp',\n  host: 'localhost', // Replace with your Logstash host\n  port: 8099, // Replace with your Logstash TCP input port\n  format: (message) => {\n    // Custom formatter: add a timestamp and filter sensitive data\n    message.formattedAt = new Date().toISOString();\n    message.apiKey = '[FILTERED]';\n    return JSON.stringify(message) + '\\n'; // Ensure newline for TCP streams\n  }\n});\n\nlogstashTcp.send({\n  'event': 'user_login',\n  'userId': 123,\n  'apiKey': process.env.API_KEY ?? 'secret_key_if_not_set',\n  'status': 'success'\n}, (err) => {\n  if (err) {\n    console.error('Error sending TCP message:', err);\n  } else {\n    console.log('TCP message sent successfully.');\n  }\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.1.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `require()` in an ECMAScript module (.mjs file or `type: module` in package.json).","error":"ReferenceError: require is not defined in ES module scope"},{"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.","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.","error":"Error: connect ECONNREFUSED <host>:<port>"},{"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 {}`.","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.","error":"Messages not appearing in Logstash when using TCP, or appearing concatenated/malformed."}],"ecosystem":"npm"}