@opentelemetry/instrumentation-winston

OpenTelemetry instrumentation for winston

This module provides automatic instrumentation of the winston module to inject trace-context into Winston log records (log correlation) and to send Winston logging to the OpenTelemetry Logging SDK (log sending). It may be loaded using the @opentelemetry/sdk-trace-node package and is included in the @opentelemetry/auto-instrumentations-node bundle.

If total installation size is not constrained, it is recommended to use the @opentelemetry/auto-instrumentations-node bundle with @opentelemetry/sdk-node for the most seamless instrumentation experience.

Compatible with OpenTelemetry JS API and SDK 1.0+.

Installation

npm install --save @opentelemetry/instrumentation-winston

Supported Versions

• winston versions >=1.0.0 <4

Log sending: winston versions >=3.0.0 <4

Usage

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const logsAPI = require('@opentelemetry/api-logs');
const {
    LoggerProvider,
    SimpleLogRecordProcessor,
    ConsoleLogRecordExporter,
} = require('@opentelemetry/sdk-logs');
const { WinstonInstrumentation } = require('@opentelemetry/instrumentation-winston');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

const tracerProvider = new NodeTracerProvider();
tracerProvider.register();

// To start a logger, you first need to initialize the Logger provider.
// Add a processor to export log record.
const loggerProvider = new LoggerProvider({
  processors: [new SimpleLogRecordProcessor(new ConsoleLogRecordExporter())],
});
logsAPI.logs.setGlobalLoggerProvider(loggerProvider);

registerInstrumentations({
    instrumentations: [
        new WinstonInstrumentation({
            // See below for Winston instrumentation options.
        }),
    ],
});

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. Default false.
logSeverity	SeverityNumber	Control severity level for log sending. Default SeverityNumber.UNSPECIFIED, it will use Winston Logger's current level when unspecified.
disableLogCorrelation	boolean	Whether to disable 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.

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.

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 log records with tracing data. The added fields are (spec):

• trace_id
• span_id
• trace_flags

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

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 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:

const logsAPI = require('@opentelemetry/api-logs');
const {
    LoggerProvider,
    SimpleLogRecordProcessor,
    ConsoleLogRecordExporter,
} = require('@opentelemetry/sdk-logs');
const { OpenTelemetryTransportV3 } = require('@opentelemetry/winston-transport');
const winston = require('winston');


// To start a logger, you first need to initialize the Logger provider.
// Add a processor to export log record
const loggerProvider = new LoggerProvider({
  processors: [new SimpleLogRecordProcessor(new ConsoleLogRecordExporter())],
});
logsAPI.logs.setGlobalLoggerProvider(loggerProvider);

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 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:

const { WinstonInstrumentation } = require('@opentelemetry/instrumentation-winston');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
registerInstrumentations({
    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

License

Apache 2.0 - See LICENSE for more information.

Similar packages

Other packages similar to @opentelemetry/instrumentation-winston

winston

Winston is a popular logging library for Node.js that provides a simple and universal logging interface. While it does not provide automatic instrumentation for OpenTelemetry, it can be used in conjunction with other OpenTelemetry packages to achieve similar functionality.

@opentelemetry/instrumentation-pino

@opentelemetry/instrumentation-pino is an OpenTelemetry instrumentation package for the Pino logging library. It provides similar functionality to @opentelemetry/instrumentation-winston by automatically injecting trace context into log messages, but it is designed specifically for Pino instead of Winston.

bunyan

Bunyan is another logging library for Node.js that focuses on JSON log output. Like Winston, it does not provide built-in OpenTelemetry instrumentation, but it can be integrated with OpenTelemetry manually to achieve similar results.