python-otel 0.1.0
Python library for easy OpenTelemetry logging setup that sends logs to an OTLP collector.
Requires Python: <3.14,>=3.9

# python-otel

A Python library for easy OpenTelemetry logging setup that sends logs to an OTLP collector. This library provides a simple interface to configure OpenTelemetry logging handlers and integrate them with Python's standard `logging` module.

## Installation

### Using pip

```bash
pip install python-otel
```

### Using Poetry

```bash
poetry add python-otel
```

## Environment Variables

The library requires the following environment variables to be set before importing or calling the setup function:

### Required Environment Variables

#### `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`

- The OTLP collector endpoint URL where logs will be sent
- **Format**: Full URL with protocol and port
- **Examples**:
  - For gRPC: `http://localhost:4317`
  - For HTTP: `http://localhost:4318/v1/logs`
  - Remote collector: `http://otel-collector:4317`

#### `OTEL_RESOURCE_ATTRIBUTES`

- Resource attributes that identify your service in key-value format
- **Format**: Comma-separated key-value pairs: `key1=value1,key2=value2`
- **Required keys**:
  - `service.name`: Name of your service (e.g., "my-python-app")
  - `service.version`: Version of your service (e.g., "1.0.0")
- **Examples**:
  - `service.name=my-app,service.version=1.0.0`
  - `service.name=api-service,service.version=2.1.0,deployment.environment=production`

### Optional Environment Variables

#### `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`

- The protocol to use for sending logs to the collector
- **Values**: `grpc` or `http`
- **Default**: `grpc` (if not set)
- **Examples**:
  - `grpc` - Use gRPC protocol (faster, binary)
  - `http` - Use HTTP protocol (REST-based)

#### `OTEL_EXPORTER_OTLP_LOGS_INSECURE`

- Whether to use an insecure (non-TLS) connection
- **Values**: `true` or `false`
- **Default**: `true` (if not set)
- **Examples**:
  - `true` - Use insecure connection (no TLS/SSL)
  - `false` - Use secure connection (TLS/SSL required)

## Usage

### Basic Import and Setup

```python
import os
import logging
from python_otel import setup_opentelemetry_logging

# Set required environment variables
os.environ["OTEL_EXPORTER_OTLP_LOGS_ENDPOINT"] = "http://localhost:4317"
os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "service.name=my-app,service.version=1.0.0"

# Setup OpenTelemetry logging
setup_opentelemetry_logging()

# Use standard Python logging - logs will be sent to OTLP collector
logging.info("This log will be sent to OpenTelemetry collector")
logging.warning("This warning will also be captured")
logging.error("Errors are captured too")
```

### Import Syntax

```python
from python_otel import setup_opentelemetry_logging
```

### Complete Example

```python
import os
import logging
from python_otel import setup_opentelemetry_logging

# Configure environment variables
os.environ["OTEL_EXPORTER_OTLP_LOGS_ENDPOINT"] = "http://localhost:4317"
os.environ["OTEL_EXPORTER_OTLP_LOGS_PROTOCOL"] = "grpc"
os.environ["OTEL_EXPORTER_OTLP_LOGS_INSECURE"] = "true"
os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "service.name=my-service,service.version=1.0.0"

# Initialize OpenTelemetry logging
setup_opentelemetry_logging()

# Your application code
logger = logging.getLogger(__name__)
logger.info("Application started")
logger.warning("This is a warning")
logger.error("This is an error")
```

### Advanced Usage with Function Parameters

You can also override environment variables by passing parameters directly:

```python
from python_otel import setup_opentelemetry_logging
import logging

# Setup with custom parameters (overrides environment variables)
setup_opentelemetry_logging(
    service_name="my-custom-service",
    service_version="2.0.0",
    otel_endpoint="http://otel-collector:4317",
    use_grpc=True,
    insecure_connection=False,
    log_level_to_capture=logging.DEBUG
)

logging.info("Logging is configured")
```

## Function Reference

### `setup_opentelemetry_logging()`

Configures OpenTelemetry to send logs to OTLP collector.

**Parameters:**
- `service_name` (str, optional): Name of your service. Defaults to value from `OTEL_RESOURCE_ATTRIBUTES`.
- `service_version` (str, optional): Version of your service. Defaults to value from `OTEL_RESOURCE_ATTRIBUTES`.
- `otel_endpoint` (str, optional): OTLP collector endpoint. Defaults to `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`.
- `use_grpc` (bool, optional): Use gRPC (True) or HTTP (False). Defaults based on `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`.
- `insecure_connection` (bool, optional): Use insecure connection. Defaults to True.
- `additional_resource_attributes` (dict, optional): Additional resource attributes.
- `attach_to_root_logger` (bool, optional): Attach handler to root logger. Defaults to True.
- `log_level_to_capture` (int, optional): Minimum log level to capture. Defaults to `logging.INFO`.
- `auto_shutdown` (bool, optional): Auto-register shutdown function. Defaults to True.

**Returns:**
- `logging.Handler`: Configured OpenTelemetry handler.

## Requirements

- Python >= 3.9, < 3.14
- OpenTelemetry API >= 1.39.1, < 2.0.0
- OpenTelemetry SDK >= 1.39.1, < 2.0.0
- OpenTelemetry OTLP Exporter (gRPC) >= 1.39.1, < 2.0.0
- python-dotenv >= 0.9.9, < 0.10.0