python-otel 0.1.0

Python library for easy OpenTelemetry logging setup that sends logs to an OTLP collector.

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

pip install python-otel

Using Poetry

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

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

from python_otel import setup_opentelemetry_logging

Complete Example

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:

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