README.md

OpenTelemetry instrumentation for bunyan

This module provides automatic instrumentation of the bunyan module to inject trace-context into Bunyan log records (log correlation) and to send Bunyan 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-bunyan

Supported Versions

• bunyan versions >=1.0.0 <2

Usage

const { NodeSDK, tracing, logs, api } = require('@opentelemetry/sdk-node');
const { BunyanInstrumentation } = require('@opentelemetry/instrumentation-bunyan');
const sdk = new NodeSDK({
  spanProcessor: new tracing.SimpleSpanProcessor(new tracing.ConsoleSpanExporter()),
  logRecordProcessor: new logs.SimpleLogRecordProcessor(new logs.ConsoleLogRecordExporter()),
  instrumentations: [
    new BunyanInstrumentation({
      // See below for Bunyan instrumentation options.
    }),
  ]
})
sdk.start();

const bunyan = require('bunyan');
const logger = bunyan.createLogger({name: 'example'});

logger.info('hi');
// 1. Log records will be sent to the SDK-registered log record processor, if any.
//    This is called "log sending".

const tracer = api.trace.getTracer('example');
tracer.startActiveSpan('manual-span', span => {
  logger.info('in a span');
  // 2. Fields identifying the current span will be added to log records:
  //    {"name":"example",...,"msg":"in a span","trace_id":"d61b4e4af1032e0aae279d12f3ab0159","span_id":"d140da862204f2a2","trace_flags":"01"}
  //    This is called "log correlation".
})

Log sending

Creation of a Bunyan Logger will automatically add a Bunyan stream that sends log records to the OpenTelemetry Logs SDK. 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 added stream will be a no-op.

Log sending can be disabled with the disableLogSending: true option.

Log correlation

Bunyan 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'];
  }

When no span context is active or the span context is invalid, injection is skipped. Log injection can be disabled with the disableLogCorrelation: true option.

Bunyan 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 Bunnyan 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.

Using OpenTelemetryBunyanStream without instrumentation

This package exports the Bunyan stream class that is used to send records to the OpenTelemetry Logs SDK. It can be used directly when configuring a Bunyan logger if one is not using the BunyanInstrumentation for whatever reason. For example:

const { OpenTelemetryBunyanStream } = require('@opentelemetry/instrumentation-bunyan');
const bunyan = require('bunyan');

// You must register an OpenTelemetry LoggerProvider, otherwise log records will
// be sent to a no-op implementation. "examples/telemetry.js" shows one way
// to configure one.
// ...

const logger = bunyan.createLogger({
  name: 'my-logger',
  streams: [
    {
      type: 'raw',
      stream: new OpenTelemetryBunyanStream()
    }
  ],
});

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.