# @opentelemetry/instrumentation-winston

> OpenTelemetry instrumentation for `winston` logger

Latest version **0.66.0** (published 2026-08-31) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @opentelemetry/instrumentation-winston
pnpm add @opentelemetry/instrumentation-winston
yarn add @opentelemetry/instrumentation-winston
bun add @opentelemetry/instrumentation-winston
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.66.0 |
| Published | 2026-08-31 |
| First published | 2021-04-26 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | ^18.19.0 \|\| >=20.6.0 |
| Dependencies | 2 |
| Unpacked size | 58.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 924 |
| Author | OpenTelemetry Authors |
| Maintainers | dyladan, pichlermarc, overbalance, npmjs-account, trentm, martinkuba |
| Keywords | instrumentation, logging, nodejs, opentelemetry, profiling, tracing, winston |

## Links

- npm: https://www.npmjs.com/package/@opentelemetry/instrumentation-winston
- Repository: https://github.com/open-telemetry/opentelemetry-js-contrib
- Homepage: https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-winston#readme
- Issues: https://github.com/open-telemetry/opentelemetry-js-contrib/issues
- npm.io page: https://npm.io/package/@opentelemetry/instrumentation-winston

## Dependencies (2)

- [@opentelemetry/api-logs](https://npm.io/package/@opentelemetry/api-logs.md) ^0.222.0
- [@opentelemetry/instrumentation](https://npm.io/package/@opentelemetry/instrumentation.md) ^0.222.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

- 0.66.0 (latest) — 2026-08-31
- 0.65.0 — 2026-07-23
- 0.64.0 — 2026-07-03
- 0.63.0 — 2026-06-11
- 0.62.0 — 2026-05-13
- 0.61.0 — 2026-05-06
- 0.60.0 — 2026-04-29
- 0.59.0 — 2026-04-17
- 0.58.0 — 2026-03-26
- 0.57.0 — 2026-03-04
- 0.56.0 — 2026-02-17
- 0.55.0 — 2026-01-22
- 0.54.0 — 2026-01-15
- 0.53.0 — 2025-11-06
- 0.52.0 — 2025-10-21
- … 48 more at https://npm.io/package/@opentelemetry/instrumentation-winston/versions

## README

# OpenTelemetry instrumentation for winston

[![NPM Published Version][npm-img]][npm-url]
[![Apache License][license-image]][license-image]

This module provides automatic instrumentation of the [`winston`](https://www.npmjs.com/package/winston) module to inject trace-context into Winston log records (log correlation) and to send Winston logging to the OpenTelemetry Logging SDK (log sending).

If total installation size is not constrained, it is recommended to use the [`@opentelemetry/auto-instrumentations-node`](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) bundle with [@opentelemetry/sdk-node](https://www.npmjs.com/package/@opentelemetry/sdk-node) for the most seamless instrumentation experience.

Compatible with OpenTelemetry JS API and SDK `1.0+`.

## Installation

```bash
npm install --save @opentelemetry/instrumentation-winston
```

### Supported Versions

- [`winston`](https://www.npmjs.com/package/winston) versions `>=1.0.0 <4`

Log sending: [`winston`](https://www.npmjs.com/package/winston) versions `>=3.0.0 <4`

## Usage

```js
const { SimpleSpanProcessor, ConsoleSpanExporter } = require('@opentelemetry/sdk-trace');
const { SimpleLogRecordProcessor, ConsoleLogRecordExporter } = require('@opentelemetry/sdk-logs');
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { WinstonInstrumentation } = require('@opentelemetry/instrumentation-winston');

const sdk = new NodeSDK({
  spanProcessors: [
    new SimpleSpanProcessor(new ConsoleSpanExporter()),
  ],
  logRecordProcessors: [
    new SimpleLogRecordProcessor({ exporter: new ConsoleLogRecordExporter() }),
  ],
  instrumentations: [
    new WinstonInstrumentation({
      // See below for Winston instrumentation options.
    }),
  ]
});
sdk.start();
process.once('beforeExit', async () => { await sdk.shutdown(); });

const winston = require('winston');
const logger = winston.createLogger({
  transports: [new winston.transports.Console()],
})
logger.info('foobar');
// {"message":"foobar","trace_id":"e21c7a95fff34e04f77c7bd518779621","span_id":"b7589a981fde09f4","trace_flags":"01", ...}
```

### Winston instrumentation options

| Option                  | Type              | Description                                                                                                                                                |
|-------------------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `disableLogSending`     | `boolean`         | Whether to disable [log sending](#log-sending). Default `false`.                                                                                           |
| `logSeverity`           | `SeverityNumber`  | Control severity level for [log sending](#log-sending). Default `SeverityNumber.UNSPECIFIED`, it will use Winston Logger's current level when unspecified. |
| `disableLogCorrelation` | `boolean`         | Whether to disable [log correlation](#log-correlation). Default `false`.                                                                                   |
| `logHook`               | `LogHookFunction` | An option hook to inject additional context to a log record after trace-context has been added. This requires `disableLogCorrelation` to be false.         |

### Log sending

Winston Logger will automatically send log records to the OpenTelemetry Logs SDK if not explicitly disabled in config and @opentelemetry/winston-transport npm package is installed in the project. The OpenTelemetry SDK can be configured to handle those records, for example, sending them on to an OpenTelemetry collector for log archiving and processing. The example above shows a minimal configuration that emits OpenTelemetry log records to the console for debugging.

When a Winston log call is made in an active span, the instrumentation preserves
that context for log sending even if Winston processes the transport
asynchronously. The OpenTelemetry LogRecord uses its native trace context fields;
the `trace_id`, `span_id`, and `trace_flags` fields added for log correlation are
not duplicated as LogRecord attributes.

If the OpenTelemetry SDK is not configured with a Logger provider, then this will be a no-op.

Log sending can be disabled with the `disableLogSending: true` option. Log sending is only available for Winston version 3 and later.

```bash
npm install --save @opentelemetry/winston-transport
```

### Log correlation

Winston logger calls in the context of a tracing span will have fields
identifying the span added to the log record. This allows
[correlating](https://opentelemetry.io/docs/specs/otel/logs/#log-correlation)
log records with tracing data. The added fields are
([spec](https://opentelemetry.io/docs/specs/otel/compatibility/logging_trace_context/)):

- `trace_id`
- `span_id`
- `trace_flags`

After adding these fields, the optional `logHook` is called to allow injecting additional fields. For example:

```js
logHook: (span, record) => {
  record['resource.service.name'] = provider.resource.attributes['service.name'];
}
```

Log injection can be disabled with the `disableLogCorrelation: true` option.

### Using OpenTelemetryTransportV3 without instrumentation

[@opentelemetry/winston-transport](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/winston-transport) package exports the Winston transport class that is used to send records to the
OpenTelemetry Logs SDK. It can be used directly when configuring a Winston logger.
For example:

```js
const { SimpleSpanProcessor, ConsoleSpanExporter } = require('@opentelemetry/sdk-trace');
const { SimpleLogRecordProcessor, ConsoleLogRecordExporter } = require('@opentelemetry/sdk-logs');
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OpenTelemetryTransportV3 } = require('@opentelemetry/winston-transport');
const winston = require('winston');

const sdk = new NodeSDK({
  spanProcessors: [
    new SimpleSpanProcessor(new ConsoleSpanExporter()),
  ],
  logRecordProcessors: [
    new SimpleLogRecordProcessor({ exporter: new ConsoleLogRecordExporter() }),
  ],
});
sdk.start();
process.once('beforeExit', async () => { await sdk.shutdown(); });

const logger = winston.createLogger({
  level: 'info',
  transports: [
    new winston.transports.Console(),
    new OpenTelemetryTransportV3()
  ]
});
```

> [!IMPORTANT]
> Logs will be **duplicated** if `OpenTelemetryTransportV3` is explicitly added as a Winston logger transport **and** `@opentelemetry/instrumentation-winston` is active with the [Log sending](#log-sending) feature (the default). If you are both using `OpenTelemetryTransportV3` and instrumentation-winston, be sure to either disable instrumentation-winston completely, or disable its Log sending feature (`disableLogSending: false`). For example:
>
> ```js
> const { WinstonInstrumentation } = require('@opentelemetry/instrumentation-winston');
>
> const sdk = new NodeSDK({
>   instrumentations: [
>     new WinstonInstrumentation({ disableLogSending: true })
>   ]
> });
> // ...
>
> const { OpenTelemetryTransportV3 } = require('@opentelemetry/winston-transport');
> // Winston import must be after the WinstonInstrumentation creation
> const winston = require('winston');
>
> // ...
> const logger = winston.createLogger(...);
> ```

## Semantic Conventions

This package does not currently generate any attributes from semantic conventions.

## Useful links

- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
- For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>
- For help or feedback on this project, join us in [GitHub Discussions][discussions-url]

## License

Apache 2.0 - See [LICENSE][license-url] for more information.

[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions
[license-url]: https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/LICENSE
[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
[npm-url]: https://www.npmjs.com/package/@opentelemetry/instrumentation-winston
[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Finstrumentation-winston.svg

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