@logtape/otel: LogTape OpenTelemetry Sink

This package provides an OpenTelemetry sink for LogTape. It allows you to send your LogTape logs to OpenTelemetry-compatible backends.

Installation

The package is available on JSR and npm.

deno add jsr:@logtape/otel # for Deno
npm  add     @logtape/otel # for npm
pnpm add     @logtape/otel # for pnpm
yarn add     @logtape/otel # for Yarn
bun  add     @logtape/otel # for Bun

Usage

The quickest way to get started is to use the getOpenTelemetrySink() function without any arguments:

import { configure } from "@logtape/logtape";
import { getOpenTelemetrySink } from "@logtape/otel";

await configure({
  sinks: {
    otel: getOpenTelemetrySink(),
  },
  loggers: [
    { category: [], sinks: ["otel"], lowestLevel: "debug" },
  ],
});

This will use the default OpenTelemetry configuration, which is to send logs to the OpenTelemetry collector running on localhost:4317 or respects the OTEL_* environment variables.

If you want to customize the OpenTelemetry configuration, you can specify options to the getOpenTelemetrySink() function:

import { configure } from "@logtape/logtape";
import { getOpenTelemetrySink } from "@logtape/otel";

await configure({
  sinks: {
    otel: getOpenTelemetrySink({
      serviceName: "my-service",
      otlpExporterConfig: {
        url: "https://my-otel-collector:4317",
        headers: { "x-api-key": "my-api-key" },
      },
    }),
  },
  loggers: [
    { category: [], sinks: ["otel"], lowestLevel: "debug" },
  ],
});

Or you can even pass an existing OpenTelemetry LoggerProvider instance:

import { configure } from "@logtape/logtape";
import { getOpenTelemetrySink } from "@logtape/otel";
import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
import {
  LoggerProvider,
  SimpleLogRecordProcessor,
} from "@opentelemetry/sdk-logs";

const exporter = new OTLPLogExporter({
  url: "https://my-otel-collector:4318/v1/logs",
  headers: { "x-api-key": "my-api-key" },
});
const loggerProvider = new LoggerProvider({
  processors: [new SimpleLogRecordProcessor(exporter)],
});

await configure({
  sinks: {
    otel: getOpenTelemetrySink({ loggerProvider }),
  },
  loggers: [
    { category: [], sinks: ["otel"], lowestLevel: "debug" },
  ],
});

For more information, see the OpenTelemetry sink documentation.
For API references, see the getOpenTelemetrySink() function and OpenTelemetrySinkOptions type.

Protocol selection

By default, the sink uses the http/json protocol to send logs to the OpenTelemetry collector. You can change the protocol by setting the OTEL_EXPORTER_OTLP_PROTOCOL or OTEL_EXPORTER_OTLP_LOGS_PROTOCOL environment variable:

# Use gRPC protocol (server environments only)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# Use HTTP/Protobuf protocol
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

# Use HTTP/JSON protocol (default)
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

The available protocols are:

• grpc: Uses gRPC transport. This is only available in server environments (Node.js, Deno, Bun) and not in browsers due to gRPC's HTTP/2 requirement.
• http/protobuf: Uses HTTP transport with Protocol Buffers encoding. Works in all environments.
• http/json: Uses HTTP transport with JSON encoding. Works in all environments. This is the default.

[!NOTE] When using gRPC protocol, make sure to use the correct port (typically 4317 for gRPC vs 4318 for HTTP).

No-op fallback

If no OTLP endpoint is configured (neither via options nor environment variables), the sink automatically falls back to a no-op logger that discards all log records. This prevents errors when running in environments where OpenTelemetry is not set up.

The sink checks for endpoints in the following order:

1. otlpExporterConfig.url option
2. OTEL_EXPORTER_OTLP_LOGS_ENDPOINT environment variable
3. OTEL_EXPORTER_OTLP_ENDPOINT environment variable

If none of these are set, the no-op fallback is used.

Diagnostic logging

If you want to log diagnostic messages from the OpenTelemetry sink itself, you can enable diagnostics: true in the sink options:

import { configure, getConsoleSink } from "@logtape/logtape";
import { getOpenTelemetrySink } from "@logtape/otel";

await configure({
  sinks: {
    otel: getOpenTelemetrySink({ diagnostics: true }),
    console: getConsoleSink(),
  },
  filters: {},
  loggers: [
    { category: ["logtape", "meta"], sinks: ["console"], level: "debug" },
    { category: [], sinks: ["otel"], level: "debug" },
  ],
});

This will log messages with the ["logtape", "meta", "otel"] category.

These messages are useful for debugging the configuration of the OpenTelemetry sink, but they can be verbose, so it's recommended to enable them only when needed.