Metadata-Version: 2.5
Name: ko-observability
Version: 0.5.0
Summary: Org-wide OpenTelemetry bootstrap for Python services
Project-URL: Repository, https://github.com/Komus-ai/ko-observability
Project-URL: Documentation, https://github.com/Komus-ai/ko-observability/tree/main/docs
Author-email: Komus-ai <dev@cinco.ai>
License: MIT
Keywords: observability,opentelemetry,otlp,structlog
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: opentelemetry-api>=1.27.0
Requires-Dist: opentelemetry-exporter-otlp-proto-common>=1.27.0
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27.0
Requires-Dist: opentelemetry-sdk>=1.27.0
Requires-Dist: protobuf<8.0,>=5.0
Requires-Dist: structlog>=24.4.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: opentelemetry-sdk>=1.27.0; extra == 'dev'
Requires-Dist: pymongo>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: elasticsearch
Requires-Dist: opentelemetry-instrumentation-elasticsearch>=0.48b0; extra == 'elasticsearch'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.115.0; extra == 'fastapi'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'fastapi'
Provides-Extra: httpx
Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0; extra == 'httpx'
Provides-Extra: pymongo
Requires-Dist: opentelemetry-instrumentation-pymongo>=0.48b0; extra == 'pymongo'
Provides-Extra: query
Requires-Dist: httpx>=0.27.0; extra == 'query'
Description-Content-Type: text/markdown

# 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

```bash
pip install ko-observability
```

Optional extras, install alongside the base package as needed:

```bash
# 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

```python
from ko_observability import init_otel, get_tracer

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

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?

| `TELEMETRY_DESTINATION` | Output |
|---|---|
| `file` (default) | `$TELEMETRY_FILE_DIR/{traces,metrics,logs}.jsonl` (default `./telemetry`), one OTLP/JSON request per line |
| `otlp` | OTLP/gRPC to `OTEL_EXPORTER_OTLP_ENDPOINT` (default `http://localhost:4317`) |

