Skip to content

Latest commit

 

History

History
1131 lines (862 loc) · 43.8 KB

transports.md

File metadata and controls

1131 lines (862 loc) · 43.8 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).
  • lazy: If true, log files will be created on demand, not at the initialization time.
  • 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 use HTTPS
  • batch: (Default: false) Value indicating if batch mode should be used. A batch of logs to send through the HTTP request when one of the batch options is reached: number of elements, or timeout
  • batchInterval: (Default: 5000 ms) Value indicating the number of milliseconds to wait before sending the HTTP request
  • batchCount: (Default: 10) Value indicating the number of logs to cumulate before sending the HTTP request

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 completed.

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)

Cloudant

winston-clodant is a transport for Cloudant NoSQL Db.

const winston = require('winston');
const WinstonCloudant = require('winston-cloudant');
logger.add(new WinstonCloudant(options));

The Cloudant transport takes the following options:

url         : Access url including user and password [required]
username    : Username for the Cloudant DB instance
password    : Password for the Cloudant DB instance
host        : Host for the Cloudant DB instance
db          : Name of the databasename to put logs in
logstash    : Write logs in logstash format

Datadog Transport

datadog-winston is a transport to ship your logs to datadog.

var winston = require('winston')
var DatadogWinston = require('datadog-winston')

var logger = winston.createLogger({
  // Whatever options you need
  // Refer https://github.com/winstonjs/winston#creating-your-own-logger
})

logger.add(
  new DatadogWinston({
    apiKey: 'super_secret_datadog_api_key',
    hostname: 'my_machine',
    service: 'super_service',
    ddsource: 'nodejs',
    ddtags: 'foo:bar,boo:baz'
  })
)

Options:

  • apiKey: Your datadog api key [required]
  • hostname: The machine/server hostname
  • service: The name of the application or service generating the logs
  • ddsource: The technology from which the logs originated
  • ddtags: Metadata associated with the logs

Google BigQuery

winston-bigquery is a transport for Google BigQuery.

import {WinstonBigQuery} from 'winston-bigquery';
import winston, {format} from 'winston';

const logger = winston.createLogger({
	transports: [
		new WinstonBigQuery({
			tableId: 'winston_logs',
			datasetId: 'logs'
		})
	]
});

The Google BigQuery takes the following options:

  • datasetId : Your dataset name [required]
  • tableId : Table name in the datase [required]
  • applicationCredentials : a path to local service worker (useful in dev env) [Optional]

Pay Attention, since BQ, unlike some other products, is not a "schema-less" you will need to build the schema in advance. read more on the topic on github or npmjs.com

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.

FastFileRotate Transport

fast-file-rotate is a performant file transport providing daily log rotation.

const FileRotateTransport = require('fast-file-rotate');
const winston = require('winston');

const logger = winston.createLogger({
  transports: [
    new FileRotateTransport({
      fileName: __dirname + '/console%DATE%.log'
    })
  ]
})

Humio Transport

humio-winston is a transport for sending logs to Humio:

const winston = require('winston');
const HumioTransport = require('humio-winston');

const logger = winston.createLogger({
  transports: [
    new HumioTransport({
      ingestToken: '<YOUR HUMIO INGEST TOKEN>',
    }),
  ],
});

LogDNA Transport

LogDNA Winston is a transport for being able to forward the logs to LogDNA:

const logdnaWinston = require('logdna-winston');
const winston = require('winston');
const logger = winston.createLogger({});
const options = {
    key: apikey, // the only field required
    hostname: myHostname,
    ip: ipAddress,
    mac: macAddress,
    app: appName,
    env: envName,
    index_meta: 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));

let meta = {
    data:'Some information'
};
logger.log('info', 'Log from LogDNA Winston', meta);

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.

MySQL Transport

winston-mysql is a MySQL transport for Winston.

