Skip to content

Latest commit

 

History

History
726 lines (544 loc) · 29.5 KB

transports.md

File metadata and controls

726 lines (544 loc) · 29.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 that leverage the built-in networking and file I/O offered by Node.js core. In addition, there are transports which are actively supported by winston contributors. And last (but not least) there are additional transports written by members of the community.

Additionally there are transports previously maintained by winston contributors that are looking for maintainers.

Built-in to winston

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

logger.add(new winston.transports.Console(options));

The Console transport takes a few simple options:

  • level: Level of messages that this transport should log (default: level set on parent logger).
  • silent: Boolean flag indicating whether to suppress output (default false).
  • eol: string indicating the end-of-line characters to use (default os.EOL)
  • stderrLevels Array of strings containing the levels to log to stderr instead of stdout, for example ['error', 'debug', 'info']. (default [])
  • consoleWarnLevels Array of strings containing the levels to log using console.warn or to stderr (in Node.js) instead of stdout, for example ['warn', 'debug']. (default [])

File Transport

logger.add(new winston.transports.File(options));

The File transport supports a variety of file writing options. If you are looking for daily log rotation see [DailyRotateFile]

  • level: Level of messages that this transport should log (default: level set on parent logger).
  • silent: Boolean flag indicating whether to suppress output (default false).
  • eol: Line-ending character to use. (default: os.EOL).
  • 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.
  • 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. This option requires maxFiles to be set, or it will be ignored.
  • 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.
  • options: options passed to fs.createWriteStream (default {flags: 'a'}).
  • stream: DEPRECATED The WriteableStream to write output to.

Http Transport

