What is @opentelemetry/instrumentation-winston?
@opentelemetry/instrumentation-winston is an npm package that provides automatic instrumentation for the Winston logging library, enabling the collection of telemetry data such as traces and metrics. This helps in monitoring and debugging applications by providing insights into the logging behavior.
What are @opentelemetry/instrumentation-winston's main functionalities?
Automatic Trace Context Injection
This feature automatically injects trace context into Winston log messages, allowing you to correlate logs with traces. The code sample demonstrates how to enable the instrumentation and create a Winston logger that includes trace context in its log messages.
const { WinstonInstrumentation } = require('@opentelemetry/instrumentation-winston');
const winston = require('winston');
const instrumentation = new WinstonInstrumentation();
instrumentation.enable();
const logger = winston.createLogger({
transports: [
new winston.transports.Console()
]
});
logger.info('This is an info message');
Custom Log Format with Trace Context
This feature allows you to customize the log format to include trace context information. The code sample shows how to create a custom log format that includes a timestamp and other metadata, which can be useful for detailed log analysis.
const { WinstonInstrumentation } = require('@opentelemetry/instrumentation-winston');
const winston = require('winston');
const instrumentation = new WinstonInstrumentation();
instrumentation.enable();
const logger = winston.createLogger({
format: winston.format.combine(
winston.format.timestamp(),
winston.format.printf(({ level, message, timestamp, ...meta }) => {
return `${timestamp} [${level}]: ${message} ${JSON.stringify(meta)}`;
})
),
transports: [
new winston.transports.Console()
]
});
logger.info('This is an info message');
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.
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
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();
const loggerProvider = new LoggerProvider();
loggerProvider.addLogRecordProcessor(
new SimpleLogRecordProcessor(new ConsoleLogRecordExporter())
);
logsAPI.logs.setGlobalLoggerProvider(loggerProvider);
registerInstrumentations({
instrumentations: [
new WinstonInstrumentation({
}),
],
});
const winston = require('winston');
const logger = winston.createLogger({
transports: [new winston.transports.Console()],
})
logger.info('foobar');
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');
const loggerProvider = new LoggerProvider();
loggerProvider.addLogRecordProcessor(
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 @opentelemetry/winston-transport
is added as a transport in winston
and @opentelemetry/instrumentation-winston
is configured with disableLogSending: false
.
Semantic Conventions
This package does not currently generate any attributes from semantic conventions.
Useful links
License
Apache 2.0 - See LICENSE for more information.