Create a table in your database first:

 CREATE TABLE `sys_logs_default` (
 `id` INT NOT NULL AUTO_INCREMENT,
 `level` VARCHAR(16) NOT NULL,
 `message` VARCHAR(2048) NOT NULL,
 `meta` VARCHAR(2048) NOT NULL,
 `timestamp` DATETIME NOT NULL,
 PRIMARY KEY (`id`));

You can also specify meta to be a JSON field on MySQL 5.7+, i.e., ``meta JSON NOT NULL, which is helfpul for searching and parsing.

Configure Winston with the transport:

import MySQLTransport from 'winston-mysql';

const options = {
    host: '${MYSQL_HOST}',
    user: '${MYSQL_USER}',
    password: '${MYSQL_PASSWORD}',
    database: '${MYSQL_DATABASE}',
    table: 'sys_logs_default'
};

const logger = winston.createLogger({
    level: 'debug',
    format: winston.format.json(),
    defaultMeta: { service: 'user-service' },
    transports: [
        new winston.transports.Console({
            format: winston.format.simple(),
        }),
        new MySQLTransport(options),
    ],
});

/// ...
let msg = 'My Log';
logger.info(msg, {message: msg, type: 'demo'});

New Relic Agent Transport

winston-newrelic-agent-transport is a New Relic transport that leverages the New Relic agent:

import winston from 'winston'
import NewrelicTransport from 'winston-newrelic-agent-transport'

const logger = winston.createLogger()

const options = {}
logger.add(new NewrelicTransport(options))

The New Relic agent typically automatically forwards Winston logs to New Relic when using CommonJS. With CommonJS no additional transport should be needed. However, when using ECMAScript modules, the automatic forwarding of logs can with certain coding patterns not work. If the New Relic agent is not automatically forwarding your logs, this transport provides a solution.

Options:

  • level (optional): The Winston logging level to use as the maximum level of messages that the transport will log.
  • rejectCriteria (optional): The rejectCriteria option allows you to specify an array of regexes that will be matched against either the Winston info object or log message to determine whether or not a log message should be rejected and not logged to New Relic.

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.

Parseable Transport

Parseable is an open source, general purpose log analytics system. Parseable-Winston is a Parseable transport for Winston.

// Using cjs
const { ParseableTransport } = require('parseable-winston')
const winston = require('winston')

const parseable = new ParseableTransport({
  url: process.env.PARSEABLE_LOGS_URL, // Ex: 'https://parsable.myserver.local/api/v1/logstream'
  username: process.env.PARSEABLE_LOGS_USERNAME,
  password: process.env.PARSEABLE_LOGS_PASSWORD,
  logstream: process.env.PARSEABLE_LOGS_LOGSTREAM, // The logstream name
  tags: { tag1: 'tagValue' } // optional tags to be added with each ingestion
})

const logger = winston.createLogger({
  levels: winston.config.syslog.levels,
  transports: [parseable],
  defaultMeta: { instance: 'app', hostname: 'app1' }
})

logger.info('User took the goggles', { userid: 1, user: { name: 'Rainier Wolfcastle' } })
logger.warning('The goggles do nothing', { userid: 1 })

PostgresQL Transport

@pauleliet/winston-pg-native is a PostgresQL transport supporting Winston 3.X.

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)

Sentry Transport

winston-transport-sentry-node is a transport for Sentry uses @sentry/node.

const Sentry = require('winston-transport-sentry-node').default;
logger.add(new Sentry({
  sentry: {
    dsn: 'https://******@sentry.io/12345',
  },
  level: 'info'
}));

This transport takes the following options:

  • sentry: [Object]
    • dsn: Sentry DSN or Data Source Name (default: process.env.SENTRY_DSN) REQUIRED
    • environment: The application environment (default: process.env.SENTRY_ENVIRONMENT || process.env.NODE_ENV || 'production')
    • serverName: The application name
    • debug: Turns debug mode on or off (default: process.env.SENTRY_DEBUG || false)
    • sampleRate: Sample rate as a percentage of events to be sent in the range of 0.0 to 1.0 (default: 1.0)
    • maxBreadcrumbs: Total amount of breadcrumbs that should be captured (default: 100)
  • level: Level of messages that this transport should log
  • silent: Boolean flag indicating whether to suppress output, defaults to false

