feat(otel): optional OpenTelemetry tracing (ADR-0025)

[muhammetsafak]

The Python mirror of babelqueue-go/otel (ADR-0025): optional OpenTelemetry tracing as a new babelqueue.otel module, importable only with the [otel] extra so the core stays dependency-free (GR-7).

What

• trace_id ↔ 128-bit OTel trace id (a UUID maps to its bytes; otherwise SHA-256). The already-propagated trace_id becomes the shared OTel trace across every hop/SDK — no envelope change (GR-1).
• wrap_handler(tracer, handler) — a CONSUMER span process <urn> in the trace_id-derived trace, with messaging-semconv attributes + error recording. Its *args signature makes the runtime pass the full envelope, so it reads trace_id/job even when the inner handler only wants (data, meta).
• publish(tracer, app, urn, data) — a PRODUCER span publish <urn> that carries the active trace into the message's trace_id.

Tests / CI

• 5 tests via an in-memory span exporter; babelqueue.otel at 100% line coverage; ruff + mypy clean.
• CI installs the [otel] extra + opentelemetry-sdk in the test/lint/coverage jobs so the suite runs under the existing --cov-fail-under=90 gate.

Honest limit

One correlated trace per trace_id; exact cross-hop span parent-child (W3C traceparent as a transport header) is the documented follow-up.

🤖 Generated with Claude Code