# otel-log

OpenTelemetry-compliant structured logging for Python. Produces JSON logs conforming to the [OTel Log Data Model](https://opentelemetry.io/docs/specs/otel/logs/data-model/) and optionally configures distributed tracing from a single call.

## Installation

```bash
# Logging only (lightweight — only opentelemetry-api required)
pip install otel-log

# Logging + tracing
pip install otel-log[tracing]
```

## Quick Start

```python
import otel_log

result = otel_log.setup("my-service", version="1.0.0")

import logging
logging.info("Hello world")
# => {"Timestamp":"...","SeverityText":"INFO","SeverityNumber":9,"Body":"Hello world","Resource":{"service.name":"my-service","service.version":"1.0.0"}}

result.shutdown()
```

## With Tracing

```python
import otel_log

result = otel_log.setup("my-service", endpoint="localhost:4317")

with result.tracer.start_as_current_span("my-operation"):
    logging.info("Inside a span")
    # TraceId, SpanId, TraceFlags auto-injected into the JSON output
```

## Advanced Usage

For auto-instrumentors, custom exporters, or fine-grained configuration:

```python
from otel_log import OTelInitializer, ResourceConfig, InstrumentationConfig

result = OTelInitializer.initialize(
    resource_config=ResourceConfig(
        service_name="my-service",
        service_version="1.0.0",
        deployment_environment="production",
        custom_attributes={"cloud.region": "us-east-1"},
    ),
    instrumentation_config=InstrumentationConfig(
        endpoint="localhost:4317",
        protocol="grpc",
    ),
)
```

## Environment Variables

| Variable | Description |
|---|---|
| `OTEL_SERVICE_NAME` | Service name (overrides config) |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP trace exporter endpoint |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | OTLP log exporter endpoint |
| `OTEL_RESOURCE_ATTRIBUTES` | Comma-separated key=value resource attributes |

## Output Format

All logs conform to the shared JSON schema:

```json
{
  "Timestamp": "2026-03-22T12:00:00.000000Z",
  "SeverityText": "INFO",
  "SeverityNumber": 9,
  "Body": "User logged in",
  "Resource": {"service.name": "my-service"},
  "TraceId": "0af7651916cd43dd8448eb211c80319c",
  "SpanId": "b7ad6b7169203331",
  "TraceFlags": "01"
}
```

## License

Proprietary. All rights reserved.
