Gateway has a trace-hook seam but no concrete OpenTelemetry exporter and no CLI/YAML/Python config to turn tracing on
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
- #23 @praisonai-triage-agent による — マージされずにクローズ
評価
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 初心者へのやさしさ
- 25/100
- issue の種類
- 機能追加
- 明瞭さ
- おおむね明確
- 活発さ
- 静か
- 技術スタック
- python
調査の方向性
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 の本文から書いたものです。
説明
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-agentssource — the onlyopentelemetry-*mentions are transitive entries insrc/praisonai/poetry.lock(pulled by unrelated deps), not an implementation. - No tracing config surface —
src/praisonai-bot/praisonai_bot/bots/_config_schema.pyhas noobservability:/tracing:/otel:block (its onlytracereference is about redacting tracebacks in logs). No--otlp/--traceCLI flag exists undersrc/praisonai-bot/praisonai_bot/cli, andGatewayConfig(gateway/config.py) has no trace-export field. - The existing metrics surface is Prometheus text only:
GatewayMetricsserved atGET /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
GatewayTraceHookneeds 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, optionalopentelemetryextra) selected by config and injected viaresolve_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 を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
MervinPraison/PraisonAI のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
MervinPraison/PraisonAI#6710 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
claude
難易度 2/5 1〜3時間 初心者へのやさしさ 74/100
MervinPraison/PraisonAI#6707 ·
メンテナーはふだん 1 日以内に返信
-
bug claude
難易度 1/5 1時間未満 初心者へのやさしさ 90/100
MervinPraison/PraisonAI#6671 ·
メンテナーはふだん 1 日以内に返信
-
Compaction budget regression fixture remains below budget with accurate tokenization再び着手できるかも このイシューのプルリクエストはマージされずにクローズされました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 62/100
MervinPraison/PraisonAI#5418 · コメント 3 件 ·
メンテナーはふだん 1 日以内に返信
-
bug claude documentation
難易度 2/5 1〜3時間 初心者へのやさしさ 70/100
MervinPraison/PraisonAI#5341 · コメント 3 件 ·
メンテナーはふだん 1 日以内に返信
MervinPraison/PraisonAI の issue をすべて見る
似ている issue
-
cognition
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 78/100
collabnix/awesome-mcp-lists#433 ·
メンテナーはふだん 4 日以内に返信
-
CrossEntropyFilter raises on zero probabilities and single-class results対応中かも @NopeCharon が今日担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
メンテナーはふだん 1 日以内に返信
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
datajoint/datajoint-python#1703 ·
メンテナーはふだん 6 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
Archmonger/ServeStatic#129 ·