roosevelt-logger

Intuitive, attractive logger for Node.js applications based on Winston. This module was built and is maintained by the Roosevelt web framework team, but it can be used independently of Roosevelt as well.

Install

First declare roosevelt-logger as a dependency in your app.

Usage

Require the package into your application and call its constructor:

const Logger = require('roosevelt-logger')
const logger = new Logger()

logger.log('some info')
//=> some info

logger.warn('a warning')
//=> ⚠️  a warning

logger.error('an error')
//=> ❌  an error

logger.verbose('noisy log only displayed when verbose is enabled')
//=>

logger.log('✅', 'log prepended with a custom emoji or other string')
//=> ✅  log prepended with a custom emoji or other string

Configure logger

Optionally you can pass the logger a set of configs.

methods: A set of configs that represent logger methods that are available to use. Each config type that maps to a default log type can be set to either a boolean to enable / disable the log or an object:
- info [Boolean]: Enable regular logs.
  - Default: true.
- warn [Boolean]: Enable logging of warnings.
  - Default: true.
- verbose [Boolean]: Enable verbose (noisy) logging.
  - Default: false.
- Custom log type [Object]: You can also define your own log types and specify what native log type it maps to.
  - API:
    - enable [Boolean]: Enable this custom log.
      - Default: true.
    - type [String]: What type of native log this custom log maps to.
      - Default: info.
      - Allowed values: info, warn, or error.
    - prefix: [String]: The string that prefixes any log entry. If not set or set to a falsy value (e.g. null, an empty string, etc), the prefix will be disabled.
      - Default for warnings: ⚠️.
      - Default for errors: ❌.
    - color: [String]: The color that the text will be set to using @colors/colors npm package. If not set, it will use whatever the default color is for the native type selected.
  - Example: Simple custom type example for a new log type called dbError:
```
{
  "dbError": {}
}
```
  - The above example would create a custom log type called dbError. Since no params are supplied to it, it defaults to being enabled and defaults to log type info with no prefix or color.
  - Complex custom type example:
```
{
  "dbError": {
    "enable": false,
    "type": "error",
    "prefix": "🗄",
    "color": "cyan"
  }
}
```
params: Configuration that applies to all logger methods:
- disable [Array of Strings]: Disable all logging in certain environments. Each entry can be either an environment variable or the value of the NODE_ENV environment variable.
  - Default: [].
  - Example usage:
    - ['LOADED_MOCHA_OPTS']: Disables logger when app is being run by Mocha.
    - ['production']: Disables logger when NODE_ENV is set to production.
- enablePrefix [Boolean]: Enable prefixes which can contain emojis or other strings to be prepended to logs. This can also be toggled with the ROOSEVELT_LOGGER_ENABLE_PREFIX environment variable.
  - Note: Due to lack of support for emojis in most windows terminals this param is disabled by default in windows. This can be overridden with the ROOSEVELT_LOGGER_ENABLE_PREFIX environment variable or logger.enablePrefix() method.

Usage with custom configs

Require the package into your application and call its constructor:

const logger = require('roosevelt-logger')({
    methods: {
      verbose: true, // enables verbose logging
      dbError: {     // create custom error called dbError
          type: 'error',
          prefix: '🗄'
      }
    },
    params: {
      disable: ['LOADED_MOCHA_OPTS'] // disable logging during Mocha tests
    }
})

logger.log('some info')
//=> some info

logger.warn('a warning')
//=> ⚠️  a warning

logger.error('an error')
//=> ❌  an error

logger.verbose('noisy log only displayed when verbose is enabled')
//=> noisy log only displayed when verbose is enabled

logger.dbError('custom log for database errors')
//=> 🗄  custom log for database errors

Instance properties exposed by roosevelt-logger

.winston()

The Winston module that roosevelt-logger uses internally.

.winstonInstance

The specific Winston object instance instantiated by roosevelt-logger.

.transports

The default Winston transports enabled by roosevelt-logger.

.enableLogging()

Programmatically enable the logger.

.disableLogging()

Programmatically disable the logger.

.enablePrefix()

Programmatically enable all log prefixes.

.disablePrefix()

Programmatically disable all log prefixes.

.createLogMethod(config)

Programmatically create a new logger method.

API:
- name [String]: New logger method name.
- type [String]: What type of native log this custom log maps to.
  - Default: info.
  - Allowed values: info, warn, or error.
- prefix: [String]: The string that prefixes any log entry. If not set or set to a falsy value (e.g. null, an empty string, etc), the prefix will be disabled.
  - Default for warnings: ⚠️.
  - Default for errors: ❌.
- color: [String]: The color that the text will be set to using colors npm package. If not set, it will use whatever the default color is for the native type selected.
Example:

  logger.createLogMethod({
    name: 'dbError',
    type: 'error'
    prefix: '💥',
    color: 'red'
  })

  logger.dbError('Our whole stack is in crisis mode!')
  //=> 💥 Our whole stack is in crisis mode!

Autre31415/roosevelt-logger