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 still sent — as an OTLP record field (timestamp, traceId, spanId), a resource attribute (service, environment, version, region, commitHash), or a log attribute for everything else. Attributes are where backends filter, facet, and scrub PII; keeping the body short also lets them cluster messages into templates, which a body containing the whole serialized event never does.

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