ko-observability (Python)

Org-wide OpenTelemetry bootstrap for Python services: one-call, idempotent init_otel for process startup, lazy get_tracer / get_meter accessors for library code that doesn't own process lifecycle, and a structlog processor (otel_bridge / make_otel_bridge) that stamps each log line with the active span's trace_id/span_id.

Install

pip install ko-observability

Optional extras, install alongside the base package as needed:

# Auto-instrument FastAPI request/response spans
pip install "ko-observability[fastapi]"

# Auto-instrument outbound httpx calls
pip install "ko-observability[httpx]"

# Auto-instrument the Elasticsearch client
pip install "ko-observability[elasticsearch]"

# Read your own service's telemetry back out (admin-panel style queries)
pip install "ko-observability[query]"

Quick start

from ko_observability import init_otel, get_tracer

init_otel(service_name="my-service", service_namespace="nexora")

tracer = get_tracer(__name__)
with tracer.start_as_current_span("do-work"):
    ...

Call init_otel exactly once at process startup. It's safe to call again (or to let library code fall back to get_tracer/get_meter before it runs) — both paths are no-ops on top of an already-configured provider. OTEL_SDK_DISABLED=true turns the whole thing into a no-op, and a misconfigured exporter degrades to "telemetry doesn't work" rather than crashing the host process.

Where does it go?

Full contract: docs/otel.md → Local file mode.

Reading telemetry back (query extra)

from ko_observability.query import get_query_client

client = get_query_client()
traces = client.list_traces(limit=20)

Scoped to the caller's own service_name by default. See docs/query.md.

Docs

Full documentation — env vars, the logs/metrics pipelines, semantic conventions, and the Collector deployment this SDK ships telemetry to — lives in the repository:

https://github.com/Komus-ai/nexora-observability/tree/main/docs