# sentry-transport-winston

> A Sentry Transport for Winston v3

Latest version **1.0.2** (published 2020-02-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install sentry-transport-winston
pnpm add sentry-transport-winston
yarn add sentry-transport-winston
bun add sentry-transport-winston
```

## Health

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

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2020-02-03 |
| First published | 2019-07-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 13.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Walmor Moreira |
| Maintainers | walmor |
| Keywords | sentry, winston, winston3, transport, logger, logging |

## Links

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

## Dependencies (3)

- [winston](https://npm.io/package/winston.md) ^3.2.1
- [@sentry/node](https://npm.io/package/@sentry/node.md) ^5.11.2
- [winston-transport](https://npm.io/package/winston-transport.md) ^4.3.0

## 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.2 (latest) — 2020-02-03
- 1.0.1 — 2019-07-15
- 1.0.0 — 2019-07-15
- 0.0.1 — 2019-07-14

## README

# A Sentry Transport for Winston@3

![CircleCI](https://img.shields.io/circleci/build/github/walmor/sentry-transport-winston.svg)
[![codecov](https://codecov.io/gh/walmor/sentry-transport-winston/branch/master/graph/badge.svg)](https://codecov.io/gh/walmor/sentry-transport-winston)
![winston](https://img.shields.io/badge/winston-v3.2.1-informational.svg)
![sentry](https://img.shields.io/badge/sentry-v5.5.0-informational.svg)

A [Sentry](https://sentry.io/) transport for [Wiston@3](https://github.com/winstonjs/) using [@sentry/node](https://github.com/getsentry/sentry-javascript/tree/master/packages/node) that allows logging context data, such as user, tags, fingerprint, and extra data. Learn more checking the [Sentry Documentation](https://docs.sentry.io/enriching-error-data/context/?platform=node).

## Installation

```bash
# npm
npm install sentry-transport-winston

# yarn
yarn add sentry-transport-winston
```

## Initializing

```typescript
import { SentryTransport } from 'sentry-transport-winston';

const opts: SentryTransportOpts = {
  sentryOpts: {
    dns: '<sentry-dns>',
  },
};

const sentry = new SentryTransport(opts);

const logger = winston.createLogger({
  transports: [sentry],
});
```

### Transport Options

The `SentryTransportOpts` interface is extending the `TransportStreamOptions` so you can pass any options that are handled by the base winston transport stream, such as `format`. Take a look [here](https://github.com/winstonjs/winston-transport/blob/46db8f3c8cd8b106ade8d7e04a191ee388683d60/index.d.ts#L25) to see all the available options.

### Sentry Options

The `SentryTransportOpts` includes the property `sentryOpts` which is passed directly to the `Sentry.init()` method, without any changes. All available options can be found on [Sentry documentation](https://docs.sentry.io/error-reporting/configuration/?platform=browser).

### Levels Mapping

`SentryTransport` is using the npm logging levels by default (just like winston does) and mapping them to Sentry logging levels:

```typescript
export const DEFAULT_LEVELS_MAP: SentryLevelsMap = {
  error: Severity.Error,
  warn: Severity.Warning,
  info: Severity.Info,
  verbose: Severity.Info,
  debug: Severity.Debug,
  silly: Severity.Debug,
};
```

If you're using different logging levels, you can pass a custom map using the `levelsMap` option.

## Logging

### Simple message

```typescript
logger.info('Error message.');
```

### Error message

```typescript
logger.error(new Error('Error message'));
```

### Tags

You can [tag an event](https://docs.sentry.io/enriching-error-data/context/?platform=node#tagging-events) using the `tags` property:

```typescript
const tags = { module: 'users', language: 'english' };

logger.error('Error message.', { tags });
```

### User

You can [capture the user](https://docs.sentry.io/enriching-error-data/context/?platform=node#capturing-the-user) using the `user` property:

```typescript
const user = { username: 'test-user' };

logger.error('Error message.', { user });
```

The user object must have at least one of the following properties: `id`, `email`, `username` or `ip_address`. Otherwise it will be logged as extra data.

### Fingerprint

You can [set a fingerprint](https://docs.sentry.io/enriching-error-data/context/?platform=node#setting-the-fingerprint) using the `fingerprint` property.

```typescript
const fingerprint = ['{{ default }}', 'my-fingerprint'];

logger.error('Error message.', { fingerprint });
```

If the `fingerprint` is not an array it will be converted to one.

```typescript
const fingerprint = 'my-fingerprint'; // it'll be converted to ['my-fingerprint'];

logger.error('Error message.', { fingerprint });
```

### Extra data

Any other data which is not named as `tags`, `user` or `fingerprint` will be logged as [extra data](https://docs.sentry.io/enriching-error-data/context/?platform=node#extra-context).

```typescript
logger.error('Error message.', { url: '/users', input: 'some-input' });
```

## License

This project is [MIT Licensed](LICENSE).

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