PurpleTeam logger wraps winston
for PurpleTeam components, provides a custom signale
transport, and is open to be extended with additional transports.
purpleteam-logger is used heavily throughout most of the PurpleTeam projects.
Contents
Install
npm install purpleteam-logger
Usage
Create a Reusable Logger
Where ever you need a logger:
import { init as initLogger } from 'purpleteam-logger';
const log = initLogger({ level: 'debug' });
This will return an existing logger (with a default Console
transport) if one was already created.
Otherwise a winston logger will be created.
As part of creating a logger, the passed options
object will be validated that the level
is one of the syslog
levels.
a combined format (format.combine
) will be created. in which we:
- colorize the output
- Create a custom format (called
tagger
) by passing the bespoke (tagger
)transform
which consumes any tags from the log event and formats them into the printed message, along with the event message - If
NODE_ENV
isproduction
- Include a
winston.format.timestamp
- Bespoke format the messages with a function (
prodFormatter
) that utiliseswinston.format.printf
to format the printed message astimestamp
level
message
(message
includes any tags from thetagger
)
- Include a
- If
NODE_ENV
isdevelopment
-
format.simple
instead of including a timestamp
-
and finally a winston.transport.console
transport is added to the transports
array property of the options object used to create the logger. This could be made more extensible.
Use the Logger
log.info('Server registered.', {tags: ['startup']});
log.info('Server started.', {tags: ['startup']});
// ...
log.info('running testJob', {tags: ['app']});
// ...
log.notice(`Constructing the cucumber world for session with id "${id}".\n`, {tags: ['world']});
// ...
log.notice(`Located element using id="${attackField.name}", and sent keys.`, {tags: ['browser']});
// ...
In development
:
In production
:
The available log levels are listed here;
Specify Transport(s)
By default the winston.transports.Console
will be used.
import { init as initLogger } from 'purpleteam-logger';
const log = initLogger({ level: 'debug', transports: ['Console'] });
You can specify the name of one or more transport constructors.
Using the SignaleTransport
alone for example looks like the following:
import { init as initLogger } from 'purpleteam-logger';
const log = initLogger({ level: 'debug', transports: ['SignaleTransport'] });
Using the File
alone for example looks like the following:
import { init as initLogger } from 'purpleteam-logger';
const log = initLogger({ level: 'debug', transports: ['File'], filename: '/path/to/your/logfile' });
Use the Logger
log.emerg('This is what an emergency looks like.', { tags: ['emerg-tag'] });
log.alert('This is what an alert looks like.', { tags: ['alert-tag'] });
log.crit('This is what a critical event looks like.', { tags: ['crit-tag'] });
log.error('This is what an error looks like.', { tags: ['error-tag'] });
log.warning('This is what a warning looks like.', { tags: ['warning-tag'] });
log.notice('This is what a notice looks like.', { tags: ['notice-tag'] });
log.info('This is what an info event looks like.', { tags: ['info-tag'] });
log.debug('This is what a debug event looks like.', { tags: ['debug-tag'] });
In development
:
In production
:
Add more Loggers
If you want to add extra loggers after the default logger has been init
ialised. See the Winston docs for more details.
import { init as initLogger } from 'purpleteam-logger';
const log = initLogger({ level: 'debug' });
log.add('nameForYourNewLogger', { transports: ['File'], filename: '/path/to/your/logfile' })
API
init(options)
Creates and returns a configured logger. If one already exists, it will be returned without creating another.
-
options
: Configuration object for the logger instance-
level
: Can be one of thesyslog
levels:'emerg'
,'alert'
,'crit'
,'error'
,'warning'
,'notice'
,'info'
,'debug'
-
transports
: An array of strings of any of the names of transport constructors. You can specify multiple transports in thetransports
array. These can be any combination of thewinston
core transports, and/or the custom transports (Any transport inside thesrc/transports/
directory will be available for selection once added to theindex.js
),SignaleTransport
for example
-
get(['default'])
Returns the already instantiated logger object, unless one hasn't been instantiated yet by init
, in which case an informative Error
will be thrown.
If an argument of 'default'
or no argument is passed to get
, the 'default' logger will be returned if it has been init
ialised.
If you supply an argument that is the name of a logger you have created previously, then that logger will be returned to you.
add(catagory, [options])
If no options
are supplied to add
, a new options
object will be created using a transport of Console
, and the same level
that the default logger has.
Custom Transport Details
Currently signale
is the only custom transport in the project, feel free to add additional transports.
The signale
types can be seen at:
Which utilise figures for icons.
Examples
There are many examples of how purpleteam-logger is being used in the purpleteam-labs projects in both development and production environments. In particular the following projects would be a good place to start:
There are also videos of purpleteam-logger in action.
Contribution
Please open an issue to discus the proposed change before submitting a pull request.
License
Copyright Kim Carter and other contributors, Licensed under MIT.