Tracely: 本番トレースを回帰テストに凍結するCIゲートの設計を読む

Tracely が置き換えようとしているのは評価ツールではなく「テストの出所」

一般的な LLM 評価ツールは、まずデータセットを人手で用意することを求める。質問を考え、理想の回答を書き、プロダクトの変化に合わせて更新し続ける。README はこのやり方を「起こるかもしれない失敗についての推測」と表現し、本番ですでに起きた失敗のトレースのほうが忠実度が高いと主張する。Tracely の中心にあるのはこの一点で、記録された実行そのものをテストとして扱う。README の比較表では、テストの出所、本番との忠実度、CI 再生コスト、回帰時の挙動、通知の到達方法の5項目でデータセット先行型のツールと対比している。CI 再生コストの欄には、記録済みのツール呼び出しと LLM 出力をフィクスチャとして使うため $0 と書かれている。対象読者は、エージェントを本番運用していて、失敗の再発防止を人手のテスト作成に依存させたくない開発チームである。

OTLP で受け、agent.id と conversation.id を索引列に昇格させる

トレースは OTLP で受信する。README によれば、エージェント意味論に関わる agent.id、conversation.id、turn、step は第一級の索引列に昇格され、実行がフラットなスパンの寄せ集めではなく会話スレッドとしてまとまる。ウォーターフォール表示は agent、thinking、skill、generation、hand-off の階層を描き、失敗したスパンを赤で示してその入出力を横に並べる。評価器は別タブではなくトレーステーブルの列として扱われ、会話・実行・スパンの各レベルで採点し、判定をグリッドに書き込む。判定は SSE で流れてくるため、実行がその場で採点されていく様子が見える。トークン数、コスト、レイテンシ、メタデータ、ターンごとのローリングサマリも同様に列である。この設計は、評価結果を後から別画面で突き合わせる運用を減らす代わりに、トレーステーブルのスキーマに評価列を同居させることを意味する。

失敗のクラスタリングと、評価器を提案する仕組み

オンライン評価器が実行の到着ごとに採点する。LLM-as-judge を会話・実行・スパンの各レベルで使うほか、モデルを必要としない構造的チェックも併用する。失敗は構造的および意味的にクラスタリングされ、README の例では31件の壊れた実行が31行ではなく出現回数付きの1つの issue になる。各クラスタは、それを捕まえられたはずの評価器を提案できると書かれている。ここは運用上おそらく最も効く部分で、失敗の件数ではなく失敗の型を単位にすることで、トリアージの対象が人間の読める数に収まる。ただしクラスタリングの粒度や類似度の閾値といった設定値は提供された資料からは確認できない。クラスタが粗すぎれば別種の失敗が同じ issue に混ざり、細かすぎれば issue が増えて元の問題に戻る。この境界は自社のトレースで確かめるしかない。

fail-to-pass 契約という厳しめの前提

失敗トレースを回帰ケースに昇格させる操作はワンクリックだと説明されている。記録済みの入力、ツール出力、LLM 出力がフィクスチャとして束ねられ、そこに fail-to-pass 契約が付く。古いコードで失敗し、修正後に通らなければ、その昇格は信頼されない。つまりケースが増えるほど「本当に回帰を検出できるケースだけが残る」方向に働く。マルチターンの挙動にはシナリオを使う。スクリプト化された会話か、レッドチームモデルがその場で組み立てる敵対的ゴールのいずれかである。この契約は運用コストにも直結する。失敗トレースのすべてがそのままテストになるわけではなく、契約を満たさないものは昇格できない。フレーキーな失敗や環境依存の失敗はここで弾かれる可能性が高い。

CI ゲートの実体は tracely gate の終了コード

