Skip to content

Latest commit

 

History

History
590 lines (444 loc) · 28.5 KB

transports.md

File metadata and controls

590 lines (444 loc) · 28.5 KB
Raw

Winston Transports

In winston a transport is essentially a storage device for your logs. Each instance of a winston logger can have multiple transports configured at different levels. For example, one may want error logs to be stored in a persistent remote location (like a database), but all logs output to the console or a local file.

There are several core transports included in winston, which leverage the built-in networking and file I/O offered by node.js core. In addition, there are third-party transports which are supported by the winston core team. And last (but not least) there are additional transports written by members of the community.

Winston Core

There are several core transports included in winston, which leverage the built-in networking and file I/O offered by node.js core.

Console Transport

  winston.add(winston.transports.Console, options)

The Console transport takes a few simple options:

  • level: Level of messages that this transport should log (default 'info').
  • silent: Boolean flag indicating whether to suppress output (default false).
  • colorize: Boolean flag indicating if we should colorize output (default false).
  • timestamp: Boolean flag indicating if we should prepend output with timestamps (default false). If function is specified, its return value will be used instead of timestamps.
  • json: Boolean flag indicating whether or not the output should be JSON. If true, will log out multi-line JSON objects. (default false)
  • stringify: Boolean flag indiciating if the output should be passed through JSON.stringify, resulting in single-line output. Most useful when used in conjunction with the json flag. (default false)
  • prettyPrint: Boolean flag indicating if we should util.inspect the meta (default false). If function is specified, its return value will be the string representing the meta.
  • depth Numeric indicating how many times to recurse while formatting the object with util.inspect (only used with prettyPrint: true) (default null, unlimited)
  • humanReadableUnhandledException Boolean flag indicating if uncaught exception should be output as human readable, instead of a single line
  • showLevel: Boolean flag indicating if we should prepend output with level (default true).
  • formatter: If function is specified, its return value will be used instead of default output. (default undefined)
  • stderrLevels Array of strings containing the levels to log to stderr instead of stdout, for example ['error', 'debug', 'info']. (default ['error', 'debug'])
  • (Deprecated: Use stderrLevels instead) debugStdout: Boolean flag indicating if 'debug'-level output should be redirected to stdout instead of to stderr. Cannot be used with stderrLevels. (default false)

Metadata: Logged via util.inspect(meta);

File Transport

  winston.add(winston.transports.File, options)

The File transport should really be the 'Stream' transport since it will accept any WritableStream. It is named such because it will also accept filenames via the 'filename' option:

  • level: Level of messages that this transport should log.
  • silent: Boolean flag indicating whether to suppress output.
  • colorize: Boolean flag indicating if we should colorize output.
  • timestamp: Boolean flag indicating if we should prepend output with timestamps (default true). If function is specified, its return value will be used instead of timestamps.
  • filename: The filename of the logfile to write output to.
  • maxsize: Max size in bytes of the logfile, if the size is exceeded then a new file is created, a counter will become a suffix of the log file.
  • maxFiles: Limit the number of files created when the size of the logfile is exceeded.
  • stream: The WriteableStream to write output to.
  • json: If true, messages will be logged as JSON (default true).
  • eol: string indicating the end-of-line characters to use (default to \n).
  • prettyPrint: If true, additional JSON metadata objects that are added to logging string messages will be displayed as a JSON string representation. If function is specified, its return value will be the string representing the meta.
  • depth Numeric indicating how many times to recurse while formatting the object with util.inspect (only used with prettyPrint: true) (default null, unlimited)
  • logstash: If true, messages will be logged as JSON and formatted for logstash (default false).
  • showLevel: Boolean flag indicating if we should prepend output with level (default true).
  • formatter: If function is specified and json is set to false, its return value will be used instead of default output. (default undefined)
  • tailable: If true, log files will be rolled based on maxsize and maxfiles, but in ascending order. The filename will always have the most recent log lines. The larger the appended number, the older the log file.
  • maxRetries: The number of stream creation retry attempts before entering a failed state. In a failed state the transport stays active but performs a NOOP on it's log function. (default 2)
  • zippedArchive: If true, all log files but the current one will be zipped.

Metadata: Logged via util.inspect(meta);

DailyRotateFile Transport

  winston.add(winston.transports.DailyRotateFile, options)

