# winston-papertrail

> A Papertrail transport for winston

Latest version **1.0.5** (published 2017-05-17) · 0 weekly downloads

## Install

```sh
npm install winston-papertrail
pnpm add winston-papertrail
yarn add winston-papertrail
bun add winston-papertrail
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.5 |
| Published | 2017-05-17 |
| First published | 2012-04-11 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.4.0 |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 203 |
| Author | Ken Perkins |
| Maintainers | kperkins, troyd |
| Keywords | logging, sysadmin, tools, winston, papertrail, logs |

## Links

- npm: https://www.npmjs.com/package/winston-papertrail
- Repository: https://github.com/kenperkins/winston-papertrail
- Homepage: https://github.com/kenperkins/winston-papertrail#readme
- Issues: https://github.com/kenperkins/winston-papertrail/issues
- npm.io page: https://npm.io/package/winston-papertrail

## Dependencies (1)

- [glossy](https://npm.io/package/glossy.md) ^0.1.7

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 1.0.5 (latest) — 2017-05-17
- 1.0.4 — 2016-11-10
- 1.0.3 — 2016-08-24
- 1.0.2 — 2015-11-25
- 1.0.1 — 2014-12-17
- 1.0.0 — 2014-12-17
- 0.2.3 — 2014-12-13
- 0.2.2 — 2014-12-13
- 0.2.1 — 2014-12-13
- 0.2.0 — 2014-12-06
- 0.1.5 — 2014-10-14
- 0.1.4 — 2013-06-20
- 0.1.3 — 2013-05-28
- 0.1.2 — 2013-05-01
- 0.1.1 — 2013-04-14
- … 7 more at https://npm.io/package/winston-papertrail/versions

## README

# winston-papertrail [![Build Status](https://secure.travis-ci.org/kenperkins/winston-papertrail.png?branch=master)](http://travis-ci.org/kenperkins/winston-papertrail) [![NPM version](https://badge.fury.io/js/winston-papertrail.png)](http://badge.fury.io/js/winston-papertrail)

A Papertrail transport for [winston][0].

## Installation

### Installing npm (node package manager)

``` bash
  $ curl http://npmjs.org/install.sh | sh
```

### Installing winston-papertrail

``` bash
  $ npm install winston
  $ npm install winston-papertrail
```

There are a few required options for logging to Papertrail:

* __host:__ FQDN or IP Address of the Papertrail Service Endpoint
* __port:__ The Endpoint TCP Port


## Usage
``` js
  var winston = require('winston');

  //
  // Requiring `winston-papertrail` will expose
  // `winston.transports.Papertrail`
  //
  require('winston-papertrail').Papertrail;

  var winstonPapertrail = new winston.transports.Papertrail({
	host: 'logs.papertrailapp.com',
	port: 12345
  })
  
  winstonPapertrail.on('error', function(err) {
	// Handle, report, or silently ignore connection errors and failures
  });

  var logger = new winston.Logger({
	transports: [winstonPapertrail]
  });

  logger.info('this is my message');
```

There are a number of optional settings:

- `disableTls` - set to `true` to disable TLS on your transport. Defaults to `false`
- `level` - The log level to use for this transport, defaults to `info`
- `levels` - A custom mapping of log levels strings to severity levels, defaults to the mapping of `npm` levels to RFC5424 severities
- `hostname` - The hostname for your transport, defaults to `os.hostname()`
- `program` - The program for your transport, defaults to `default`
- `facility` - The syslog facility for this transport, defaults to `daemon`
- `logFormat` - A function to format your log message before sending, see below
- `colorize` - Enable colors in logs, defaults to `false`
- `inlineMeta` - Inline multi-line messages, defaults to `false`
- `handleExceptions` - Tell this Transport to handle exceptions, defaults to `false`
- `flushOnClose` - Flush any queued logs prior to closing/exiting
- `depth` - max depth for objects dumped by NodeJS `util.inspect`

There are also a number of settings for connection failure and retry behavior

- `attemptsBeforeDecay` - How many retries should be attempted before backing off, defaults to `5`
- `maximumAttempts` - How many retries before disabling buffering, defaults to `25`
- `connectionDelay` - How long between backoff in milliseconds, defaults to `1000`
- `maxDelayBetweenReconnection` - The maximum backoff in milliseconds, defaults to `60000`
- `maxBufferSize` - The maximum size of the retry buffer, in bytes, defaults to `1048576`

## Advanced Usage

For more some advanced logging, you can take advantage of custom formatting for
Papertrail:

``` js
  var winston = require('winston');

  //
  // Requiring `winston-papertrail` will expose
  // `winston.transports.Papertrail`
  //
  require('winston-papertrail').Papertrail;

  var logger = new winston.Logger({
  	transports: [
  		new winston.transports.Papertrail({
  			host: 'logs.papertrailapp.com',
  			port: 12345,
  			logFormat: function(level, message) {
  			    return '<<<' + level + '>>> ' + message;
  			}
  		})
  	]
  });

  logger.info('this is my message');
```

## Transport Events

The Papertrail transport is also capable of emitting events for `error` and `connect` so you can log to other transports:

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

var logger,
	consoleLogger = new winston.transports.Console({
		level: 'debug',
		timestamp: function() {
			return new Date().toString();
		},
		colorize: true
	}),
	ptTransport = new Papertrail({
		host: 'logs.papertrailapp.com',
		port: 12345,
		hostname: 'web-01',
		level: 'debug',
		logFormat: function(level, message) {
			return '[' + level + '] ' + message;
		}
	});

ptTransport.on('error', function(err) {
	logger && logger.error(err);
});

ptTransport.on('connect', function(message) {
	logger && logger.info(message);
});

var logger = new winston.Logger({
	levels: {
		debug: 0,
		info: 1,
		warn: 2,
		error: 3
	},
	transports: [
		ptTransport,
		consoleLogger
	]
});

logger.info('this is my message ' + new Date().getTime());
```

### Colorization

The `winston-papertrail` transport supports colorization with `winston`. Currently, the ANSI codes used for escape sequences are part of the search index, so please be advised when using colorization.

```Javascript
var winston = require('winston'),
    Papertrail = require('winston-papertrail').Papertrail;

var logger = new winston.Logger({
    transports: [
        new Papertrail({
            host: 'logs.papertrailapp.com',
            port: 12345, // your port here
            colorize: true
        })
    ]
});

logger.info('Hello from colorized winston', logger);
```

### Closing the transport

As of `v0.1.3` `winston-papertrail` transport supports closing the transport (and the underlying TLS connection) via the `Winston.Transport` `close` method. Thus, you can enable scenarios where your transport automatically closes when you close the `winston` logger.

```Javascript
var winston = require('winston'),
    Papertrail = require('winston-papertrail').Papertrail;

pt = new Papertrail({
    host: 'logs.papertrailapp.com',
    port: 12345 // your port here
});

var logger = new winston.Logger({
    transports: [ pt ]
});

pt.on('connect', function () {
    logger.info('logging before I close');
    logger.close(); // this closes the underlying connection in the Papertrail transport
});
```

#### Author: [Ken Perkins](https://twitter.com/kenperkins)

[0]: https://github.com/flatiron/winston

---
_Source: https://npm.io/package/winston-papertrail · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._