Seq Transport

winston-seq is a transport that sends structured log events to Seq.

const { SeqTransport } = require('@datalust/winston-seq');
logger.add(new SeqTransport({
  serverUrl: "https://your-seq-server:5341",
  apiKey: "your-api-key",
  onError: (e => { console.error(e) }),
}));

SeqTransport is configured with the following options:

  • serverUrl - the URL for your Seq server's ingestion
  • apiKey - (optional) The Seq API Key to use
  • onError - Callback to execute when an error occurs within the transport

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.

Slack Transport

winston-slack-webhook-transport is a transport that sends all log messages to the Slack chat service.

const winston = require('winston');
const SlackHook = require('winston-slack-webhook-transport');

const logger = winston.createLogger({
	level: 'info',
	transports: [
		new SlackHook({
			webhookUrl: 'https://hooks.slack.com/services/xxx/xxx/xxx'
		})
	]
});

logger.info('This should now appear on Slack');

This transport takes the following options:

  • webhookUrl - Slack incoming webhook URL. This can be from a basic integration or a bot. REQUIRED
  • channel - Slack channel to post message to.
  • username - Username to post message with.
  • iconEmoji - Status icon to post message with. (interchangeable with iconUrl)
  • iconUrl - Status icon to post message with. (interchangeable with iconEmoji)
  • formatter - Custom function to format messages with. This function accepts the info object (see Winston documentation) and must return an object with at least one of the following three keys: text (string), attachments (array of attachment objects), blocks (array of layout block objects). These will be used to structure the format of the logged Slack message. By default, messages will use the format of [level]: [message] with no attachments or layout blocks.
  • level - Level to log. Global settings will apply if this is blank.
  • unfurlLinks - Enables or disables link unfurling. (Default: false)
  • unfurlMedia - Enables or disables media unfurling. (Default: false)
  • mrkdwn - Enables or disables mrkdwn formatting within attachments or layout blocks (Default: false)

SQLite3 Transport

The winston-better-sqlite3 transport uses better-sqlite3.

const wbs = require('winston-better-sqlite3');
logger.add(new wbs({

    // path to the sqlite3 database file on the disk
    db: '<name of sqlite3 database file>',

    // A list of params to log
    params: ['level', 'message']
}));

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.

VS Code extension

winston-transport-vscode is a transport for VS Code extension development.

const vscode = require('vscode');
const winston = require('winston');
const { OutputChannelTransport } = require('winston-transport-vscode');

const outputChannel = vscode.window.createOutputChannel('My extension');

const logger = winston.createLogger({
  transports: [new OutputChannelTransport({ outputChannel })],
});

The extension includes dedicated log levels and format for using with VS Code's LogOutputChannel.

const { LogOutputChannelTransport } = require('winston-transport-vscode');

const outputChannel = vscode.window.createOutputChannel('My extension', {
  log: true,
});

const logger = winston.createLogger({
  levels: LogOutputChannelTransport.config.levels,
  format: LogOutputChannelTransport.format(),
  transports: [new LogOutputChannelTransport({ outputChannel })],
});

Worker Thread based async Console transport

winston-console-transport-in-worker

import * as winston from 'winston';
import { ConsoleTransportInWorker } from '@rpi1337/winston-console-transport-in-worker';

...

export const logger: winston.Logger = winston.createLogger({
    format: combine(timestamp(), myFormat),
    level: Level.INFO,
    transports: [new ConsoleTransportInWorker()],
});

The ConsoleTransportInWorker is a subclass of winston.transports.Console therefore accepting the same options as the Console transport.

TypeScript supported.

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 more than 1000 packages on npm when you search for winston. That's why we say it's a logger for just about everything