The DailyRotateFile transport can rotate files by minute, hour, day, month or year. Its options are identical to the File transport with the lone addition of the 'datePattern' option:

  • datePattern: A string representing the pattern to be used when appending the date to the filename (default '.yyyy-MM-dd'). The meta characters used in this string will dictate the frequency of the file rotation. For example if your datePattern is simply '.HH' you will end up with 24 log files that are picked up and appended to every day.

Valid meta characters in the datePattern are:

  • yy: Last two digits of the year.
  • yyyy: Full year.
  • M: The month.
  • MM: The zero padded month.
  • d: The day.
  • dd: The zero padded day.
  • H: The hour.
  • HH: The zero padded hour.
  • m: The minute.
  • mm: The zero padded minute.

Metadata: Logged via util.inspect(meta);

Http Transport

  winston.add(winston.transports.Http, options)

The Http transport is a generic way to log, query, and stream logs from an arbitrary Http endpoint, preferably winstond. It takes options that are passed to the node.js http or https request:

  • host: (Default: localhost) Remote host of the HTTP logging endpoint
  • port: (Default: 80 or 443) Remote port of the HTTP logging endpoint
  • path: (Default: /) Remote URI of the HTTP logging endpoint
  • auth: (Default: None) An object representing the username and password for HTTP Basic Auth
  • ssl: (Default: false) Value indicating if we should us HTTPS

Winston More

Starting with winston@0.3.0 an effort was made to remove any transport which added additional dependencies to winston. At the time there were several transports already in winston which will always be supported by the winston core team.

CouchDB Transport

As of winston@0.6.0 the CouchDB transport has been broken out into a new module: winston-couchdb.

  winston.add(winston.transports.Couchdb, options)

The Couchdb will place your logs in a remote CouchDB database. It will also create a Design Document, _design/Logs for later querying and streaming your logs from CouchDB. The transport takes the following options:

  • host: (Default: localhost) Remote host of the HTTP logging endpoint
  • port: (Default: 5984) Remote port of the HTTP logging endpoint
  • db: (Default: winston) Remote URI of the HTTP logging endpoint
  • auth: (Default: None) An object representing the username and password for HTTP Basic Auth
  • ssl: (Default: false) Value indicating if we should us HTTPS

Redis Transport

  winston.add(winston.transports.Redis, options)

This transport accepts the options accepted by the node-redis client:

  • host: (Default localhost) Remote host of the Redis server
  • port: (Default 6379) Port the Redis server is running on.
  • auth: (Default None) Password set on the Redis server

In addition to these, the Redis transport also accepts the following options.

  • length: (Default 200) Number of log messages to store.
  • container: (Default winston) Name of the Redis container you wish your logs to be in.
  • channel: (Default None) Name of the Redis channel to stream logs from.

Metadata: Logged as JSON literal in Redis

Loggly Transport

As of winston@0.6.0 the Loggly transport has been broken out into a new module: winston-loggly.

  winston.add(winston.transports.Loggly, options);

The Loggly transport is based on Nodejitsu's node-loggly implementation of the Loggly API. If you haven't heard of Loggly before, you should probably read their value proposition. The Loggly transport takes the following options. Either 'inputToken' or 'inputName' is required:

  • level: Level of messages that this transport should log.
  • subdomain: The subdomain of your Loggly account. [required]
  • auth: The authentication information for your Loggly account. [required with inputName]
  • inputName: The name of the input this instance should log to.
  • inputToken: The input token of the input this instance should log to.
  • json: If true, messages will be sent to Loggly as JSON.

Metadata: Logged in suggested Loggly format

Riak Transport

As of winston@0.3.0 the Riak transport has been broken out into a new module: winston-riak. Using it is just as easy:

  var Riak = require('winston-riak').Riak;
  winston.add(Riak, options);

In addition to the options accepted by the riak-js client, the Riak transport also accepts the following options. It is worth noting that the riak-js debug option is set to false by default:

  • level: Level of messages that this transport should log.
  • bucket: The name of the Riak bucket you wish your logs to be in or a function to generate bucket names dynamically.
  // Use a single bucket for all your logs
  var singleBucketTransport = new (Riak)({ bucket: 'some-logs-go-here' });

  // Generate a dynamic bucket based on the date and level
  var dynamicBucketTransport = new (Riak)({
    bucket: function (level, msg, meta, now) {
      var d = new Date(now);
      return level + [d.getDate(), d.getMonth(), d.getFullYear()].join('-');
    }
  });

