README
n-logger
This package provides a Winston wrapper which sends server-side logs to Splunk's HTTP Event Collector (HEC).
Please note that this package is not only used by the Customer Products team. Please be mindful of this as any changes may impact other teams, such as Internal Products, differently.
Getting started
This package is compatible with the Node version defined by engines.node
in package.json
(run command nvm use
to switch your local Node version to the one specified in .nvmrc
) and is distributed on npm.
npm install --save @financial-times/n-logger
After installing the package you will need to configure your production application with the SPLUNK_HEC_TOKEN
environment variable. If you are working on a next-
application this will be specified in the shared secrets folder in Vault.
Usage
import logger from '@financial-times/n-logger';
logger.log('info', 'Saying hello');
logger.info('Saying hello');
logger.warn('Everything’s mostly cool');
logger.error('Uh-oh', { field: 'some value' });
logger.info({ event: 'UPDATE_NOTIFICATION', data: data });
const error = new Error('Whoops!');
logger.error('Uh-oh', error, { extra_field: 'boo' });
If using CommonJS modules:
const logger = require('@financial-times/n-logger').default;
Loggers
By default, the following loggers are configured:
The
console
loggerThe default logger. The log levels to output to the terminal can be set using the
CONSOLE_LOG_LEVEL
environment variable (defaults tosilly
).The
splunkHEC
loggerUsed if the
SPLUNK_HEC_TOKEN
environment variable is present. The log levels to send to Splunk can be set using theSPLUNK_LOG_LEVEL
environment variable (defaults towarn
).
Testing n-logger locally
If you are making a change to n-logger
it is worth testing it locally to check it is sending logs successfully before merging.
- Create a test.js file in the root of your local n-logger.
- Add the following to this file:
const logger = require('./dist/main').default;
logger.warn('Testing Testing Testing');
logger.warn({ event: 'HELLO_WORLD', message: 'Testing 1 2 3', count: 5 }, {fizz: 'buzz'});
In the terminal
export NODE_ENV=production
,export SYSTEM_CODE=next-foo-bar
andexport SPLUNK_HEC_TOKEN={token}
(find this token in thenext/shared
folder in Vault).Run
node test
in the terminal.If everything is working correctly, you should be able to see your test logs in Splunk with the query
index=heroku source="/var/log/apps/heroku/ft-next-foo-bar.log"
.
API
log(level, message, ...meta)
level
can be silly, debug, verbose, info, warn or errormessage
is optional- any number of meta objects can be supplied, including
Error
objects - IMPORTANT NOTE - do not send errors as properties of other objects, e.g.
{event: 'My_EVENT', error}
. This will result in no details of the error being logged**
silly|debug|verbose|info|warn|error(message, ...meta)
addConsole(level = 'info', opts = {})
removeConsole()
addSplunkHEC(level = 'info', opts = {})
removeSplunkHEC()
clearLoggers()
addContext(metadata = {})
Additional metadata
properties to be appended to every subsequent log call.
logger
The Winston object