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

import { createOTLPDrain } from 'evlog/otlp'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog: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

These follow the OpenTelemetry exporter specification, so a deployment that already configures an OTel SDK through the environment needs no evlog-specific 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:

spanId is the span of the request that produced the event. The TraceContext enricher records the caller's span from an incoming traceparent as parentSpanId, which is sent as a log attribute, so set spanId from your tracer's active span to link the record to the server span.

Attribute values keep their type: integers are sent as intValue, other finite numbers as doubleValue, booleans as boolValue, and arrays whose elements share one primitive type as arrayValue. In the json shape, nested plain objects are sent as kvlistValue. Anything else is serialized to a stringValue. A traceId or spanId that is not valid W3C hex, or is all zeros, stays an ordinary attribute.

Every field of the wide event is sent as an OTLP record field, a resource attribute, or a log attribute. null and undefined are omitted rather than transmitted. Both shapes drop them at every level, so a nested { user: { id: null } } has no user.id attribute in compact and no id entry in the json key-value list.

Record Shape

recordShape controls how the record carries the event. The default is json.

{
  "body": { "stringValue": "{\"timestamp\":\"…\",\"method\":\"POST\",\"user\":{\"id\":\"usr_123\"}}" },
  "attributes": [
    { "key": "method", "value": { "stringValue": "POST" } },
    { "key": "user", "value": { "kvlistValue": { "values": [
      { "key": "id", "value": { "stringValue": "usr_123" } },
      { "key": "plan", "value": { "stringValue": "premium" } }
    ] } } }
  ]
}

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

compact is worth switching to when your backend charges by ingested volume or facets on attributes:

• The body is a one-line summary: POST /api/checkout (500), falling back to the service name, instead of the whole event repeated next to the attributes. Backends that cluster messages into templates can only do so with a stable body.
• Nested fields become dotted attributes, so each leaf is its own facet:
  server/api/checkout.post.ts

  const drain = createOTLPDrain({ recordShape: 'compact' })
  
  log.set({ user: { id: 'usr_123', plan: 'premium' } })
  // → user.id, user.plan
  

Only plain objects are walked. Arrays are sent as a single attribute, an arrayValue when their elements share one primitive type and a JSON string otherwise. Indexing them, as 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. The same goes for anything else that is not a plain object, such as a Date. An empty object stays a single {} attribute rather than disappearing.

Semantic Conventions

With semanticConventions: true, each record also carries the OpenTelemetry semantic convention names for the fields evlog knows, so backends with built-in HTTP, error, and GenAI views pick them up. The evlog names stay, so existing queries keep working.

A field is mapped only when it has the type the convention requires, and an attribute the event already sets under that name is not overwritten. The resource also gets deployment.environment.name. The option becomes the default in the next major.

Protobuf

With protocol: 'http/protobuf', the adapter sends the same request as binary protobuf with Content-Type: application/x-protobuf. Use it for collectors and gateways that only accept protobuf, or to shrink the payload. The encoder ships with evlog, has no dependencies, and is only loaded when this protocol is selected, so evlog/otlp stays the same size for JSON users.

const drain = createOTLPDrain({
  endpoint: 'http://localhost:4318',
  protocol: 'http/protobuf',
  compression: 'gzip',
})

To encode a request yourself, evlog/otlp/protobuf exports encodeOTLPLogsRequest().

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). For a protobuf-only receiver, set protocol: 'http/protobuf'
• 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