Metadata: Logged as JSON literal in Riak

MongoDB Transport

As of winston@0.3.0 the MongoDB transport has been broken out into a new module: winston-mongodb. Using it is just as easy:

  var MongoDB = require('winston-mongodb').MongoDB;
  winston.add(MongoDB, options);

The MongoDB transport takes the following options. 'db' is required:

  • level: Level of messages that this transport should log.
  • silent: Boolean flag indicating whether to suppress output.
  • db: The name of the database you want to log to. [required]
  • collection: The name of the collection you want to store log messages in, defaults to 'log'.
  • safe: Boolean indicating if you want eventual consistency on your log messages, if set to true it requires an extra round trip to the server to ensure the write was committed, defaults to true.
  • host: The host running MongoDB, defaults to localhost.
  • port: The port on the host that MongoDB is running on, defaults to MongoDB's default port.

Metadata: Logged as a native JSON object.

Additional Transports

The community has truly embraced winston; there are over 23 winston transports and over half of them are maintained by authors external to the winston core team. If you want to check them all out, just search npm:

  $ npm search winston

If you have an issue using one of these modules you should contact the module author directly

SimpleDB Transport

The winston-simpledb transport is just as easy:

  var SimpleDB = require('winston-simpledb').SimpleDB;
  winston.add(SimpleDB, options);

The SimpleDB transport takes the following options. All items marked with an asterisk are required:

  • awsAccessKey:* your AWS Access Key
  • secretAccessKey:* your AWS Secret Access Key
  • awsAccountId:* your AWS Account Id
  • domainName:* a string or function that returns the domain name to log to
  • region:* the region your domain resides in
  • itemName: a string ('uuid', 'epoch', 'timestamp') or function that returns the item name to log

Metadata: Logged as a native JSON object to the 'meta' attribute of the item.

Mail Transport

The winston-mail is an email transport:

  var Mail = require('winston-mail').Mail;
  winston.add(Mail, options);

The Mail transport uses node-mail behind the scenes. Options are the following, to and host are required:

  • to: The address(es) you want to send to. [required]
  • from: The address you want to send from. (default: winston@[server-host-name])
  • host: SMTP server hostname
  • port: SMTP port (default: 587 or 25)
  • secure: Use secure
  • username User for server auth
  • password Password for server auth
  • level: Level of messages that this transport should log.
  • silent: Boolean flag indicating whether to suppress output.

Metadata: Stringified as JSON in email.

Amazon SNS (Simple Notification System) Transport

The winston-sns transport uses amazon SNS to send emails, texts, or a bunch of other notifications. Since this transport uses the Amazon AWS SDK for JavaScript, you can take advantage of the various methods of authentication found in Amazon's Configuring the SDK in Node.js document.

  var winston = require('winston'),
      winstonSNS = require('winston-sns');

  winston.add(winstonSNS, options);

Options:

  • subscriber: Subscriber number - found in your SNS AWS Console, after clicking on a topic. Same as AWS Account ID. [required]
  • topic_arn: Also found in SNS AWS Console - listed under a topic as Topic ARN. [required]
  • aws_key: Your Amazon Web Services Key.
  • aws_secret: Your Amazon Web Services Secret.
  • region: AWS Region to use. Can be one of: us-east-1,us-west-1,eu-west-1,ap-southeast-1,ap-northeast-1,us-gov-west-1,sa-east-1. (default: us-east-1)
  • subject: Subject for notifications. Uses placeholders for level (%l), error message (%e), and metadata (%m). (default: "Winston Error Report")
  • message: Message of notifications. Uses placeholders for level (%l), error message (%e), and metadata (%m). (default: "Level '%l' Error:\n%e\n\nMetadata:\n%m")
  • level: lowest level this transport will log. (default: info)
  • json: use json instead of a prettier (human friendly) string for meta information in the notification. (default: false)
  • handleExceptions: set to true to have this transport handle exceptions. (default: false)

Amazon CloudWatch Transport

The winston-aws-cloudwatch transport relays your log messages to Amazon CloudWatch.

  var winston = require('winston'),
      winstonAwsCloudWatch = require('winston-aws-cloudwatch');

  winston.add(winstonAwsCloudWatch, options);

Options:

  • logGroupName: The name of the CloudWatch log group to which to log. [required]
  • logStreamName: The name of the CloudWatch log stream to which to log. [required]
  • awsConfig: An object containing your accessKeyId, secretAccessKey, region, etc.

