175 lines
5.4 KiB
Markdown
175 lines
5.4 KiB
Markdown
Jibo Log - Centralized logging facility
|
|
=======================================
|
|
|
|
A module to centralize and control (and log to syslog or files) all
|
|
logging messages. Use this everywhere instead of `console.log` and
|
|
friends.
|
|
|
|
To use:
|
|
|
|
```js
|
|
const {Log} = require('jibo-log');
|
|
const log = new Log('my-namespace');
|
|
log.debug('this is a debug');
|
|
log.info('this is an info');
|
|
log.warn('this is a warning');
|
|
log.error('this is an error');
|
|
```
|
|
|
|
Use `log.debug`, `log.info`, `log.warn`, `log.error`, instead of
|
|
`console.log` and friends.
|
|
|
|
`log.log` is also available, but it's just an alias for log.debug and
|
|
is there mainly for compatibility with the console object.
|
|
|
|
You specify a string to act as the name space of your log messages in
|
|
the `new Log()` constructor call. The name space will appear in front
|
|
of all your log messages. Each name space can be configured to show or
|
|
discard messages above/below a certain level, and separately for each
|
|
output channel (i.e. console, syslog, or file). `jibo-log` creates a
|
|
hierarchy of namespaces, separated by slashes, and a lower-level namespace
|
|
inherits the configuration of its closest ancestor, and may override that
|
|
configuration.
|
|
|
|
The level order is `debug` < `info` < `warn` < `error`. By default
|
|
`debug` messages are not printed to the syslog or console, but `info` and
|
|
above are.
|
|
|
|
Syslog messages
|
|
---------------
|
|
|
|
By default, syslog messages are enabled at the `info` level. However, note
|
|
that they will only truly be turned on if and only if the current
|
|
process's platform is `linux` and architecture is `arm`.
|
|
|
|
|
|
Error logging helper
|
|
--------------------
|
|
|
|
`log.iferr(err, [message])`
|
|
|
|
A common JavaScript (and especially Node.js) convention is to indicate
|
|
an error condition as the first argument in a callback (usually named
|
|
`err` by convention). Frequently you want to log that such errors
|
|
happened, but many times it doesn't affect your program flow because
|
|
you still need to call some callback that you were given and are just
|
|
going to pass the error upward.
|
|
|
|
`log.iferr()` prints your message (at the `error` level) only if
|
|
`err` is truthy. Your message is *followed* by `err` stringified.
|
|
|
|
Use this:
|
|
|
|
```js
|
|
log.iferr(err, 'error happened');
|
|
```
|
|
|
|
Instead of this:
|
|
|
|
```js
|
|
if (err) {
|
|
log.error('error happened', err);
|
|
}
|
|
```
|
|
|
|
Your code will be more readable (and you can save a bunch of typing).
|
|
|
|
|
|
Logging uncaught exceptions
|
|
---------------------------
|
|
|
|
`jibo-log` registers a listener for `uncaughtExceptions` so they can
|
|
be logged. It will log the details of the exception and then re-throw
|
|
the exception. It also registers a listener for unhandled promise
|
|
errors.
|
|
|
|
It seems that handling uncaughtExceptions can sometimes confuse the
|
|
stack information about where the original exception happened. If you
|
|
are debugging such an issue you can temporarily disable this functionality:
|
|
|
|
```js
|
|
Log.logUncaughtExceptions = false;
|
|
Log.logUnhandledRejections = false;
|
|
```
|
|
|
|
And the handlers will be uninstalled which may hopefully give you
|
|
better information to help track down the problem. Please remove this
|
|
call once you've resolved the issue or uncaught exceptions will not be
|
|
logged and might be missed.
|
|
|
|
|
|
File names and line numbers
|
|
---------------------------
|
|
|
|
By default, logging to the console through `jibo-log` behaves the same way
|
|
as logging directly to the global console. It will include a stack trace only
|
|
if an Error object is called with `log.error`. If you are interested in seeing
|
|
the filename and line number for every logging call (even `debug`, `info`, and
|
|
`warn` calls), you can enable this feature by passing JSON configuration
|
|
to `Log` (see the next section) with `outputs.console.outputFileAndLine` set
|
|
to `true`.
|
|
|
|
Logging configuration
|
|
---------------------
|
|
|
|
Logging can be configured statically using a JSON file in the following format:
|
|
|
|
```json
|
|
{
|
|
"logUncaughtExceptions": true,
|
|
"logUnhandledRejections": true,
|
|
"outputs": {
|
|
"console": {
|
|
"outputFileAndLine": false
|
|
},
|
|
"syslog": {
|
|
"port": 514,
|
|
"target": "127.0.0.1"
|
|
},
|
|
"file": {
|
|
"filename": "",
|
|
"mode": "overwrite"
|
|
}
|
|
},
|
|
"namespaces": {
|
|
"": {
|
|
"console": "info",
|
|
"syslog": "info"
|
|
},
|
|
"Be.Radio.RadioPlayer": {
|
|
"console": "debug"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Once you've read the JSON file into an object of this format, or created one
|
|
manually, you can pass it to the static `loadConfig` method on `Log` before
|
|
performing any logging:
|
|
|
|
```js
|
|
const fs = require('fs');
|
|
const {Log} = require('jibo-log');
|
|
Log.loadConfig(fs.readFileSync('/path/to/logging-config.json'));
|
|
```
|
|
|
|
In the `skills-service-manager`, the default configuration is specified
|
|
separately for each robot mode, and can be modified per mode on a robot, in
|
|
the four files found in `/usr/local/etc/jibo-ssm`.
|
|
|
|
For `jibo-cli`, a default config file is created at `.jibo/t.logging.json`
|
|
in your machine's home directory. If that file does not exist, run
|
|
`jibo robot-list` once, and it will be created. When using Jibo's
|
|
simulator, this file will be used. To use this configuration on robot,
|
|
copy this file to the robot and adjust permissions with the following:
|
|
```
|
|
scp t.logging.json root@{robot-ip}:/var/jibo/
|
|
ssh root@{robot-ip} "chmod 755 /var/jibo/t.logging.json"
|
|
```
|
|
|
|
If the permissions are not set correctly, you can get this console warning:
|
|
```js
|
|
Could not load logging config file /var/jibo/t.logging.json
|
|
EACCES: permission denied, open '/var/jibo/t.logging.json'
|
|
```
|