@trace0/lambda-otel-logger

OpenTelemetry-based logger for AWS Lambda Node.js functions.

Automatically captures all console log output, injects OTel trace context (traceId, spanId), and exports logs as OTLP JSON to the Trace0 ingest endpoint.

See the Background section for more details on why this library is needed.

How it works

console.log() 
  → ConsoleAppender (captures + creates OTel LogRecord)
    → BatchLogProcessor (buffers during invocation)
      → OTLPJsonLogExporter (POST to Trace0 ingest endpoint)

Based on the OpenTelemetry Logs API specification.

Installation

npm install @trace0/lambda-otel-logger

Usage

1. Add as the first import in your Lambda handler entry point:

import '@trace0/lambda-otel-logger'; // must be first
import { flush } from '@trace0/lambda-otel-logger';

2. Call flush() at the end of every invocation:

export const handler = async (event: APIGatewayProxyEvent, context: Context) => {
  try {
    return await yourHandler(event, context);
  } finally {
    await flush(); // always flush before Lambda freezes
  }
};

3. Set environment variables:

OTEL_EXPORTER_OTLP_ENDPOINT=https://app.trace0hq.com/api
OTEL_EXPORTER_OTLP_HEADERS=X-API-KEY=YOUR_TRACE0_ENV_API_KEY

That's it. No changes to your existing console.log calls required.

Environment Variables

Log Formats

The library handles all common logging patterns without any code changes:

// JSON string — message extracted as body, remaining fields as attributes
console.log(JSON.stringify({ message: 'User created', userId: '123' }));

// Plain string
console.log('Hello world');

// Multiple args
console.log('User created with Id:', userId);

// All severity levels supported
console.debug('Debug message');
console.info('Info message');
console.warn('Warning message');
console.error('Error message');

Log Record Format

Each log record is exported as OTLP JSON with the following fields:

{
  "timeUnixNano": "1234567890000000000",
  "severityNumber": 9,
  "severityText": "INFO",
  "body": { "stringValue": "User created" },
  "attributes": [
    { "key": "userId", "value": { "stringValue": "123" } }
  ],
  "traceId": "abc123...",
  "spanId": "def456..."
}

Requirements

• Node.js >= 18
• AWS Lambda with the OpenTelemetry Lambda Layer attached (for trace context).

Background

To correlate logs with traces in Trace0, the @trace0/lambda-otel-logger library must be installed in your Lambda function. This is necessary because the OpenTelemetry Lambda layer for Node.js does not automatically bridge console output into the OTel Logs pipeline.

The official solution for log bridging in OpenTelemetry JS is the Logs Bridge API, however this package is currently alpha software under active development. Until it is stabilised and merged into the core @opentelemetry/api package, it is not suitable for production use.

The @trace0/lambda-otel-logger library solves this gap by wrapping the global console methods to automatically inject the active OTel span's traceId and spanId into every log record, and exporting them directly to the Trace0 ingest endpoint. This enables full log-trace correlation with minimal integration effort.