Alternatively, you may be interested in winston-cloudwatch.

Amazon DynamoDB Transport

The winston-dynamodb transport uses Amazon's DynamoDB as a sink for log messages. You can take advantage of the various authentication methods supports by Amazon's aws-sdk module. See Configuring the SDK in Node.js.

  var winston = require('winston'),
      winstonDynamo = require("winston-dynamodb");

  winstonDynamo.DynamoDB;
  winston.add(winston.transports.DynamoDB, options)

Options:

  • accessKeyId: your AWS access key id
  • secretAccessKey: your AWS secret access key
  • region: the region where the domain is hosted
  • useEnvironment: use process.env values for AWS access, secret, & region.
  • tableName: DynamoDB table name

To Configure using environment authentication:

  var options = {
    useEnvironment: true,
    tableName: 'log'
  };
  winston.add(winston.transports.DynamoDB, options);

Also supports callbacks for completion when the DynamoDB putItem has been compelted.

Papertrail Transport

winston-papertrail is a Papertrail transport:

  var Papertrail = require('winston-papertrail').Papertrail;
  winston.add(Papertrail, options);

The Papertrail transport connects to a PapertrailApp log destination over TCP (TLS) using the following options:

  • level: Level of messages this transport should log. (default: info)
  • host: FQDN or IP address of the Papertrail endpoint.
  • port: Port for the Papertrail log destination.
  • hostname: The hostname associated with messages. (default: require('os').hostname())
  • program: The facility to send log messages.. (default: default)
  • logFormat: a log formatting function with the signature function(level, message), which allows custom formatting of the level or message prior to delivery

Metadata: Logged as a native JSON object to the 'meta' attribute of the item.

Graylog2 Transport

winston-graylog2 is a Graylog2 transport:

  var winston = require('winston');
  winston.add(require('winston-graylog2'), options);

The Graylog2 transport connects to a Graylog2 server over UDP using the following options:

  • name: Transport name
  • level: Level of messages this transport should log. (default: info)
  • silent: Boolean flag indicating whether to suppress output. (default: false)
  • handleExceptions: Boolean flag, whenever to handle uncaught exceptions. (default: false)
  • graylog:
    • servers; list of graylog2 servers
      • host: your server address (default: localhost)
      • port: your server port (default: 12201)
    • hostname: the name of this host (default: os.hostname())
    • facility: the facility for these log messages (default: "Node.js")
    • bufferSize: max UDP packet size, should never exceed the MTU of your system (default: 1400)

Cassandra Transport

winston-cassandra is a Cassandra transport:

  var Cassandra = require('winston-cassandra').Cassandra;
  winston.add(Cassandra, options);

The Cassandra transport connects to a cluster using the native protocol with the following options:

  • level: Level of messages that this transport should log (default: 'info').
  • table: The name of the Cassandra column family you want to store log messages in (default: 'logs').
  • partitionBy: How you want the logs to be partitioned. Possible values 'hour' and 'day'(Default).
  • consistency: The consistency of the insert query (default: quorum).

In addition to the options accepted by the Node.js Cassandra driver Client.

  • hosts: Cluster nodes that will handle the write requests: Array of strings containing the hosts, for example ['host1', 'host2'] (required).
  • keyspace: The name of the keyspace that will contain the logs table (required). The keyspace should be already created in the cluster.

Azure Table

winston-azuretable is a Azure Table transport:

  var azureLogger = require('winston-azuretable').AzureLogger
  winston.add(azureLogger, options);

The Azure Table transport connects to an Azure Storage Account using the following options:

  • useDevStorage: Boolean flag denoting whether to use the Azure Storage Emulator (default: false)
  • account: Azure Storage Account Name. In lieu of this setting, you can set the environment variable: AZURE_STORAGE_ACCOUNT
  • key: Azure Storage Account Key. In lieu of this setting, you can set the environment variable: AZURE_STORAGE_ACCESS_KEY
  • level: lowest logging level transport to be logged (default: info)
  • tableName: name of the table to log messages (default: log)
  • partitionKey: table partition key to use (default: process.env.NODE_ENV)
  • silent: Boolean flag indicating whether to suppress output (default: false)

Airbrake Transport

