Add distributed tracing via OpenTelemetry

[valdis]

Every message hop across agents now shares a single trace_id, giving end-to-end visibility into multi-agent interactions. Tracing is opt-in and zero-cost when not configured.

Description

Adds distributed tracing support to the EggAI SDK using OpenTelemetry. A traceparent field (W3C Trace Context) is propagated through every message, linking producer and consumer spans across agents and transport backends into a single end-to-end trace. Every message hop across agents shares a single trace_id, giving end-to-end visibility into multi-agent interactions.

Tracing uses a swappable backend (_NoOpBackend / _OtelBackend) so setup_tracing() can be called at any point — handlers subscribed before it is called are immediately traced once it fires. When the otel extra is not installed, handlers are never wrapped and there is zero overhead.

Type of Change

• New feature (non-breaking change which adds functionality)

Changes Made

• Added sdk/eggai/tracing.py with setup_tracing(), swappable _NoOpBackend / _OtelBackend, make_tracing_wrapper() for consumer spans, and auto-activation when OTEL_EXPORTER_OTLP_ENDPOINT is set
• Added traceparent: str | None field to BaseMessage for W3C Trace Context propagation
• Updated Channel.publish() to inject/continue trace context into outgoing messages as a PRODUCER span via the active backend
• Wrapped subscriber handlers in all three transports (InMemory, Kafka, Redis) with a CONSUMER span that restores the upstream trace context
• Fixed Redis transport to avoid double-wrapping the handler on internal retry subscriptions
• Added otel optional extra to pyproject.toml (pip install eggai[otel]) with OTLP gRPC, OTLP HTTP, and console exporters
• Added sdk/tests/test_tracing.py with test coverage for no-op, producer spans, consumer spans, trace continuation, and multi-hop trace propagation

Testing

• Existing tests pass locally (make test)
• Added new tests for new functionality
• Tested manually (describe below if applicable)

Manual Testing Steps

1. Install with pip install eggai[otel]
2. Set OTEL_EXPORTER_OTLP_ENDPOINT (or call setup_tracing(exporter="console") at startup)
3. Publish a message from one agent and consume it in another — both spans appear under the same trace_id in your tracing backend (Jaeger, Tempo, etc.)
4. Run without calling setup_tracing() — confirm no errors and no performance change

Changelog

• I have updated sdk/CHANGELOG.md under [Unreleased] section (required for code changes)

Checklist

• My code follows the project's code style (make lint passes)
• My code is properly formatted (make format applied)
• I have added/updated tests that prove my fix/feature works
• I have added/updated documentation as needed
• All tests pass locally
• I have reviewed my own code
• My changes generate no new warnings
• My commit messages follow the Conventional Commits standard

Additional Notes

• Zero overhead when OTel is not installed — make_tracing_wrapper detects OTel is absent at import time and returns handlers unwrapped; no closures allocated, no per-message cost
• Order-independent activation — setup_tracing() swaps the backend in-place; handlers already subscribed begin producing real spans immediately, no re-subscription needed
• No provider clobber — if a TracerProvider is already configured (e.g. by the application), setup_tracing() adopts it rather than overwriting it
• Supports OTLP gRPC (default), OTLP HTTP, and console exporters; also accepts a pre-built exporter object for testing
• Auto-activates via OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_EXPORTER_OTLP_PROTOCOL env vars (silently skips if the otel extra is not installed)
• Redis transport: handler is only wrapped on the initial subscribe call, not on internal retry-stream subscriptions, to prevent duplicate spans and consumer group name corruption

[github-actions]

QualOps Code Quality Analysis

Status: ✅ PASSED - No issues found

Summary

• Total Issues: 0
• Critical: 0 🔴
• High: 0 🟠
• Medium: 0 🟡
• Low: 0 🟢
• Files Analyzed: 0

No issues found in the analyzed code.

📊 Full Report

View detailed report

---

Powered by QualOps