otelio

Python OpenTelemetry + Loguru toolkit

A small, batteries-included OpenTelemetry + Loguru toolkit for Python services. Call init_otelio(...) once at startup and you get traces and logs that are automatically correlated by trace_id / span_id, exported over OTLP/gRPC or OTLP/HTTP (SigNoz, Grafana, Jaeger, any OTLP collector) or to Azure Application Insights — switchable with a single environment variable, no code changes.

Manual instrumentation, full control. otelio is not an auto-instrumentation library. Nothing is monkey-patched and no spans are created behind your back — you decide exactly what gets traced and logged via explicit calls (init_otelio, otel_span, logger.*).

Features

• One call to wire everything — init_otelio(...) sets up the tracer + logger providers, the Loguru bridge, and a clean-shutdown flush hook.
• Logs correlate to spans automatically — keep using Loguru; every record is stamped with the active trace_id / span_id and exported.
• Backend-agnostic — OTLP/gRPC, OTLP/HTTP, or Azure App Insights via the OTELIO_TARGET env var. Send traces and logs to the same backend, or split them across different backends (and OTLP collectors) per signal. Exporter SDKs are imported lazily, so you only install what you use.
• Cross-service tracing built in — W3C traceparent + baggage propagation helpers so one request shows up as a single connected trace across service boundaries.
• Tiny surface — eleven well-documented functions, nothing to configure in code.

Install

pip install python-otelio                # core + OTLP/gRPC and OTLP/HTTP exporters
pip install "python-otelio[azure]"       # also the Azure Application Insights exporter

Requires Python 3.10+. The distribution is named python-otelio on PyPI but imports as otelio (from otelio import ...).

Quick start

from otelio import init_otelio, otel_span, otel_set_attributes
from loguru import logger

# 1. Bootstrap once, at process start (before anything emits telemetry).
init_otelio(service_name="my-service", service_version="1.0.0")

# 2. Log with Loguru as usual — records are stamped with the active span.
logger.info("service started")

# 3. Wrap units of work in spans; exceptions are recorded and re-raised.
with otel_span("handle_request", attributes={"route": "/search"}):
    otel_set_attributes({"result.count": 12})

Configuration

All configuration is via environment variables.

# OTLP/gRPC collector (SigNoz, Grafana, Jaeger, ...)
export OTELIO_TARGET=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# OTLP/HTTP-protobuf collector (path /v1/traces, /v1/logs appended automatically)
export OTELIO_TARGET=otlp-http
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# Azure Application Insights
export OTELIO_TARGET=azure
export APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=...;IngestionEndpoint=..."
export OTELIO_ENVIRONMENT=production

# Split: traces to an OTLP collector, logs to Azure
export OTELIO_TRACE_TARGET=otlp
export OTELIO_LOG_TARGET=azure

# Split: traces and logs to two different OTLP collectors
export OTELIO_TARGET=otlp
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://tempo:4317
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://loki-otlp:4317

Required: set OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION=false when using otelio.

export OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION=false

Public API (from otelio import ...)

Context propagation across services

otelio carries the W3C traceparent + baggage headers automatically, so one request shows up as a single connected trace across service boundaries:

import httpx
from opentelemetry.trace import SpanKind
from otelio import otel_inject_headers, otel_context_from_headers, otel_span

# Outbound — inject context into the request headers
with otel_span("call_downstream", kind=SpanKind.CLIENT):
    headers = otel_inject_headers({"Authorization": token})
    resp = httpx.post(url, headers=headers, json=payload)

# Inbound — continue the caller's trace
ctx = otel_context_from_headers(request.headers)
with otel_span("serve_request", kind=SpanKind.SERVER, context=ctx):
    ...

Documentation

See the full usage guide for bootstrapping, spans, correlated logging, context propagation, baggage, and a complete FastAPI example.

License

MIT © code4mk