winston-airbrake2 is a transport for winston that sends your logs to Airbrake.io.

  var winston = require('winston');
  winston.add(require('winston-airbrake2').Airbrake, options);

The Airbrake transport utilises the node-airbrake module to send logs to the Airbrake.io API. You can set the following options:

  • apiKey: The project API Key. (required, default: null)
  • name: Transport name. (optional, default: 'airbrake')
  • level: The level of message that will be sent to Airbrake (optional, default: 'error')
  • host: The information that is displayed within the URL of the Airbrake interface. (optional, default: 'http://' + os.hostname())
  • env: The environment will dictate what happens with your message. If your environment is currently one of the 'developmentEnvironments', the error will not be sent to Airbrake. (optional, default: process.env.NODE_ENV)
  • timeout: The maximum time allowed to send to Airbrake in milliseconds. (optional, default: 30000)
  • developmentEnvironments: The environments that will not send errors to Airbrake. (optional, default: ['development', 'test'])
  • projectRoot: Extra string sent to Airbrake. (optional, default: null)
  • appVersion: Extra string or number sent to Airbrake. (optional, default: null)
  • consoleLogError: Toggle the logging of errors to console when the current environment is in the developmentEnvironments array. (optional, default: false)

Winlog2 Transport

winston-winlog2 is a Windows Event log transport:

  var winston = require('winston');
  winston.add(require('winston-winlog2'), options);

The winlog2 transport uses the following options:

  • name: Transport name
  • eventLog: Log type (default: 'APPLICATION')
  • source: Name of application which will appear in event log (default: 'node')

Newrelic Transport

newrelic-winston is a Newrelic transport:

  var winston = require('winston');
  winston.add(require('newrelic-winston'), options);

The Newrelic transport will send your errors to newrelic and accepts the follwing optins:

  • env: the current evironment. Defatuls to process.env.NODE_ENV

If env is either 'dev' or 'test' the lib will not load the included newrelic module saving devs from anoying errors ;)

Logsene Transport

winston-logsene transport for Elasticsearch bulk indexing via HTTPS to Logsene:

  var winston = require('winston')
  var Logsene = require('winston-logsene')
  var logger = new winston.Logger()
  logger.add (Logsene, {token: process.env.LOGSENE_TOKEN})
  logger.info ("Info message no. %d logged to %s",1,'Logsene', {metadata: "test-log", count:1 , tags: ['test', 'info', 'winston'], memoryUsage: process.memoryUsage()})

Options:

  • token: Logsene Application Token
  • source: Source of the logs (defaults to main module)

Logsene features:

Find more Transports

  $ npm search winston
  (...)
  winston-amon         Winston transport for Amon logging                            =zoramite
  winston-amqp         An AMQP transport for winston                                 =kr1sp1n
  winston-cassandra    A Cassandra transport for winston                             =jorgebay
  winston-couchdb      a couchdb transport for winston                               =alz
  winston-express      Express middleware to let you use winston from the browser.   =regality
  winston-graylog2     A graylog2 transport for winston                              =smithclay
  winston-hbase        A HBase transport for winston                                 =ddude
  winston-loggly       A Loggly transport for winston                                =indexzero
  winston-mail         A mail transport for winston                                  =wavded
  winston-mail2        A mail transport for winston                                  =ivolo
  winston-mongodb      A MongoDB transport for winston                               =indexzero
  winston-nodemail     A mail transport for winston                                  =reinpk
  winston-nssocket     nssocket transport for winston                                =mmalecki
  winston-papertrail   A Papertrail transport for winston                            =kenperkins
  winston-redis        A fixed-length Redis transport for winston                    =indexzero
  winston-riak         A Riak transport for winston                                  =indexzero
  winston-scribe       A scribe transport for winston                                =wnoronha
  winston-simpledb     A Winston transport for Amazon SimpleDB                       =chilts
  winston-skywriter    A Windows Azure table storage transport for winston           =pofallon
  winston-sns          A Simple Notification System Transport for winston            =jesseditson
  winston-syslog       A syslog transport for winston                                =indexzero
  winston-syslog-ain2  An ain2 based syslog transport for winston                    =lamtha
  winston-winlog       Windows Event Log logger for Winston                          =jfromaniello
  winston-winlog2      Windows Event Log logger for Winston (no node-gyp)            =peteward44
  winston-zmq          A 0MQ transport for winston                                   =dhendo
  winston-growl        A growl transport for winston                                 =pgherveou