TCP and UDP syslog client RFC 5424 & RFC 3164
npm install @phillipivan/syslog-client
npm install syslog-client
`
It is loaded using the require() function:
`js
var syslog = require("syslog-client");
`
TCP or UDP clients can then be created to log messages to remote hosts.
`js
var client = syslog.createClient("127.0.0.1");
client.log("example message");
`
[1]: https://www.ietf.org/rfc/rfc3164.txt
[2]: https://tools.ietf.org/html/rfc5424
[3]: https://npmjs.org
Constants
The following sections describe constants exported and used by this module.
syslog.Transport
This object contains constants for all valid values for the transport
attribute passed to the options argument for the createClient() function.
The following constants are defined in this object:
* Tcp
* Udp
* Tls
* Unix
syslog.Facility
This object contains constants for all valid values for the facility
attribute passed to the options argument for the log() method on the
Client class. The following constants are defined in this object:
* Kernel - 0
* User - 1
* Mail - 2
* System - 3
* Daemon - 3
* Auth - 4
* Syslog - 5
* Lpr - 6
* News - 7
* Uucp - 8
* Cron - 9
* Authpriv - 10
* Ftp - 11
* Audit - 13
* Alert - 14
* Local0 - 16
* Local1 - 17
* Local2 - 18
* Local3 - 19
* Local4 - 20
* Local5 - 21
* Local6 - 22
* Local7 - 23
syslog.Severity
This object contains constants for all valid values for the severity
attribute passed to the options argument for the log() method on the
Client class. The following constants are defined in this object:
* Emergency - 0
* Alert - 1
* Critical - 2
* Error - 3
* Warning - 4
* Notice - 5
* Informational - 6
* Debug - 7
Using This Module
All messages are sent using an instance of the Client class. This
module exports the createClient() function which is used to create
instances of the Client class.
syslog.createClient([target], [options])
The createClient() function instantiates and returns an instance of the
Client class:
`js
// Default options
var options = {
syslogHostname: os.hostname(),
transport: syslog.Transport.Udp,
port: 514
};
var client = syslog.createClient("127.0.0.1", options);
`
The optional target parameter defaults to 127.0.0.1. The optional
options parameter is an object, and can contain the following items:
* port - TCP or UDP port to send messages to, defaults to 514
* syslogHostname - Value to place into the HOSTNAME part of the HEADER
part of each message sent, defaults to os.hostname()
* tcpTimeout - Number of milliseconds to wait for a connection attempt to
the specified Syslog target, and the number of milliseconds to wait for
TCP acknowledgements when sending messages using the TCP transport,
defaults to 10000 (i.e. 10 seconds)
* transport - Specify the transport to use, can be either
syslog.Transport.Udp or syslog.Transport.Tcp or syslog.Transport.Unix, defaults to
syslog.Transport.Udp
* facility - set default for client.log(); default is syslog.Facility.Local0.
* severity - set default for client.log(); default is syslog.Severity.Informational.
* rfc3164 - set to false to use RFC 5424
syslog header format; default is true for the older RFC 3164
format.
* appName - set the APP-NAME field when using rfc5424; default uses process.title
* dateFormatter - change the default date formatter when using rfc5424; interface: function(date) { return string; }; defaults to function(date) { return date.toISOString(); }
* udpBindAddress - set to bind an UDP socket only on a specific address; default node behavior is to bind to 0.0.0.0 (all network adresses of the machine)
For Unix sockets (TCP only), set target to the path of Unix socket.
client.on("close", callback)
The close event is emitted by the client when the clients underlying TCP or
UDP socket is closed.
No arguments are passed to the callback.
The following example prints a message to the console when a clients
underlying TCP or UDP socket is closed:
`js
client.on("close", function () {
console.log("socket closed");
});
`
client.on("error", callback)
The error event is emitted by the client when the clients underlying TCP or
UDP socket emits an error.
The following arguments will be passed to the callback function:
* error - An instance of the Error class, the exposed message attribute
will contain a detailed error message.
The following example prints a message to the console when an error occurs
with a clients underlying TCP or UDP socket:
`js
client.on("error", function (error) {
console.error(error);
});
`
client.close()
The close() method closes the clients underlying TCP or UDP socket. This
will result in the close event being emitted by the clients underlying TCP
or UDP socket which is passed through to the client, resulting in the client
also emitting a close event.
The following example closes a clients underlying TCP or UDP socket:
`js
client.close();
`
client.log(message, [options], [callback])
The log() method sends a Syslog message to a remote host.
The message parameter is a string containing the message to be logged.
The optional options parameter is an object, and can contain the following
items:
* facility - Either one of the constants defined in the syslog.Facility
object or the facility number to use for the message, defaults to
syslog.Facility.Local0 (see syslog.createClient())
* severity - Either one of the constants defined in the syslog.Severity
object or the severity number to use for the message, defaults to
syslog.Severity.Informational (see syslog.createClient())
* rfc3164 - set to false to use RFC 5424
syslog header format; default is true for the older RFC 3164
format.
* timestamp - Optional Javascript Date() object to back-date the message.
* msgid - Optional RFC 5424 message-id.
The callback function is called once the message has been sent to the remote
host, or an error occurred. The following arguments will be passed to the
callback function:
* error - Instance of the Error class or a sub-class, or null if no
error occurred
Each message sent to the remote host will have a newline character appended
to it, if one is not already appended. Care should be taken to ensure newline
characters are not embedded within the message passed to this method (i.e. not
appearing at the end), as this may cause some syslog relays/servers to
incorrectly parse the message.
The following example sends a message to a remote host:
`js
var options = {
facility: syslog.Facility.Daemon,
severity: syslog.Severity.Critical
};
var message "something is wrong with this daemon!";
client.log(message, options, function(error) {
if (error) {
console.error(error);
} else {
console.log("sent message successfully");
}
});
`
Example Programs
Example programs are included under the modules example directory.
Running tests and test coverage
Tests can be run with:
`
npm test
`
Install dev dependencies before running test coverage:
`
npm install --dev
npm run coverage
`
Coverage should be generated into coverage/lcov-report/index.html.
Changes
Version 1.0.0 - 31/07/2015
* Initial release
Version 1.0.1 - 31/07/2015
* Correct typo in README.md
Version 1.0.2 - 31/07/2015
* Correct typo in README.md :(
Version 1.0.3 - 01/08/2015
* Correct typo in README.md :( :(
Version 1.0.4 - 08/08/2015
* Transport error events are not propagated to an error event in the Syslog
client
Version 1.0.5 - 22/10/2015
* Redundant release
Version 1.0.6 - 22/10/2015
* Slight formatting error in the README.md file
Version 1.0.7 - 08/02/2016
* Remove debug console.dir() statement accidently left in code
Version 1.0.8 - 26/08/2016
* Variable key in _expandConstantObject() missing var declaration
Version 1.0.9 - 27/10/2016
* Added mocha test framework
* Added istanbul test coverage
* Added tests for aprox 89% coverage
* Fixed bug where transports where not being reused
* Fixed bug where some connections would not close()
* Made options in .log() optional as per existing documentation
* Make cb in .log() optional and update documentation
* Fixed bug where error event and .log callback wouldn't predictably receive error
* close event is now always fired when .close()` is called, regarless of open connection