README.md

Node.js Winston library for logging to LogDNA

---

• Install
• API
• Winston Transport
• License

Install

$ npm install --save logdna-winston

API

Please see @logdna/logger for instantiation options to passthrough to LogDNA's logger client.

Winston Transport

This module also provides a transport object, which can be added to winston using:

const logdnaWinston = require('logdna-winston');
const winston = require('winston');
const logger = winston.createLogger({});
const options = {
    key: apikey,
    hostname: myHostname,
    ip: ipAddress,
    mac: macAddress,
    app: appName,
    env: envName,
    level: level, // Default to debug, maximum level of log, doc: https://github.com/winstonjs/winston#logging-levels
    indexMeta: true // Defaults to false, when true ensures meta object will be searchable
}

// Only add this line in order to track exceptions
options.handleExceptions = true;

logger.add(new logdnaWinston(options));


// log with meta
logger.log({
  level: 'info'
, message: 'Log from LogDNA-winston'
, indexMeta: true // Optional.  If not provided, it will use the default.
, data:'Some information' //  Properties besides level, message and indexMetaare considered as "meta"
, error: new Error("It's a trap.") // Transport will parse the error object under property 'error'
})

// log without meta
logger.info('Info: Log from LogDNA-winston');

// A payload without 'message' will log the stringified object as the message
logger.info({
  key: 'value'
, text: 'This is some text to get logged'
, bool: true
})

Custom Log Levels

As per the Winston documentation, custom log levels may be used. In order to use such levels in LogDNA, custom levels must be defined for that logger as well. If levels is passed to this transport, they will automatically be configured as custom levels for the LogDNA logger.

Similarly, if no custom winston levels are used, then the Winston default of "npm" levels will be automatically configured for LogDNA to understand.

NOTE: The "levels" parameter is in the context of Winston, thus it should be an object where the keys are the level names, and the values are a numeric priority.

  const levels = {
    error: 0
  , warn: 1
  , info: 2
  , http: 3
  , verbose: 4
  , loquacious: 5
  , ludicrous: 6
  }
  const logger = winston.createLogger({
    levels
  , level: 'ludicrous' // needed, or else it won't log levels <= to 'info'
  })

  const logdna_options = {
    key: 'abc123'
  }
  logger.add(new logdnaWinston(logdna_options))

  // Now the custom levels can be logged in Winston and LogDNA
  logger.ludicrous('Some text')

  logger.log({
    msg: 'Custom level log message'
  , key: 'value'
  , bool: true
  , level: 'loquacious'
  })

The maxLevel Parameter

Both the Winston logger and the LogDNA logger accept a level parameter, but they mean different things:

• For Winston, level represents the maximum log level by priority. In other words, anything "higher" in priority number WILL NOT be logged.
• In LogDNA, level represents a default log level which is used in the absence of a level being defined for each log entry. Since Winston always passed a log level, this parameter is not usable in this transport.

To disambiguate the two level parameters (even though the LogDNA one cannot be used), this custom transport will accept the maxLevel parameter to be used as Winston's level parameter. This is only needed if level has not been defined during Winston's createLogger call prior to adding this custom transport.

const winston = require('winston')
const logdnaTransport = require('logdna-winston')

const logger = winston.createLogger({
  level: 'verbose'
, transports:[new logdnaTransport({key: 'abc123'})]
})
logger.silly('This will not be logged')
logger.verbose('This will be logged')

// ...is the same as this
 const logger = winston.createLogger({
  transports:[
    new logdnaTransport({
      key: 'abc123'
    , maxLevel: 'verbose'
    })
  ]
})
logger.silly('This will not be logged')
logger.verbose('This will be logged')

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Muaz Siddiqui 💻 📖	Samir Musali 💻 📖	Darin Spivey 💻 📖	Mike Huang 💻 📖	Brian Conn 📖	Mario Casciaro 💻	vilyapilya 🔧
Mike Del Tito 💻 🔧

This project follows the all-contributors specification. Contributions of any kind welcome!

License

Copyright © LogDNA, released under an MIT license. See the LICENSE file and https://opensource.org/licenses/MIT

Happy Logging!