winston-elasticsearch

The transformer converts Winston's log data into a shape optimized for Elasticsearch/Kibana.

Default Behavior: It generates a @timestamp and moves meta properties into a fields object.

Input Shape (logdata):

• timestamp (ISO string)
• level (string)
• message (string)
• meta (object)

Output Shape:

• @timestamp (ISO string)
• severity (string, from level)
• message (string)
• fields (object, from meta)

To use this transport, install both winston and winston-elasticsearch via npm:

npm install --save winston winston-elasticsearch

To link logs with APM traces, pass the APM client to the apm option in ElasticsearchTransport.

If you use a custom transformer, you must manually map the APM IDs to ensure Kibana can link them. Add this logic to your transformer:

if (logData.meta['transaction.id']) transformed.transaction = { id: logData.meta['transaction.id'] };
if (logData.meta['trace.id']) transformed.trace = { id: logData.meta['trace.id'] };
if (logData.meta['span.id']) transformed.span = { id: logData.meta['span.id'] };

If you provide an apm object in the transport options, the transport will automatically extract and attach APM trace information to every log entry.

It looks for currentTraceIds and maps them to the following fields in the log document:

• transaction.id $\rightarrow$ transaction.id
• trace.id $\rightarrow$ trace.id
• span.id $\rightarrow$ span.id

You can dynamically route logs to different indices by including an indexInterfix property in your log metadata.

If dataStream is false, the transport will use the pattern: {indexPrefix}-{indexInterfix}-{dateString}. If dataStream is true, it will use: {dataStreamName}-{indexInterfix}.

Note: The indexInterfix property is automatically deleted from the log entry before being sent to Elasticsearch to avoid polluting the document.

You can import ElasticsearchTransformer to extend the default transformation logic within your options.

const { ElasticsearchTransformer } = require('winston-elasticsearch');
const esTransportOpts = {
 transformer: (logData) => {
   const transformed = ElasticsearchTransformer(logData);
   transformed.fields.customField = 'customValue';
   return transformed;
 }
};
const esTransport = new ElasticsearchTransport(esTransportOpts);

Initialize ElasticsearchTransport with an options object and add it to a Winston logger.

Important: You must implement error handling for both the logger and the esTransport instance to catch and handle errors effectively.

const winston = require('winston');
const { ElasticsearchTransport } = require('winston-elasticsearch');

const esTransportOpts = {
  level: 'info'
};
const esTransport = new ElasticsearchTransport(esTransportOpts);
const logger = winston.createLogger({
  transports: [
    esTransport
  ]
});

// Compulsory error handling
logger.on('error', (error) => {
  console.error('Error in logger caught', error);
});
esTransport.on('error', (error) => {
  console.error('Error in logger caught', error);
});

You can force the transport to write its current buffer to Elasticsearch immediately by calling .flush() on the ElasticsearchTransport instance.

const esTransport = new ElasticsearchTransport(esTransportOpts);
esTransport.flush();

The ElasticsearchTransport class is a Winston transport that sends log entries to Elasticsearch. It supports buffering for performance, automatic index template management, and data stream support. You can provide your own @elastic/elasticsearch client or let the transport create one using clientOpts.

const winston = require('winston');
const { ElasticsearchTransport } = require('winston-elasticsearch');

const logger = winston.createLogger({
  transports: [
    new ElasticsearchTransport({
    // configuration options
    })
  ]
});

The ElasticsearchTransformer (exported as ElasticsearchTransformer) is the default function used to reshape log data. It extracts message, level, and timestamp from the Winston info object and moves all other properties into a meta object.

If useTransformer is set to true, the log entry sent to Elasticsearch will follow this structure:

{
  "message": "...",
  "level": "...",
  "timestamp": "...",
  "meta": { "key": "value" }
}

const { ElasticsearchTransformer } = require('winston-elasticsearch');

// Example of a custom transformer
const myTransformer = (logData) => {
  return {
    ...logData,
    custom_field: 'added_value'
  };
};

// Usage in transport
new ElasticsearchTransport({
  transformer: myTransformer,
  useTransformer: true
});