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

オープン
#5,169 コメント 2 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

  • #23 @praisonai-triage-agent による — マージされずにクローズ

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
25/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
静か
技術スタック
python
領域
observability

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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").

主要言語
Python
スター
9.3k
フォーク
1.5k
平均マージ
1日 5時間
マージ済み PR(30日)
520

環境構築

このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

MervinPraison/PraisonAI のほかの issue

MervinPraison/PraisonAI の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。