logger.add(new 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

Stream Transport

logger.add(new winston.transports.Stream({
  stream: fs.createWriteStream('/dev/null')
  /* other options */
}));

The Stream transport takes a few simple options:

  • stream: any Node.js stream. If an objectMode stream is provided then the entire info object will be written. Otherwise info[MESSAGE] will be written.
  • level: Level of messages that this transport should log (default: level set on parent logger).
  • silent: Boolean flag indicating whether to suppress output (default false).
  • eol: Line-ending character to use. (default: os.EOL).

Maintained by winston contributors

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 have slowly waned in usage. The following transports are actively maintained by members of the winston Github organization.

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:

const winston = require('winston');

/**
 * Requiring `winston-mongodb` will expose
 * `winston.transports.MongoDB`
 */
require('winston-mongodb');

logger.add(new winston.transports.MongoDB(options));

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

  • level: Level of messages that this transport should log, defaults to 'info'.
  • silent: Boolean flag indicating whether to suppress output, defaults to false.
  • db: MongoDB connection uri, pre-connected db object or promise object which will be resolved with pre-connected db object.
  • options: MongoDB connection parameters (optional, defaults to {poolSize: 2, autoReconnect: true}).
  • collection: The name of the collection you want to store log messages in, defaults to 'log'.
  • storeHost: Boolean indicating if you want to store machine hostname in logs entry, if set to true it populates MongoDB entry with 'hostname' field, which stores os.hostname() value.
  • username: The username to use when logging into MongoDB.
  • password: The password to use when logging into MongoDB. If you don't supply a username and password it will not use MongoDB authentication.
  • label: Label stored with entry object if defined.
  • name: Transport instance identifier. Useful if you need to create multiple MongoDB transports.
  • capped: In case this property is true, winston-mongodb will try to create new log collection as capped, defaults to false.
  • cappedSize: Size of logs capped collection in bytes, defaults to 10000000.
  • cappedMax: Size of logs capped collection in number of documents.
  • tryReconnect: Will try to reconnect to the database in case of fail during initialization. Works only if db is a string. Defaults to false.
  • expireAfterSeconds: Seconds before the entry is removed. Works only if capped is not set.

Metadata: Logged as a native JSON object in 'meta' property.

Logging unhandled exceptions: For logging unhandled exceptions specify winston-mongodb as handleExceptions logger according to winston documentation.

DailyRotateFile Transport

See [winston-dailyrotatefile].

Syslog Transport

See [winston-syslog].

Community 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

Airbrake Transport

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

const winston = require('winston');
const { Airbrake } = require('winston-airbrake2');
logger.add(new 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)

Amazon CloudWatch Transport

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

const winston = require('winston');
const AwsCloudWatch = require('winston-aws-cloudwatch');

logger.add(new AwsCloudWatch(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.

const winston = require('winston');
const { DynamoDB } = require('winston-dynamodb');

logger.add(new 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:

logger.add(new winston.transports.DynamoDB({
  useEnvironment: true,
  tableName: 'log'
});

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

Amazon Kinesis Firehose Transport

The winston-firehose transport relays your log messages to Amazon Kinesis Firehose.

const winston = require('winston');
const WFirehose = require('winston-firehose');

logger.add(new WFirehose(options));

Options:

  • streamName: The name of the Amazon Kinesis Firehose stream to which to log. [required]
  • firehoseOptions: The AWS Kinesis firehose options to pass direction to the firehose client, as documented by AWS. [required]

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.

const winston = require('winston');
const SnsTransport = require('winston-sns');

logger.add(new SnsTransport(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)

Azure Table

winston-azuretable is a Azure Table transport:

const { AzureLogger } = require('winston-azuretable');
logger.add(new 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)

Cassandra Transport

winston-cassandra is a Cassandra transport:

const Cassandra = require('winston-cassandra').Cassandra;
logger.add(new 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.

Cisco Spark Transport

winston-spark is a transport for Cisco Spark

const winston = require('winston');
require('winston-spark');

const options = {
  accessToken: '***Your Spark Access Token***',
  roomId: '***Spark Room Id***'
};

logger.add(new winston.transports.SparkLogger(options));

Valid Options are as the following:

  • accessToken Your Spark Access Token. [required]
  • roomId Spark Room Id. [required]
  • level Log Level (default: info)
  • hideMeta Hide MetaData (default: false)

Google Stackdriver Transport

@google-cloud/logging-winston provides a transport to relay your log messages to Stackdriver Logging.

const winston = require('winston');
const Stackdriver = require('@google-cloud/logging-winston');
logger.add(new Stackdriver({
  projectId: 'your-project-id',
  keyFilename: '/path/to/keyfile.json'
}));

Graylog2 Transport

winston-graylog2 is a Graylog2 transport:

const winston = require('winston');
const Graylog2 = require('winston-graylog2');
logger.add(new 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)

Elasticsearch Transport

Log to Elasticsearch in a logstash-like format and leverage Kibana to browse your logs.

See: https://github.com/vanthome/winston-elasticsearch.

Logzio Transport

You can download the logzio transport here : https://github.com/logzio/winston-logzio

Basic Usage

const winston = require('winston');
const Logzio = require('winston-logzio');

logger.add(new Logzio({
  token: '__YOUR_API_TOKEN__'
}));

For more information about how to configure the logzio transport, view the README.md in the winston-logzio repo.

Logsene Transport

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

const winston = require('winston');
const Logsene = require('winston-logsene');

logger.add(new Logsene({
  token: process.env.LOGSENE_TOKEN
  /* other options */
});

Options:

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

Logsene features:

Mail Transport

The winston-mail is an email transport:

const { Mail } = require('winston-mail');
logger.add(new 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.

Newrelic Transport

newrelic-winston is a Newrelic transport:

const winston = require('winston');
const Newrelic = require('newrelic-winston');
logger.add(new Newrelic(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 ;)

Papertrail Transport

winston-papertrail is a Papertrail transport:

const { Papertrail } = require('winston-papertrail');
logger.add(new 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.

Pusher Transport

winston-pusher is a Pusher transport.

const { PusherLogger } = require('winston-pusher');
logger.add(new PusherLogger(options));

This transport sends the logs to a Pusher app for real time processing and it uses the following options:

  • pusher [Object]
    • appId The application id obtained from the dashboard
    • key The application key obtained from the dashboard
    • secret The application secret obtained from the dashboard
    • cluster The cluster
    • encrypted Whether the data will be send through SSL
  • channel The channel of the event (default: default)
  • event The event name (default: default)

SimpleDB Transport

The winston-simpledb transport is just as easy:

const SimpleDB = require('winston-simpledb').SimpleDB;
logger.add(new 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.

Sumo Logic Transport

winston-sumologic-transport is a transport for Sumo Logic

const winston = require('winston');
const { SumoLogic } = require('winston-sumologic-transport');

logger.add(new SumoLogic(options));

Options:

  • url: The Sumo Logic HTTP collector URL

SSE transport with KOA 2

winston-koa-sse is a transport that leverages on Server Sent Event. With this transport you can use your browser console to view your server logs.

Winlog2 Transport

winston-winlog2 is a Windows Event log transport:

const winston = require('winston');
const Winlog2 = require('winston-winlog2');
logger.add(new 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')

Looking for maintainers

These transports are part of the winston Github organization but are actively seeking new maintainers. Interested in getting involved? Open an issue on winston to get the conversation started!

CouchDB Transport

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

const WinstonCouchDb = require('winston-couchdb');
logger.add(new WinstonCouchdb(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

Loggly Transport

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

const WinstonLoggly = require('winston-loggly');
logger.add(new 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.

Redis Transport

const WinstonRedis = require('winston-redis');
logger.add(new WinstonRedis(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.

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:

const { Riak } = require('winston-riak');
logger.add(new 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
  const singleBucketTransport = new Riak({ bucket: 'some-logs-go-here' });

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

Find more Transports

There are almost 1000 packages on npm when you search for winston. That's why we say it's a logger for just about everything