Metadata-Version: 2.4
Name: trace0-lambda-otel-logger
Version: 1.0.6
Summary: OpenTelemetry-based logger for AWS Lambda Python functions
Author: Trace0
License-Expression: MIT
Project-URL: Repository, https://github.com/Trace0-HQ/trace0-lambda-python-otel-logger
Keywords: opentelemetry,otel,lambda,python,logging,observability,trace0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opentelemetry-api>=1.20.0
Dynamic: license-file

# trace0-lambda-otel-logger

OpenTelemetry-based logger for AWS Lambda Python functions.

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

> See the [Background](#background) section for more details on why this library is needed.

## How it works

```
logging.info() 
  → Trace0LogHandler (logging.Handler bridge)
    → BatchLogProcessor (buffers during invocation)
      → OTLPJsonLogExporter (POST to Trace0 ingest endpoint)
```

Based on the [OpenTelemetry Logs API specification](https://opentelemetry.io/docs/specs/otel/logs/api/).

## Installation

```bash
pip install trace0-lambda-otel-logger
```

## Usage

**1. Add as the first import in your Lambda handler module:**

```python
import trace0_lambda_otel_logger  # must be first
from trace0_lambda_otel_logger import flush
```

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

```python
import logging

logger = logging.getLogger(__name__)

def handler(event, context):
    try:
        return your_handler(event, context)
    finally:
        flush()  # always flush before Lambda freezes
```

**3. Set environment variables:**

```bash
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 `logging` calls required.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Yes | — | Your Trace0 ingest endpoint |
| `OTEL_EXPORTER_OTLP_HEADERS` | Yes | — | Your Trace0 API key |

## Log Record Format

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

```json
{
  "timeUnixNano": "1234567890000000000",
  "severityNumber": 9,
  "severityText": "INFO",
  "body": { "stringValue": "User created" },
  "attributes": [
    { "key": "logger.name", "value": { "stringValue": "app.users" } },
    { "key": "code.function", "value": { "stringValue": "create_user" } },
    { "key": "code.lineno", "value": { "intValue": 42 } }
  ],
  "traceId": "abc123...",
  "spanId": "def456..."
}
```

## Requirements

- Python >= 3.11
- AWS Lambda with the [OpenTelemetry Lambda Layer](https://github.com/open-telemetry/opentelemetry-lambda) attached (for trace context)

## Background

The OpenTelemetry Lambda Layer does not include the `opentelemetry-instrumentation-logging` library. Adding it as a dependency pulls in `opentelemetry-sdk` and `opentelemetry-instrumentation` as transitive dependencies — both of which are already bundled in the layer — resulting in duplicate packages and potential version conflicts.

`trace0-lambda-otel-logger` solves this problem by installing a `logging.Handler` on the root logger that automatically injects 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, while only depending on `opentelemetry-api`, which is already present in the layer, making it safe to install alongside it.
