Trawler-Internal
Provides an API for internal logging to the console and to log files to disk. The functionality provided depends on which mode you choose i.e. "trawler" or "bunyan". Works beautifully with Trawler-Std (for external application logging, restarting and crash reporting).
Usage
There are two ways to use Trawler-Internal. You can include the configuration inside the trawler
property in your package.json
which is great if you use Trawler-Std to manage your application. Otherwise you can pass a config object directly to the .init()
method. Either way you must call the .init()
method before you require any modules that use the logger.
The only supported mode
at present is bunyan
. The log variable returned by .init()
and .get()
will be an instance of a Bunyan logger which you can use as you normally would.
Package.json
In your package.json
add the config like this:
{
...
"trawler": {
...
"internal": {
"mode": "bunyan", // Required.
"logDir": "/data/logs",
"logFilename": "ops.log",
"bunyanConfig": {
"level": "debug",
"src": true,
"streams": [{
"type": "rotating-file",
"level": "debug",
"period": "1d",
"count": 30
}],
...
}
}
}
}
Then initialise Trawler-Internal by providing the path to your package.json
:
const log = require('trawler-internal').init('../');
// Don't specify anything if package.json is in the same directory!
const log = require('trawler-internal').init();
Config Object
The other way to initialise Trawler-Internal is to pass a plain config object directly to .init()
:
const packageJSON = require('./package.json');
const log = require('trawler-internal').init({
appName: packageJSON.name, // Required.
mode: 'bunyan', // Required.
logDir: '/data/logs', // Required.
logFilename: 'ops.log', // Required.
bunyanConfig: {
level: 'debug',
src: true,
streams: [{
type: 'rotating-file',
level: 'debug'
period: '1d',
count: 30
}],
...
},
});
In Other Files
To use the logger in other files and modules simply use the .get()
method and use as normal:
const log = require('trawler-internal').get();
log.info('My log message...'); // Example Bunyan log.
Config Properties
These are the properties you need to configure to use Trawler-Internal:
Property | Default | Description |
---|---|---|
appName | The name of the application Trawler-Internal is being used in. Defaults to the value in package.json unless a config object is passed directly to .init() , in which case you need to specify it manually. |
|
mode | trawler | The mode to use i.e. "trawler" or "bunyan". |
logDir | /logs | The directory where log files should be stored. This can be a Docker volume. |
logFilename | ops.log | The filename for the log files e.g. "ops.log". |
bunyanConfig | {} | Configuration options to pass to Bunyan, see Bunyan on npm. Only required if mode is "bunyan". |
Modes
Trawler-Internal supports a number of different modes depending on how you want to handle app logging.
Trawler Mode
Not Currently Implemented - Specify the mode as "trawler" (or leave blank) to use the default logging system provided by Trawler-Internal.
Bunyan Mode
Specify the mode as "bunyan" to use Bunyan as the logging module. You can specify Bunyan's configuration in the bunyanConfig
property. By default, file
and rotating-file
streams will write log files to the directory given in the logDir
property and will be named like the logFilename
property.
The log variable returned by .init()
and .get()
will be an instance of a Bunyan logger which you can use as you normally would.
In Detail
Examples
See the /examples
directory for two sample scripts that demonstrate how to use Trawler-Internal:
-
example1.js - Demonstrates specifying the configuration in your app's
package.json
file. -
example2.js - Demonstrates passing the configuration object directly to
.init()
.
Known Issues
- The "trawler" mode is not yet implemented.
- The "bunyan" mode has only been tested with simple Bunyan configurations.
- Currently doesn't support specifying different config for different environments.