← 概念解説に戻る

Concept Fable

追跡記録

先に結論:Trace(トレース記録)は、一回のリクエストまたはタスクの開始から終了までの完全な実行経路を記録する。Agentシステムにとって、一つのtraceは通常、ユーザー入力、モデル呼び出し、検索ステップ、ツール呼び出し、パラメータ、返却結果、遅延、エラー、中間状態を含む。Traceは可観測性の中核オブジェクトであり、一回の実行で実際に何が起きたかを再現するために使われる。

Trace · Observability artifact

まず物語を読む。ここでは急いで定義を示さず、まず問題そのものを立ち上がらせる。

寓話

行方不明の荷物が残した十二の印章

カモメ郵便局は毎日千以上の荷物を処理する。窓口で受け取り、仕分け係が札を貼り、倉庫で重量を量り、埠頭で船に積み、駅伝で転送し、受取人が署名する。荷物が届きさえすれば、人々はそれが途中どこを通ったかをほとんど気にしない。

ある日、急用の測定器一箱が届かなかった。送り主は窓口に渡したと言い、窓口は倉庫に入れたと言い、倉庫は船に載せたようだと言い、船頭はそれがその箱かどうか分からないと言った。誰もが自分の目の前の一小段だけを覚えており、全行程を説明できる者はいなかった。

郵便局長は最初、皆にそれぞれ帳簿を調べさせた。窓口は窓口の帳簿を、倉庫は倉庫の帳簿を、埠頭は埠頭の明細を。一日中調べても、各工程は『目立った誤りはない』と言う。荷物は依然として見つからない。

年老いた郵便配達人は言った。私たちに足りないのは、もっと多くの台帳ではなく、台帳をつなぐ一本の糸だ。そこで彼は各小包に長い紙片を付け、小包が一つの工程を通過するたびに印章を押した。誰が引き継ぎ、いつ、何をし、どれだけ時間がかかり、異常はなかったか、誰に渡したか。

新制度が始まった当初、皆は余分な手続きのように感じた。二つ目の小包がまた遅延するまでは。局長は長い紙を広げ、それが第三駅で六時辰止まったのを見た。原因は重量再検査の失敗だった;再検査後また倉庫に送り返されラベルを貼り直した;貼り直した人が目的地の略称を間違えて書き、その後の誤仕分けを引き起こした。

今回は誰も互いに推測し合わなかった。経路全体が机の上に広げられ、遅延は曖昧な「郵便局の問題」ではなく、いくつかの具体的なステップが連なった結果であった。第三駅伝所がなぜ遅いのか、倉庫がなぜ貼り替えるのか、略語がなぜ誤読されるのか、すべて追跡を続けられる。

その後、カモメ郵便局は事故の時だけ長い紙を見るのではなくなった。局長は毎週何枚かを抜き出して見て、いつも遅い区間、よく手戻りする宿駅、最終的には届いても途中で遠回りしている荷物があることに気づいた。

荷物自体が賢くなったわけではない。賢くなったのは郵便局が、あることが始まりから終わりまでに何を経験したかを見られるようになったことだ。もはや「着いたか」だけを問うのではなく、「どう着いたか、どこで遅れたか、どこで間違えたか、次はどうすればより安定するか」を問える。

明らかにする

この物語が語るのは:追跡記録

Trace(トレース記録)は、一回のリクエストまたはタスクの開始から終了までの完全な実行経路を記録する。Agentシステムにとって、一つのtraceは通常、ユーザー入力、モデル呼び出し、検索ステップ、ツール呼び出し、パラメータ、返却結果、遅延、エラー、中間状態を含む。Traceは可観測性の中核オブジェクトであり、一回の実行で実際に何が起きたかを再現するために使われる。

重要なのは、それが単なる用語ではなく、実際のAI/Agentシステムで繰り返し現れる構造的な問題だという点だ。これを理解して初めて、いつモデルを足すべきか、いつプロセスを変えるべきか、いつガバナンスを補うべきかを判断できる。

メタファーのマッピング

  • パッケージ:1回のユーザーリクエスト、Agent タスク、または業務チケット
  • 窓口、倉庫、埠頭、駅伝:一回の実行における異なるコンポーネント、例えばモデル、検索器、ツール、データベース、承認ノード
  • 各自が帳簿を調べるが繋がらない:局所ログのみで、エンドツーエンド trace がない
  • 長い紙:Trace ID が実行全体を貫く追跡記録
  • 各段階で押印:Spanは単一操作の時間、入力、出力、状態を記録する
  • 第三駅は六時間停まる:Traceが遅延がどのステップで起きたかの特定を助ける
  • 目的地の略称を間違える:Trace は誤りが上流から下流へどう伝わるかを明らかにできる
  • 毎週長い紙の帯を抜き取り検査する:trace を通じて性能分析、品質振り返り、システム最適化を行う

Andy(任旭)判断

この概念の実戦的価値は、「賢く見えるAI機能」を納品可能、検収可能、ガバナンス可能な作業単位に分解する手助けをすることです。

spanobservability実行ステップ監査ログデバッグLangSmith
京ICP备2026014272号