Full contract: [docs/otel.md → Local file mode](../../docs/otel.md#local-file-mode-the-default).

## Execution helpers

Generic wrappers so service code never imports `opentelemetry`. Full guide with Go and JS
equivalents: [docs/02-utilisation.md](../../docs/02-utilisation.md#plomberie-dexécution).

| Helper | Signature | Role |
|---|---|---|
| `current_traceparent` | `() -> str \| None` | W3C `traceparent` of the active span, `None` outside a valid span |
| `extract_traceparent` | `(traceparent: str \| None) -> Context \| None` | parent context, `None` if absent/invalid (never raises) |
| `start_execution_span` | `(name, *, traceparent=None, attributes=None, kind=SpanKind.INTERNAL, exception_message=False)` context manager | current span for one execution, continuing `traceparent`; exceptions recorded (ERROR, type only unless `exception_message=True`) and re-raised |
| `set_current_span_attributes` | `(attrs: Mapping) -> None` | attributes on the current span; no-op if not recording |
| `execution_context` | `(**kv)` context manager | binds structlog contextvars, restored on exit; stamped on spans via `init_otel(context_attr_map=...)` |
| `force_flush` | `(timeout_ms: int = 2000) -> None` | flushes tracer, logger and meter providers; never raises |

Re-exports: `Span`, `SpanKind`, `Status`, `StatusCode`, `InMemoryMetricReader`.

```python
from ko_observability import start_execution_span, set_current_span_attributes, force_flush

with start_execution_span("task.run", traceparent=incoming_tp, attributes={"task.id": "t-1"}):
    set_current_span_attributes({"step": "load"})
force_flush()
```

## Tracer without side effects (0.4)

`get_tracer(name, version=None, *, bootstrap=True)` returns a `Tracer`. With `bootstrap=False` it
only reads the global registry: no provider is created and the lazy-bootstrap latch is untouched
(a no-op tracer when nothing is installed). The new span helpers below use it, so they never
create a provider by themselves.

## Manual spans, context and propagation (0.4)

For work that does not fit a `with` block (streams, callbacks, background tasks). None of these
creates a provider: without an installed SDK the span is a no-op.

| API | Role |
|---|---|
| `start_span(name, *, traceparent, tracestate, parent, root, kind, attributes, links, instrumentation_name, instrumentation_version)` | span NOT made current; parent priority `root` > `parent` > `traceparent` > current; `root` with `parent`/`traceparent` raises `ValueError` |
| `activate_span(span)` | context manager: span current inside the block, previous context restored; does not end the span; never raises on exit |
| `end_span(span, *, exc, error, description, error_policy, record_exception=True)` | final status and `end()`; no-op if already ended; never raises. `error=True` ERROR, `error=False` OK, else `exc` + `error_policy(exc)` (default always an error) |
| `start_execution_span(..., kind, links, root, parent, tracestate, error_policy, exception_message)` | same parent rules; `error_policy(exc) -> False` leaves the status UNSET, no `exception` event, exception still re-raised; `exception_message=True` puts the message in the status and event |
| `current_trace_ids()`, `trace_ids_of(span)` | `(trace_id, span_id)` as 32/16 hex chars, `None` if invalid |
| `current_span()`, `current_span_context()` | current span / its valid `SpanContext` |
| `annotate_current_span()` | copies the `init_otel(context_attr_map=...)` structlog keys onto the current span |
| `current_trace_headers(*, include_baggage=False)`, `inject_trace_headers(headers, *, include_baggage=False)` | `traceparent`, `tracestate` (and `baggage` on request) for outgoing calls |
| `extract_trace_context(headers, *, accept_baggage=False)` | parent `Context` from incoming headers (case-insensitive), `None` if invalid; incoming baggage ignored by default |
| `extract_traceparent(tp, tracestate=None)`, `link_from_traceparent(tp, tracestate=None, attributes=None)` | parent context / span `Link` |

Baggage is opt-in in both directions and is never used by ko to attribute anything.

```python
from ko_observability import activate_span, end_span, start_span

span = start_span("stream", traceparent=incoming_tp)
try:
    with activate_span(span):
        ...
except Exception as exc:
    end_span(span, exc=exc, error_policy=lambda e: not isinstance(e, KeyError))
    raise
else:
    end_span(span)
```

## `init_otel` options, redaction, instrumentation (0.4)

`init_otel` returns `True` if this call installed the SDK. New keyword-only options:
`telemetry_destination`, `service_version`, `deployment_environment`, `resource_attributes`,
`service_instance_id`, `redacted_query_params`, `redacted_query_prefixes`, `traces_sampler`,
`traces_sampler_arg`, `exporter_timeout_ms` (details in [docs/otel.md](../../docs/otel.md)).
`is_initialized()`, `has_metric_reader()`, `reset_for_tests()` and `default_service_instance_id()`
complete it. `redact_url(url, names, prefixes=())` and `QueryRedactionSpanProcessor(names, prefixes)` mask
secret query parameters; the list of names belongs to the application. `instrument_fastapi(app)` and
`instrument_pymongo()` (extra `pymongo`, covers Motor) are idempotent and return `False` when the extra is
missing.

## Test helpers (`ko_observability.testing`, 0.4)

Imports the SDK; never imported by the package root. No pytest dependency.

```python
from ko_observability.testing import telemetry_capture

with telemetry_capture() as cap:      # fresh in-memory traces + metrics + logs, restored on exit
    ...
    assert [s.name for s in cap.spans()] == ["work"]   # also cap.metrics(), cap.logs(), cap.clear()
```

Also: `reset_otel_globals()`, `uninstrument_all()`, `uninstrument_fastapi(app)`, `bind_baggage(**items)`,
`baggage_items(ctx=None)`, and re-exports (`InMemorySpanExporter`, `InMemoryMetricReader`,
`InMemoryLogRecordExporter`, `SimpleSpanProcessor`, `TracerProvider`, `MeterProvider`, `LoggerProvider`,
`Resource`, `PeriodicExportingMetricReader`). A pytest fixture is documentation only:
`@pytest.fixture def otel_capture(): with telemetry_capture() as c: yield c`.

The package root also re-exports `Context`, `Link`, `SpanContext`, `Tracer`, `SpanProcessor`, `ReadableSpan`,
`Meter`, `Counter`, `Histogram`, `UpDownCounter`, `ObservableGauge`, `ObservableCounter`,
`ObservableUpDownCounter`, `CallbackOptions`, `Observation`. `tests/consumer_check.py` is type-checked with
`mypy --strict --follow-imports=silent`.

## Reading telemetry back (`query` extra)

```python
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/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/ko-observability/tree/main/docs
