otlp-logger's Introduction

otlp-logger

Sends logs in the OpenTelemetry Log Data Model to an OTLP logs collector.

Install

npm i otlp-logger

Configuration

Protocol

can be set to http/protobuf, grpc, http or console by using

env var OTEL_EXPORTER_OTLP_PROTOCOL
env var OTEL_EXPORTER_OTLP_LOGS_PROTOCOL
setting the exporterProtocol option

Settings configured programmatically take precedence over environment variables. Per-signal environment variables take precedence over non-per-signal environment variables. This principle applies to all the configurations in this module.

If no protocol is specified, http/protobuf is used as a default.

Exporter settings

Collector URL

Set either of the following environment variables: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_EXPORTER_OTLP_ENDPOINT

Protocol-specific exporter configuration

Processor-specific configuration

If batch log processor is selected (is default), it can be configured using env vars described in the OpenTelemetry specification

Options

When using the transport, the following options can be used to configure the transport programmatically:

loggerName: name to be used by the OpenTelemetry logger
serviceVersion: version to be used by the OpenTelemetry logger
resourceAttributes: Object containing resource attributes. Optional
logRecordProcessorOptions: a single object or an array of objects specifying the LogProcessor and LogExporter types and constructor params. Optional

Usage

Minimalistic example

Make sure you have access to an OTEL collector.

To start quickly, create a minimal configuration for OTEL collector in the otel-collector-config.yaml file:

receivers:
  otlp:
    protocols:
      grpc:

exporters:
  file:
    path: ./etc/test-logs/otlp-logs.log
    flush_interval: 1

  logging:
    verbosity: basic
  
processors:
  batch:

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: []
      exporters: [logging, file]

The collector can then be ran with:

docker run --volume=$(pwd)/otel-collector-config.yaml:/etc/otel-collector-config.yaml:rw --volume=/tmp/test-logs:/etc/test-logs:rw -p 4317:4317 -d otel/opentelemetry-collector-contrib:0.103.1 --config=/etc/otel-collector-config.yaml

Create an index.js file containing

const { getOtlpLogger } = require('otlp-logger')

const logger = getOtlpLogger({
  loggerName: 'test',
  serviceVersion: '1.0.0'
})

logger.emit({
  severityNumber: 1,
  severityText: 'TRACE',
  body: 'test',
  timestamp: Date.now()
})

Run the service setting the OTEL_EXPORTER_OTLP_LOGS_ENDPOINT and OTEL_RESOURCE_ATTRIBUTES env vars

OTEL_EXPORTER_OTLP_LOGS_PROTOCOL='grpc' OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:4317 OTEL_RESOURCE_ATTRIBUTES="service.name=my-service,service.version=1.2.3" node index.js

License

MIT

otlp-logger's People

Contributors

Stargazers

Watchers

otlp-logger's Issues

Feature discussion: support for custom exporters

TL;DR What do you think of adding support for custom exporters?

Background

Using the ConsoleLogRecordExporter with pino-opentelemetry-transport, I noticed that the colorization doesn't work locally. This happens because the logger is in a worker thread and process.stdout is not a TTY.

I opened open-telemetry/opentelemetry-js#4524 to add an option to ConsoleLogRecordExporter that would force colorization. However, the OpenTelemetry team suggested implementing a custom exporter as they do not want to expand the API for ConsoleLogRecordExporter (which currently takes no options).

Ultimately, I will likely stick with my workaround of using process.env.FORCE_COLOR=1. But this is what got me thinking about otlp-logger supporting custom exporters.

Design

A custom exporter just needs to implement the LogRecordExporter interface. The API could look something like this:

const logger = getOtlpLogger({
  loggerName: 'my-app',
  resourceAttributes: {/* ... */},
  serviceVersion: '1.0.0',
  logRecordProcessorOptions: {
    recordProcessorType: 'batch',
    exporterOptions: {
      path: path.join(__dirname, 'my-exporter'), // or just 'name-of-custom-exporter-package'
      export: 'LogExporter', // optional, assumes default export when omitted
      options: {/* ... */} // optional
    }
  }
})

OTel deps as peerDeps

What are your thoughts on making the OTel dependencies peerDependencies so that they can be updated without waiting on an otlp-logger release?

API design question: exporter options key

Why is it that different keys are required to pass options to the different exporters? e.g. When exporterOptions.protocol is grpc, you must use exporterOptions.grpcExporterOptions and when exporterOptions.protocol is http, you must use exporterOptions.httpExporterOptions.

Why not just use exporterOptions.options for all of them? Is it simply because of the types? If so, are you open to a non-breaking PR to support exporterOptions.options properly typed with overrides?

Recommend Projects

vunovati / otlp-logger Goto Github PK