diff --git a/@xen-orchestra/log/.USAGE.md b/@xen-orchestra/log/.USAGE.md index b10b49f74..e5ad5ed0a 100644 --- a/@xen-orchestra/log/.USAGE.md +++ b/@xen-orchestra/log/.USAGE.md @@ -1,3 +1,5 @@ +### Producers + Everywhere something should be logged: ```js @@ -25,6 +27,8 @@ log.error('could not join server', { }) ``` +### Consumer + Then, at application level, configure the logs are handled: ```js @@ -45,13 +49,6 @@ const transport = transportEmail({ configure([ { - // if filter is a string, then it is pattern - // (https://github.com/visionmedia/debug#wildcards) which is - // matched against the namespace of the logs - // - // If it's an array, it will be handled as an array of filters - // and the transport will be used if any one of them match the - // current log filter: process.env.DEBUG, transport: transportConsole(), @@ -62,6 +59,17 @@ configure([ transport, }, + { + type: 'email', + + service: 'gmail', + auth: { + user: 'jane.smith@gmail.com', + pass: 'H&NbECcpXF|pyXe#%ZEb', + }, + from: 'jane.smith@gmail.com', + to: ['jane.smith@gmail.com', 'sam.doe@yahoo.com'], + }, ]) // send all global errors (uncaught exceptions, warnings, unhandled rejections) @@ -69,6 +77,15 @@ configure([ catchGlobalErrors(createLogger('app')) ``` +A transport as expected by `configure(transport)` can be: + +- a function that will receive emitted logs; +- an object with a `type` property and options which will be used to create a transport (see next section); +- an object with a nested `transport` which will be used if one of the following conditions is fulfilled: + - `filter`: [pattern](https://github.com/visionmedia/debug#wildcards) which is matched against the log namespace (can also be an array of filters); + - `level`: the minimal level of accepted logs; +- an array of transports. + ### Transports #### Console @@ -122,5 +139,5 @@ import transportSyslog from '@xen-orchestra/log/transports/syslog' configure(transportSyslog()) // But TCP, a different host, or a different port can be used -configure(transportSyslog('tcp://syslog.company.lan')) +configure(transportSyslog({ target: 'tcp://syslog.company.lan' })) ``` diff --git a/@xen-orchestra/log/README.md b/@xen-orchestra/log/README.md index b146a5429..0f3f94489 100644 --- a/@xen-orchestra/log/README.md +++ b/@xen-orchestra/log/README.md @@ -16,6 +16,8 @@ Installation of the [npm package](https://npmjs.org/package/@xen-orchestra/log): ## Usage +### Producers + Everywhere something should be logged: ```js @@ -43,6 +45,8 @@ log.error('could not join server', { }) ``` +### Consumer + Then, at application level, configure the logs are handled: ```js @@ -63,13 +67,6 @@ const transport = transportEmail({ configure([ { - // if filter is a string, then it is pattern - // (https://github.com/visionmedia/debug#wildcards) which is - // matched against the namespace of the logs - // - // If it's an array, it will be handled as an array of filters - // and the transport will be used if any one of them match the - // current log filter: process.env.DEBUG, transport: transportConsole(), @@ -80,6 +77,17 @@ configure([ transport, }, + { + type: 'email', + + service: 'gmail', + auth: { + user: 'jane.smith@gmail.com', + pass: 'H&NbECcpXF|pyXe#%ZEb', + }, + from: 'jane.smith@gmail.com', + to: ['jane.smith@gmail.com', 'sam.doe@yahoo.com'], + }, ]) // send all global errors (uncaught exceptions, warnings, unhandled rejections) @@ -87,6 +95,15 @@ configure([ catchGlobalErrors(createLogger('app')) ``` +A transport as expected by `configure(transport)` can be: + +- a function that will receive emitted logs; +- an object with a `type` property and options which will be used to create a transport (see next section); +- an object with a nested `transport` which will be used if one of the following conditions is fulfilled: + - `filter`: [pattern](https://github.com/visionmedia/debug#wildcards) which is matched against the log namespace (can also be an array of filters); + - `level`: the minimal level of accepted logs; +- an array of transports. + ### Transports #### Console @@ -140,7 +157,7 @@ import transportSyslog from '@xen-orchestra/log/transports/syslog' configure(transportSyslog()) // But TCP, a different host, or a different port can be used -configure(transportSyslog('tcp://syslog.company.lan')) +configure(transportSyslog({ target: 'tcp://syslog.company.lan' })) ``` ## Contributions diff --git a/@xen-orchestra/log/configure.js b/@xen-orchestra/log/configure.js index 8e6655f4a..631fc681a 100644 --- a/@xen-orchestra/log/configure.js +++ b/@xen-orchestra/log/configure.js @@ -57,6 +57,20 @@ const createTransport = config => { } } + const { type } = config + if (type !== undefined) { + if (typeof type !== 'string') { + throw new TypeError('transport type property must be a string') + } + + if (type.includes('/')) { + throw new TypeError('invalid transport type') + } + + const { ...opts } = config + return require(`./transports/${type}.js`)(opts) + } + const level = resolve(config.level) const filter = compileFilter([config.filter, level === undefined ? undefined : log => log.level >= level]) @@ -73,6 +87,7 @@ const createTransport = config => { return transport } +exports.createTransport = createTransport const symbol = typeof Symbol !== 'undefined' ? Symbol.for('@xen-orchestra/log') : '@@@xen-orchestra/log' diff --git a/@xen-orchestra/log/transports/syslog.js b/@xen-orchestra/log/transports/syslog.js index 3253f85a3..7e973efb2 100644 --- a/@xen-orchestra/log/transports/syslog.js +++ b/@xen-orchestra/log/transports/syslog.js @@ -20,6 +20,10 @@ const LEVEL_TO_SEVERITY = { const facility = Facility.User function createTransport(target) { + if (typeof target === 'object') { + target = target.target + } + const opts = {} if (target !== undefined) { if (target.startsWith('tcp://')) { diff --git a/CHANGELOG.unreleased.md b/CHANGELOG.unreleased.md index 84491fd40..9667ccacd 100644 --- a/CHANGELOG.unreleased.md +++ b/CHANGELOG.unreleased.md @@ -28,6 +28,7 @@ - @vates/read-chunk patch +- @xen-orchestra/log minor - xo-remote-parser patch - xo-server-transport-nagios patch - xo-web patch