gelf-pro
v1.3.12
Published
The Graylog Extended Log Format for the Node.js
Downloads
64,452
Maintainers
Readme
gelf pro
gelf-pro
- Graylog2 client library for Node.js.
Sends logs to Graylog2 server in GELF (Graylog Extended Log Format) format.
Features:
- JS object marshalling
- UDP/TCP/TLS support
- Filtering, Transforming, Broadcasting.
Installation
"dependencies": {
"gelf-pro": "~1.3" // see the "releases" section
}
npm install gelf-pro
(ALL node.js versions are supported [0.x to 2x.x] :)
Library depends on: lodash#~4.17
Initialization
var log = require('gelf-pro');
Adapters
[!WARNING] To ensure consistent behavior, none of the existing adapters re-use the socket connection. Re-using socket connections can lead to resource leakage, complexity in state management, concurrency issues, security risks, and may not always provide significant performance benefits. It's often simpler and safer to establish new connections as needed rather than re-using existing ones, ensuring better resource utilization and reducing potential complications in network communication.
There are multiple (1, 2) variants available for you to borrow from and create a new adapter. See related section.
- UDP (with deflation and chunking)
- Input:
GELF UDP
- Input:
- TCP
- Input:
GELF TCP
(withNull frame delimiter
)
- Input:
- TCP via TLS(SSL)
- Input:
GELF TCP
(withNull frame delimiter
andEnable TLS
)
- Input:
[!NOTE] Within a more or less stable network (which is most likely), I would recommend using the
udp
adapter. I would also recommend it for an average to high-loaded project. For sensitive information, thetcp-tls
adapter is recommended.
Configuration
// simple
log.setConfig({adapterOptions: {host: 'my.glog-server.net'}});
// advanced
log.setConfig({
fields: {facility: "example", owner: "Tom (a cat)"}, // optional; default fields for all messages
filter: [], // optional; filters to discard a message
transform: [], // optional; transformers for a message
broadcast: [], // optional; listeners of a message
levels: {}, // optional; default: see the levels section below
aliases: {}, // optional; default: see the aliases section below
adapterName: 'udp', // optional; currently supported "udp", "tcp" and "tcp-tls"; default: udp
adapterOptions: { // this object is passed to the adapter.connect() method
// common
host: '127.0.0.1', // optional; default: 127.0.0.1
port: 12201, // optional; default: 12201
// ... and so on
// tcp adapter example
family: 4, // tcp only; optional; version of IP stack; default: 4
timeout: 1000, // tcp only; optional; default: 10000 (10 sec)
// udp adapter example
protocol: 'udp4', // udp only; optional; udp adapter: udp4, udp6; default: udp4
// tcp-tls adapter example
key: fs.readFileSync('client-key.pem'), // tcp-tls only; optional; only if using the client certificate authentication
cert: fs.readFileSync('client-cert.pem'), // tcp-tls only; optional; only if using the client certificate authentication
ca: [fs.readFileSync('server-cert.pem')] // tcp-tls only; optional; only for the self-signed certificate
}
});
log.setConfig
merges the data. Therefore, you can call it multiple times.
Basic functionality
var extra = {tom: 'cat', jerry: 'mouse', others: {spike: 1, tyke: 1}};
log.info("Hello world", extra, function (err, bytesSent) {});
log.info("Hello world", function (err, bytesSent) {});
log.info("Hello world", extra);
log.info("Hello world");
log.error('Oooops.', new Error('An error message'));
// ^-- extra becomes: {short_message: 'Oooops.', _error_message: 'An error message', _error_stack: Error's stack}
log.error(new Error('An error message'));
// ^-- extra becomes: {short_message: 'An error message', full_message: Error's stack}
log.message(new Error('An error message'), 3); // same as previous
Extra
In case extra
is a plain object,
the library converts it to a readable format. Other values are converted to string.
The acceptable format of a key is: ^[\w-]$
log.info(
'a new msg goes here',
{me: {fname: 'k', lname: 'k', bdate: new Date(2000, 01, 01)}}
);
// ^-- extra becomes: {_me_fname: 'k', _me_lname: 'k', _me_bdate: 'Tue Feb 01 2000 00:00:00 GMT+0100 (CET)'}
Filtering
Sometimes we have to discard a message which is not suitable for the current environment. It is NOT
possible to modify the data.
log.setConfig({
filter: [
function (message) { // rejects a "debug" message
return (message.level < 7);
}
]
});
Transforming
transforming
happens after filtering
. It is possible to modify the data.
log.setConfig({
transform: [
function (message) { // unwind an error
if (_.isError(message.error)) {
message.error = {message: message.error.message, stack: message.error.stack};
}
return message;
}
]
});
Broadcasting
broadcasting
happens after transforming
. It is NOT
possible to modify the data.
log.setConfig({
broadcast: [
function (message) { // broadcasting to console
console[message.level > 3 ? 'log' : 'error'](message.short_message, message);
}
]
});
Levels (1, 2, 3)
Default:{emergency: 0, alert: 1, critical: 2, error: 3, warning: 4, notice: 5, info: 6, debug: 7}
Example: log.emergency(...)
, log.critical(...)
, etc.
Custom example: {alert: 0, notice: 1, ...}
Third party adapters
You can force using custom adapter by setting the adapter
right after initialisation. The signature might be found here.
var log = require('gelf-pro');
var myFancyAdapter = require('...');
log.adapter = myFancyAdapter;
// (!) adapterName and adapterOptions will be ignored
Aliases
Default: {log: 'debug', warn: 'warning'}
Example: log.log(...) -> log.debug(...)
, log.warn(...) -> log.warning(...)
, etc.
Custom example: {red: 'alert', yellow: 'notice', ...}
Tests
Cli
npm install
npm test
Docker
[sudo] docker build --no-cache -t node-gelf-pro .
[sudo] docker run -ti --rm -v "${PWD}:/opt/app" -w "/opt/app" node-gelf-pro