OTLP Adapter

The OTLP (OpenTelemetry Protocol) adapter sends logs in the standard OpenTelemetry format. This works with any OTLP-compatible backend including:

• Grafana Cloud (Loki)
• Datadog
• Honeycomb
• Jaeger
• Splunk
• New Relic
• Self-hosted OpenTelemetry Collector
• HyperDX

Installation

The OTLP adapter comes bundled with evlog:

import { createOTLPDrain } from 'evlog/otlp'

Quick Start

1. Set your OTLP endpoint

OTLP_ENDPOINT=http://localhost:4318

2. Wire the drain to your framework

// server/plugins/evlog-drain.ts
import { createOTLPDrain } from 'evlog/otlp'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createOTLPDrain())
})

// lib/evlog.ts
import { createEvlog } from 'evlog/next'
import { createOTLPDrain } from 'evlog/otlp'

export const { withEvlog, useLogger, log, createError } = createEvlog({
  service: 'my-app',
  drain: createOTLPDrain(),
})

import { createOTLPDrain } from 'evlog/otlp'

app.use(evlog({ drain: createOTLPDrain() }))

import { createOTLPDrain } from 'evlog/otlp'

app.use(evlog({ drain: createOTLPDrain() }))

import { createOTLPDrain } from 'evlog/otlp'

await app.register(evlog, { drain: createOTLPDrain() })

import { createOTLPDrain } from 'evlog/otlp'

app.use(evlog({ drain: createOTLPDrain() }))

import { createOTLPDrain } from 'evlog/otlp'

EvlogModule.forRoot({ drain: createOTLPDrain() })

import { createOTLPDrain } from 'evlog/otlp'

initLogger({ drain: createOTLPDrain() })

Configuration

The adapter reads configuration from multiple sources (highest priority first):

1. Overrides passed to createOTLPDrain()
2. Runtime config at runtimeConfig.otlp (Nuxt/Nitro only)
3. Environment variables

Environment Variables

Runtime Config (Nuxt only)

export default defineNuxtConfig({
  runtimeConfig: {
    otlp: {
      endpoint: '', // Set via OTLP_ENDPOINT (or OTEL_EXPORTER_OTLP_ENDPOINT)
    },
  },
})

Override Options

const drain = createOTLPDrain({
  endpoint: 'http://localhost:4318',
  serviceName: 'my-api',
  headers: {
    'Authorization': 'Bearer xxx',
  },
  resourceAttributes: {
    'deployment.environment': 'staging',
  },
})

Full Configuration Reference

Deployment

OTLP is a protocol, not a product — the same adapter talks to a collector you run yourself and to a managed gateway. Only the endpoint and headers change.

Self-hosted

Run an OpenTelemetry Collector and point evlog at it. Nothing else to configure:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    logs:
      receivers: [otlp]
      exporters: [debug]

docker run --rm -p 4318:4318 \
  -v $(pwd)/otel-collector.yaml:/etc/otelcol/config.yaml \
  otel/opentelemetry-collector:latest

OTLP_ENDPOINT=http://localhost:4318

From there the collector fans out wherever you want — Loki, ClickHouse, Elasticsearch, a managed backend, or several at once. That indirection is the reason to pick OTLP over a direct adapter.

Managed gateways

Same adapter, a credentialed endpoint:

OTLP_ENDPOINT=https://otlp-gateway-prod-us-central-0.grafana.net/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic%20base64-encoded-credentials

OTLP_ENDPOINT=https://http-intake.logs.datadoghq.com
OTLP_HEADERS=DD-API-KEY=your-api-key

OTLP_ENDPOINT=https://api.honeycomb.io
OTLP_HEADERS=x-honeycomb-team=your-api-key

OTLP Log Format

evlog maps wide events to the OTLP log format:

Log Record Body

The body is a one-line summary of the request — POST /api/checkout (500) — falling back to the service name when the event has no request shape:

{
  "severityText": "ERROR",
  "body": { "stringValue": "POST /api/checkout (500)" },
  "attributes": [
    { "key": "method", "value": { "stringValue": "POST" } },
    { "key": "path", "value": { "stringValue": "/api/checkout" } },
    { "key": "status", "value": { "intValue": "500" } },
    { "key": "user.id", "value": { "stringValue": "usr_123" } },
    { "key": "user.plan", "value": { "stringValue": "premium" } }
  ]
}

Nothing is dropped: every field of the wide event is sent as an attribute, which is where backends filter, facet, and scrub PII. Keeping the body short also lets them cluster messages into templates — a body containing the whole serialized event is unique on every request, so it clusters into nothing.

Nested Fields

Nested objects are flattened into dotted attribute keys, so each leaf is its own facet:

log.set({ user: { id: 'usr_123', plan: 'premium' } })
// → user.id, user.plan

Arrays stay serialized as a single JSON string. Indexing them (ai.tools.0.name) would turn a list into an unbounded set of distinct attribute keys, which most backends charge for and none can chart. Date values and class instances are serialized whole for the same reason — they have no useful own keys to flatten.

Severity Mapping

Troubleshooting

Missing endpoint error

[evlog/otlp] Missing endpoint. Set OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT

Make sure your endpoint environment variable is set and the server was restarted.

401 Unauthorized

Your authentication headers may be missing or incorrect. Check:

1. The OTEL_EXPORTER_OTLP_HEADERS format is correct
2. Credentials are valid and not expired
3. The endpoint URL is correct

404 Not Found

The adapter sends to /v1/logs. Make sure your endpoint:

• Supports OTLP HTTP (not gRPC)
• Is the base URL without /v1/logs suffix

Logs not appearing

1. Check the server console for [evlog/otlp] error messages
2. Test with a local collector first to verify the format
3. Check your backend's ingestion delay (some have 1-2 minute delays)

Direct API Usage

For advanced use cases:

import { sendToOTLP, sendBatchToOTLP, toOTLPLogRecord } from 'evlog/otlp'

// Send a single event
await sendToOTLP(event, {
  endpoint: 'http://localhost:4318',
})

// Send multiple events
await sendBatchToOTLP(events, {
  endpoint: 'http://localhost:4318',
})

// Convert event to OTLP format (for inspection)
const otlpRecord = toOTLPLogRecord(event)

Next Steps

• Axiom Adapter - Send logs to Axiom
• PostHog Adapter - Send logs to PostHog
• Custom Adapters - Build your own adapter
• Best Practices - Security and production tips