スイートは CI 上で記録済みフィクスチャに対して再生される。README はこれを決定論的かつオフラインで、API キーもモデル課金も不要と説明する。tracely gate は非ゼロで終了し、コミットステータスを投稿し、PR コメントを upsert する。導入の入口は PyPI の tracely-ai パッケージで、Python 3.10 以上が要件として示されている。フルのスタックを自前で立てる場合は、API、ワーカー、UI、Postgres、ClickHouse、Redis、MinIO を Railway のワンクリックテンプレートでデプロイできると README に書かれている。ライセンスは MIT である。ここで注意したいのは、ゲートが意味を持つのは再生対象のケースが十分に揃ってからだという点だ。ケースが数件の段階では、PR を止める判断材料としては薄い。CI への挿入位置と、失敗時に開発者が何を見て修正に入るかまで含めて設計する必要がある。

アラートは条件とアクションをキャンバスで組む

通知はルールとして定義する。ルールは when と what happens の2つの半分からなる。when の例として README は、ゲートの失敗、ライブ会話が judge で壊れたとき、誰も見たことのない失敗モードの出現、レートが閾値を超えたときを挙げる。アクションはキャンバス上に描く。フローの残りをゲートする条件、Slack、メール、独自 Webhook が含まれる。監視ツールを別に立ててダッシュボードを見に行く運用ではなく、検知から通知までを同じ場所で組む発想である。README の比較表でも「どうやって知るか」の行で、見に行くのではなく向こうから来ると表現している。もっとも、通知経路の信頼性やリトライの扱いについては提供された資料からは読み取れない。

向かないケースと、代替となるアプローチ

Tracely が前提にしているのは、本番のトレースがすでに存在することだ。トレースを出していなければ、最初に凍結できる失敗がなく、ループは回らない。もうひとつの前提は、記録済みフィクスチャに対する再生が意味を持つことである。外部 API の応答が毎回変わる、あるいはエージェントが非決定的にツールを選ぶ設計では、フィクスチャとの差分が実際の回帰なのか単なる揺らぎなのかを切り分けるのが難しくなる。代替としては、人手でデータセットを管理する評価ツールがある。違いはテストの出所である。データセット先行型は、まだ起きていない失敗も含めて意図的にテストを設計できる。Tracely は起きた失敗しかテストにできない。新機能のリリース前に未知の失敗を潰したいなら前者、本番で起きた再発を止めたいなら後者という住み分けになる。両方を併用する判断もありうる。

保守コストとライセンスの確認点

MIT ライセンスであるため、自社プロダクトへの組み込みや改変、再配布は比較的自由度が高い。ただし MIT は無保証であり、ゲートが誤って PR を止めた場合の責任は導入側にある。ライセンス条項の解釈は法務の領域なので、ここでは条文そのものを確認することを勧めるにとどめる。保守の観点では、セルフホスト構成が Postgres、ClickHouse、Redis、MinIO の4つのストレージ系コンポーネントを含む点が効いてくる。Railway のワンクリックテンプレートは立ち上げを簡単にするが、運用中のバックアップ、ClickHouse のディスク増加、ワーカーのスケールは導入側の仕事として残る。リリースは取得できておらず、最終プッシュは2026年9月9日、アーカイブはされていない。バージョン固定で導入するか、master を追うかを最初に決めておきたい。

編集部の結論

導入を検討すべきなのは、すでに OTLP でトレースを出しており、失敗パターンを人手でデータセット化する運用に行き詰まっているチームである。逆に、トレースをまだ収集していない、あるいはエージェントの出力が毎回大きく変わり「同じ入力で同じ出力」を前提にできない設計のチームには向かない。最初に確認すべきは、自社のトレースに agent.id や conversation.id が付与されているか、そして tracely gate を既存 CI のどのステップに挿入するかである。fail-to-pass 契約が通らないケースは昇格が信頼されない仕様なので、昇格フローが実際に自社の失敗トレースで回るかを最初の1件で確かめてから広げるのが妥当だ。

公式情報源

1. Issues
2. Jwuthri/Tracely-ai on GitHub
3. License: MIT
4. Project website
5. README