Syslog Client for Node.js

Common errors

• Error: connect ECONNREFUSED

  cause The syslog server at the specified target IP and port is not running or is blocking connections.
  fix Ensure the syslog server (e.g., rsyslog, syslog-ng) is running on the target machine and configured to listen on the specified port and protocol. Check firewall rules on both the client and server. For TCP, ensure the server is configured to accept TCP connections.

• TypeError: syslog.createClient is not a function

  cause This error typically occurs when attempting to use ESM `import { createClient } from 'syslog-client'` with a CommonJS-only module, or incorrectly destructuring the `require` output.
  fix Use the CommonJS `require` syntax as demonstrated in the documentation: `const syslog = require('syslog-client');` and then access `syslog.createClient()`. If using TypeScript with `esModuleInterop` enabled, `import syslog from 'syslog-client';` might work, but direct named imports are generally not supported for pure CJS modules.

• Message not appearing in syslog server logs.

  cause This can be due to incorrect IP address, port, transport protocol, or facility/severity filtering on the syslog server.
  fix Verify the `target` IP address and `port` in `createClient`. Confirm the `transport` (UDP/TCP) matches the server's configuration. Check the syslog server's configuration (`/etc/rsyslog.conf` or `/etc/syslog-ng/syslog-ng.conf`) for any filtering rules that might be discarding messages based on facility, severity, program name, or source host. Temporarily increase verbosity on the server or use a network packet analyzer like Wireshark/tcpdump.

Warnings

• gotcha By default, the client sends messages formatted according to RFC 3164. If you require the newer RFC 5424 format, you must explicitly set the `rfc3164` option to `false` in the `createClient` options object.
  Fix: When creating the client, pass `{ rfc3164: false }` in the options object: `syslog.createClient('127.0.0.1', { rfc3164: false });`
• gotcha The package defaults to using UDP transport on port 514. If your syslog server expects TCP or a different port, these must be explicitly configured in the client options.
  Fix: Specify the `transport` and `port` options: `syslog.createClient('127.0.0.1', { transport: syslog.Transport.Tcp, port: 6514 });`
• gotcha The `tcpTimeout` option, defaulting to 10 seconds, controls both connection attempts and TCP acknowledgement waits. This default might be too long for highly responsive systems or too short for unreliable network conditions.
  Fix: Adjust `tcpTimeout` in the client options to suit your network environment: `syslog.createClient('127.0.0.1', { transport: syslog.Transport.Tcp, tcpTimeout: 5000 });`
• gotcha This package has not been updated in approximately 9 years. While it may still function for basic syslog needs, it might lack modern features, performance optimizations, or security patches found in more actively maintained alternatives.
  Fix: For new projects or critical applications, consider evaluating more modern and actively maintained syslog client libraries for Node.js, such as `@resqclub/syslog-client` or `@n8n/syslog-client`, or the `winston-syslog` transport if using Winston.

Install

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

Imports

• syslog
  wrong:

  import syslog from 'syslog-client';

  correct:

  const syslog = require('syslog-client');

  This package is primarily a CommonJS module. Direct ESM import might not work as expected and would require a bundler or specific Node.js loader configuration.
• createClient
  wrong:

  import { createClient } from 'syslog-client';

  correct:

  const client = syslog.createClient('127.0.0.1');

  The `createClient` function is a property of the main `syslog` object exported via CommonJS `require`.
• Transport, Facility, Severity
  wrong:

  import { Transport } from 'syslog-client';

  correct:

  const transport = syslog.Transport.Udp; // Similarly for Facility and Severity

  Constants like `Transport`, `Facility`, and `Severity` are nested objects under the main `syslog` export and should be accessed as `syslog.Transport.Udp`.

Quickstart

This quickstart demonstrates how to initialize a syslog client, send basic log messages, and specify custom options like severity and facility. It highlights the use of `createClient` and the `log` method with callbacks for error handling.

const os = require('os');
const syslog = require('syslog-client');

const options = {
  syslogHostname: os.hostname(),
  transport: syslog.Transport.Udp,
  port: 514,
  facility: syslog.Facility.Local0,
  severity: syslog.Severity.Informational,
  rfc3164: true // Defaults to RFC 3164
};

// Create a syslog client targeting localhost via UDP
const client = syslog.createClient('127.0.0.1', options);

client.log('This is an example syslog message from my Node.js application.', {}, (error) => {
  if (error) {
    console.error('Failed to send syslog message:', error);
  } else {
    console.log('Syslog message sent successfully.');
  }
  client.close(); // Close the client connection if TCP is used or to clean up resources
});

// Example with custom severity
client.log('An important warning occurred!', {
  severity: syslog.Severity.Warning,
  facility: syslog.Facility.User
}, (error) => {
  if (error) console.error('Warning message failed:', error);
  else console.log('Warning message sent.');
});