pino-opentelemetry-transport

pino-opentelemetry-transport is an official Pino transport that converts your application’s Pino log records into the OpenTelemetry Log Data Model and exports them to an OTLP logs collector. It bridges the gap between Pino’s fast structured logging and an OpenTelemetry observability backend, mapping Pino log levels to OTel severity numbers and forwarding attributes, timestamps, and message bodies without changing how you write logs.

Running in a Pino worker thread, the transport supports the http/protobuf, gRPC, and http OTLP protocols (plus a console exporter for debugging), configurable entirely through standard OpenTelemetry environment variables or programmatic options. This lets you route logs to collectors like the OpenTelemetry Collector, Grafana Loki, or any OTLP-compatible backend while keeping trace-context correlation intact.

What You Get

• A drop-in Pino transport target requiring no changes to your logging call sites
• Automatic mapping of Pino levels to OpenTelemetry severity numbers, with an override hook for custom levels
• Support for http/protobuf, gRPC, http, and console OTLP exporter protocols
• Configuration via standard OpenTelemetry environment variables or programmatic options
• Batch and simple log-record processors with resource attribute detection

Common Use Cases

• Sending structured Node.js application logs to an OpenTelemetry Collector
• Forwarding Pino logs to observability backends such as Grafana Loki via OTLP
• Correlating logs with distributed traces using OpenTelemetry context propagation
• Standardizing log export across services on the OpenTelemetry Log Data Model

Under The Hood

Architecture The transport entry point (lib/pino-opentelemetry-transport.js) is an async factory built on pino-abstract-transport that runs inside a Pino worker thread. It obtains an OTLP logger via getOtlpLogger, then iterates the incoming log stream and calls toOpenTelemetry on each record before emitting it, wiring a close() handler to shut the logger down cleanly. lib/opentelemetry-mapper.js performs the pure transformation from a Pino binding object to an OTel LogRecord, splitting out time, level, hostname, pid, and the message key while forwarding the remaining fields as attributes and resolving severityNumber from a configurable-then-default map. lib/otlp-logger-shim.js wires up the OpenTelemetry sdk-logs LoggerProvider, resource detectors, and the batch/simple processors plus the protocol-specific exporters.

Tech Stack Written in modern JavaScript (CommonJS) with generated TypeScript declaration files. It depends on the OpenTelemetry JS SDK family — @opentelemetry/api, api-logs, sdk-logs, resources, and the OTLP grpc/http/proto log exporters — alongside pino-abstract-transport, and declares Pino v10 as a peer dependency. Tooling includes ESLint (neostandard), the borp test runner with coverage checks, tsd for type tests, knip for dependency checks, and commitlint with conventional-commit enforcement.

Code Quality The codebase is small, focused, and well-documented with JSDoc typedefs on the public surface. A dedicated test suite lives under test/lib and test/types, using testcontainers to spin up a real OTLP collector for integration coverage and tsd for compile-time type assertions; the test script enforces linting, coverage thresholds, and dependency hygiene together. Error handling is handled by delegating shutdown/flush to the OpenTelemetry SDK processors, and naming is clear and consistent across the three modules.

API Design The public API is deliberately minimal: register the package as a Pino transport target and it works with zero code changes, while advanced behavior is tuned through standard OTEL_* environment variables or a small set of programmatic options (loggerName, serviceVersion, severityNumberMap, resourceAttributes, logRecordProcessorOptions). The README documents protocol selection, exporter configuration, and several runnable examples (minimalistic, trace-context, Grafana Loki, TypeScript), keeping onboarding boilerplate low for anyone already using Pino.