Gateway has a trace-hook seam but no concrete OpenTelemetry exporter and no CLI/YAML/Python config to turn tracing on

Aperta
#5,169 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

  • #23 di @praisonai-triage-agent — chiusa senza merge

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
python
Ambito
observability

Direzione di ricerca

Start from the existing trace seam in gateway/protocols.py (GatewayTraceHook, resolve_trace_hook, GATEWAY_TRACE_STAGES) and its re-exports in gateway/init.py, then read gateway/config.py and bots/_config_schema.py to see where an observability/tracing block would go. A linked pull request is already open, so check it before starting. Done means a concrete OTLP hook, selected by config, emits spans for each stage and stays a no-op when disabled.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

bug claude

Summary

The gateway exposes a tracing seam (GatewayTraceHook / resolve_trace_hook / GATEWAY_TRACE_STAGES) but ships no concrete span exporter and no way for an operator to enable tracing declaratively. There is no observability: / tracing: block in the gateway config schema, no --otlp-endpoint CLI flag, and no Python knob on the gateway to wire an OpenTelemetry (OTLP) exporter. As a result, a production gateway emits correlation-ID logs + a Prometheus /metrics endpoint, but per-turn/per-stage distributed traces (inbound → route → admission → run → delivery) cannot be exported to an OTel collector / Jaeger / Grafana / Datadog without out-of-band code. This also breaks PraisonAI's "every feature works three ways (CLI + YAML + Python)" principle: the only tracing integration today (Langfuse) lives as a wrapper-CLI side-channel with no YAML/Python parity.

Current behaviour

The trace-hook contract exists in core and is exported, but nothing concrete consumes it:

# src/praisonai-agents/praisonaiagents/gateway/protocols.py
class GatewayTraceHook(Protocol): ...        # stage spans: on_stage_start/on_stage_end
class NullGatewayTraceHook: ...              # default no-op
def resolve_trace_hook(...) -> GatewayTraceHook: ...
GATEWAY_TRACE_STAGES = (...)                 # declared stage names
# src/praisonai-agents/praisonaiagents/gateway/__init__.py:167-171, 481-485
#   re-exports GatewayTraceHook / NullGatewayTraceHook / resolve_trace_hook / GATEWAY_TRACE_STAGES

Verification of the gaps around that seam:

  • No concrete span exporter anywhere in praisonai / praisonai-bot / praisonai-agents source — the only opentelemetry-* mentions are transitive entries in src/praisonai/poetry.lock (pulled by unrelated deps), not an implementation.
  • No tracing config surface — src/praisonai-bot/praisonai_bot/bots/_config_schema.py has no observability:/tracing:/otel: block (its only trace reference is about redacting tracebacks in logs). No --otlp/--trace CLI flag exists under src/praisonai-bot/praisonai_bot/cli, and GatewayConfig (gateway/config.py) has no trace-export field.
  • The existing metrics surface is Prometheus text only: GatewayMetrics served at GET /metrics (gateway/server.py), plus per-request correlation IDs (bots/_correlation.py) — no spans.

The abstract seam was added previously (#2716, closed); this issue is the missing concrete exporter + operator-facing configuration on top of it.

Desired behaviour

A gateway operator can turn on OpenTelemetry export in one declarative step and get spans for the gateway pipeline stages (already enumerated in GATEWAY_TRACE_STAGES) shipped to their collector, reusing the existing GatewayTraceHook seam. Disabled by default (zero overhead, optional dependency), backward compatible.

Layer placement

  • Primary layer: wrapper (praisonai / praisonai-bot)
  • Why not core: core must stay lightweight and dependency-free; the OpenTelemetry SDK is a heavy optional integration and belongs behind a lazy import in the wrapper. Core already provides the correct contract (GatewayTraceHook) — it should not gain the exporter.
  • Why not wrapper → it is wrapper: wiring optional packages and the operator's run/config surface (CLI flags, gateway.yaml) is exactly the wrapper's role (resolver: local → core → tools → plugins).
  • Why not tools: tracing is framework lifecycle observability, not something the agent calls during a task. (The agent-callable observability providers already in praisonai-tools/observability/ are a separate concern.)
  • Why not plugins: while a lifecycle plugin could consume the hook, first-class, discoverable 3-way config (YAML/CLI) for the gateway's own telemetry belongs in the wrapper so it is on by a single config key, not an install-a-plugin step; a plugin implementation can still register through the same hook.
  • Secondary touch (optional): core — only if GatewayTraceHook needs a small extension to carry attributes (e.g. tenant/scope, model) on spans.
  • 3-way surface (CLI + YAML + Python): yes.

Proposed approach

  • Extension point: config + existing hook — a concrete OtelGatewayTraceHook (wrapper, optional opentelemetry extra) selected by config and injected via resolve_trace_hook.
  • Minimal API sketch (YAML):
# gateway.yaml
observability:
  tracing:
    exporter: otlp            # otlp | none (default: none)
    endpoint: http://collector:4318
    service_name: praisonai-gateway
    sample_ratio: 1.0
praisonai gateway start --otlp-endpoint http://collector:4318
from praisonai_bot import WebSocketGateway
WebSocketGateway(config, trace_hook="otlp")   # or an explicit GatewayTraceHook instance

Resolution sketch

# Before (today): the seam exists but resolves to a no-op; no exporter, no config.
hook = resolve_trace_hook(None)          # -> NullGatewayTraceHook  (spans go nowhere)

# After (proposed): config selects a concrete OTLP exporter behind the same seam.
# wrapper: praisonai_bot/observability/otel_trace_hook.py  (opentelemetry optional extra)
class OtelGatewayTraceHook:               # satisfies GatewayTraceHook
    def on_stage_start(self, stage, ctx): ...   # start a span per GATEWAY_TRACE_STAGES
    def on_stage_end(self, stage, ctx, error=None): ...  # end/record

hook = resolve_trace_hook(config.observability.tracing)   # -> OtelGatewayTraceHook
# inbound -> route -> admission -> run -> delivery now emit OTLP spans to the collector.

Severity

High — distributed tracing is table-stakes for operating a production gateway, and its absence (plus the missing YAML/CLI parity) is a concrete ease-of-use and observability gap; the enabling seam already exists, so the remaining work is a focused wrapper addition.

Validation

Confirmed by reading source: the GatewayTraceHook/resolve_trace_hook/GATEWAY_TRACE_STAGES seam is defined in gateway/protocols.py and re-exported from gateway/__init__.py:167-171 but has no concrete consumer; no span-exporter implementation exists in praisonai/praisonai-bot/praisonai-agents source (only transitive poetry.lock deps); _config_schema.py has no observability/tracing block and no tracing CLI flag exists. Distinct from the closed #2716, which added the abstract hook only; related open interest in #579 ("Open Telemetry").

Lingua principale
Python
Stelle
9.3k
Fork
1.5k
Merge medio
1g 5h
PR unite (30g)
520

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di MervinPraison/PraisonAI

Tutte le issue di MervinPraison/PraisonAI

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.