Skip to content

Commit

Permalink
[refactor doc] Move transport specific documentation into `docs/trans…
Browse files Browse the repository at this point in the history 
…ports.md`.
  • Loading branch information
@indexzero
indexzero committed Jun 30, 2015
1 parent 9b7af12 commit 7a13132
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 227 deletions.
227 changes: 1 addition & 226 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -461,7 +461,7 @@ It is also worth mentioning that the logger also emits an 'error' event which yo
Every logging method described in the previous section also takes an optional callback which will be called only when all of the transports have logged the specified message.

``` js
logger.info('CHILL WINSTON!', { seriously: true }, function (err, data) {
logger.info('CHILL WINSTON!', { seriously: true }, function (err, level, msg, meta) {
// [msg] and [meta] have now been logged at [level] to **every** transport.
});
```
Expand Down Expand Up @@ -733,231 +733,6 @@ In addition to the options accepted by the File transport, the Daily Rotate File

* __datePattern:__ Defines rolling time of a log file and suffix appended to the file. Following meta characters can be used: `yy`, `yyyy`, `M`, `MM`, `d`, `dd`, `H`, `HH`, `m`, `mm`. The default pattern is `'.yyyy-MM-dd'`. Rotation time of the log file will be equal to the smallest given time token timespan, so `'.yyyy-MM-ddTHH'` will rotate logfile every hour. You can not rotate files more frequent then every minute.

### Loggly Transport
``` js
var Loggly = require('winston-loggly').Loggly
winston.add(Loggly, options);
```

The Loggly transport is based on [Nodejitsu's][3] [node-loggly][6] implementation of the [Loggly][7] API. If you haven't heard of Loggly before, you should probably read their [value proposition][8]. 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][2]

### Riak Transport
As of `0.3.0` the Riak transport has been broken out into a new module: [winston-riak][17]. Using it is just as easy:

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

In addition to the options accepted by the [riak-js][3] [client][4], 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.

``` js
// 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 `0.3.0` the MongoDB transport has been broken out into a new module: [winston-mongodb][16]. Using it is just as easy:

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

For more information about its arguments, check [winston-mongodb's README][16].

* __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.

### SimpleDB Transport

The [winston-simpledb][18] transport is just as easy:

``` js
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][19] is an email transport:

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

The Mail transport uses [emailjs](https://github.com/eleith/emailjs) behind the scenes. Options are the following:

* __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 (default: localhost)
* __port:__ SMTP port (default: 587 or 25)
* __username__ User for server auth
* __password__ Password for server auth
* __ssl:__ Use SSL (boolean or object { key, ca, cert })
* __tls:__ Boolean (if true, use starttls)
* __level:__ Level of messages that this transport should log.
* __silent:__ Boolean flag indicating whether to suppress output.

*Metadata:* Stringified as JSON in email.

### Amazon DynamoDB Transport
The [winston-dynamodb][26] 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](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html).

``` 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:
``` js
var options = {
useEnvironment: true,
tableName: 'log'
};
winston.add(winston.transports.DynamoDB, options);
```

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

### Amazon SNS (Simple Notification System) Transport

The [winston-sns][25] 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](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html) document.

``` js
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`)

### Graylog2 Transport

[winston-graylog2][22] is a Graylog2 transport:

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

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

* __level:__ Level of messages this transport should log. (default: info)
* __silent:__ Boolean flag indicating whether to suppress output. (default: false)

* __graylogHost:__ IP address or hostname of the graylog2 server. (default: localhost)
* __graylogPort:__ Port to send messages to on the graylog2 server. (default: 12201)
* __graylogHostname:__ The hostname associated with graylog2 messages. (default: require('os').hostname())
* __graylogFacility:__ The graylog2 facility to send log messages.. (default: nodejs)

*Metadata:* Stringified as JSON in the full message GELF field.

### Papertrail Transport

[winston-papertrail][23] is a Papertrail transport:

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

The Papertrail transport connects to a [PapertrailApp log destination](https://papertrailapp.com) 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.

### Cassandra Transport

[winston-cassandra][24] is a Cassandra transport:

``` js
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](https://github.com/datastax/nodejs-driver) Client.

* __contactPoints:__ Cluster nodes that will handle the write requests:
Array of strings containing the contact points, 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.

### Adding Custom Transports
Adding a custom transport (say for one of the datastore on the Roadmap) is actually pretty easy. All you need to do is accept a couple of options, set a name, implement a log() method, and add it to the set of transports exposed by winston.

Expand Down
50 changes: 49 additions & 1 deletion docs/transports.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -311,6 +311,55 @@ Options:
* __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 DynamoDB Transport
The [winston-dynamodb][26] 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](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html).

``` 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:
``` js
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][23] is a Papertrail transport:

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

The Papertrail transport connects to a [PapertrailApp log destination](https://papertrailapp.com) 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][19] is a Graylog2 transport:
Expand All @@ -334,7 +383,6 @@ The Graylog2 transport connects to a Graylog2 server over UDP using the followin
- __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][20] is a Cassandra transport:
Expand Down

0 comments on commit 7a13132

Please sign in to comment.