Metadata-Version: 2.4
Name: otel-log
Version: 0.3.0
Summary: OpenTelemetry Standard Log Format library for Python
License-Expression: MIT
Keywords: opentelemetry,otel,logging,structured-logging,observability,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: opentelemetry-api>=1.20.0
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "otel"
Provides-Extra: tracing
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "tracing"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == "tracing"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: jsonschema>=4.0; extra == "dev"

# 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

MIT
