phoenix-error-analysis

エラー分析

サンプリングしたトレース、スパン、またはセッションを対象に、2つのフェーズで進めます。オープンコーディングでは、サンプリングした各エンティティを読み、何が問題だったかを具体的に短く記録します。軸足コーディングでは、それらの記録をいくつかの限定的なアノテーションにまとめます。各アノテーションは、少数のラベルセットを用いてエンティティの1つの側面を評価し、ラベルを集計して、評価設計や修正の優先順位付けに役立てます。オープンコーディングは必ず先に行います。記録に根拠のない側面やラベルを設定すると、上から決めつけることになり、このワークフローが避けようとしている失敗につながるためです。軸足コーディングは、既存の自由記述による観察事項を出発点にすることもできます。

記録したメモが成果物です。 オープンコーディングは、問題のあるエンティティごとに1件のメモをサーバーに記録し、ローカルのサイドカーにも反映した時点で完了します。チャットで要約するだけでは完了しません。トレースを読んで気づいたことを報告するだけで何も記録しないのは、読み取り専用の診断にすぎず、このワークフローが置き換えようとしている上からの決めつけです。「問題を見つけて」「何が起きているのか」「ここにエラーはあるか」といったプロジェクト全体に関する質問は、フェーズ1の依頼です。識別子と単位を選び、問題を見つけるたびにメモを記録してから、要約します。まだアノテーション名がないプロジェクトは通常の開始状態であり、記録を控える理由にはなりません。

分析単位の選択

記録を始める前に、トレース、スパン、セッションのいずれを単位にするか、意識して選んでください。この選択によって、以下のすべてのメモとアノテーションの対象が決まります。初期設定を誤ると、実行途中で修正するコストが大きくなります。単位は、調査対象の失敗モードが実際に存在する場所です。

• トレース — 1つの入力 → 1つの出力。分類器、単発の要約器、ステートレスなツール使用エージェント、単一クエリの RAG。
• スパン — トレース内の1つの操作。単独で判定できる機械的な失敗（例外、ツールのエラー応答、不正な形式の出力）や、見ただけで1つのコンポーネントに原因を特定できる失敗。
• セッション — session.id を共有するトレースの連続。失敗が軌跡として現れる複数ターンのエージェントが対象です。ターンをまたぐコンテキストの喪失、目標の逸脱、好みの失念など、トレースをまたいで初めて存在する失敗を扱います。

確認するシグナルは3つあります。

1. ユーザーの表現。 「会話」「エージェントが忘れた」「逸脱」「ターンをまたいで」→ セッション。「このトレース」「出力が間違っている」→ トレース。「例外」「不正な形式」「検索に失敗した」→ スパン。

2. セッションの構成。 セッション ID は、最上位のトレースフィールドではなく、ルートスパンの session.id 属性にあります。"" は値がないことを意味します。直近の約200件のトレースを一覧表示し、空でないセッション ID を持つものの数、異なるセッション ID の数、セッションあたりのトレース数の中央値を算出します。セッション ID がない、または中央値が1なら、トレースまたはスパン単位が適切です。中央値が2以上なら、セッション単位が妥当な可能性があります。

3. ターンの構造。 直近のトレースを1つ開き、ルートスパンの input.value を確認します（大きい場合があるため、全体を読むのではなくフィルターしてください）。ユーザーメッセージが1つなら単発です。メッセージの配列（[{role: user}, {role: assistant}, ...]）なら、セッション単位で扱う対話の1ターンです。

メモを記録する前に、選んだ単位を明示してください。データに応じて変更してもかまいません。トレース単位のメモで「エージェントは以前のターンをまったく覚えていない」という問題が繰り返し見つかるなら、次のバッチではセッション単位に切り替えるべきです。単位は最初の仮説であり、固定の約束ではありません。

コーディング注釈識別子（最初に選択）

このワークフローで生成されるすべての成果物（オープンコーディングのメモ、軸足コーディングのラベル、ローカルのサイドカーファイル）は、1つのコーディング注釈識別子でタグ付けされます。これにより、実行全体をひとまとまりとして検索・元に戻せます。記録を始める前に、coding-run:chatbot-context-loss-2026-05-06 のような、説明的で一意な値を選んでください。（coding-run: プレフィックスは命名規則であり、この値は Phoenix セッション ID ではありません。）

サーバーへの書き込みのたびに、識別子を明示的に渡してください。読みやすくするためにシェル変数を使ってもかまいませんが、シェルの継承に頼らないでください。多くのエージェントハーネスでは、コマンドごとに新しいサブシェルが起動されます。

ローカルのサイドカーは、CWD を基準として .px/coding/<sanitized-identifier>.jsonl（オープンコーディングのメモ）と .px/coding/<sanitized-identifier>-axial.jsonl（軸足ラベル）に保存されます。サニタイズでは、[a-zA-Z0-9_-] 以外の文字をすべて - に置き換えます。一意性はサーバーへの問い合わせではなく、ローカルファイルの確認で判定します。

CODING_ANNOTATION_IDENTIFIER="coding-run:chatbot-context-loss-2026-05-06"
SLUG=$(echo -n "$CODING_ANNOTATION_IDENTIFIER" | sed 's/[^a-zA-Z0-9_-]/-/g')
NOTES_SIDECAR=".px/coding/${SLUG}.jsonl"
AXIAL_SIDECAR=".px/coding/${SLUG}-axial.jsonl"
test ! -f "$NOTES_SIDECAR" || { echo "Sidecar already exists at $NOTES_SIDECAR — pick a new identifier or delete the file"; exit 1; }
mkdir -p .px/coding

$NOTES_SIDECAR がすでに存在する場合は、識別子に曖昧さを解消する文字列（-v2、-dustin など）を追加して、もう一度確認してください。

実行の再開 — 2つのフェーズは、それぞれ独立した呼び出しで実行される場合があります。新しいシェルで軸足コーディングを開始する場合は、オープンコーディングで選んだものと同じ識別子を設定し（ラップアップ UI の URL、または .px/coding/*.jsonl の一覧から確認できます）、一意性の確認は省略して、識別子からサイドカーパスを再導出してください。実行の途中で新しい識別子を作成しないでください。

書き込み先

以下の手順では、コマンドではなく操作を示しています。これらを実行する手段は2つあります。ハーネスで利用できる方を使ってください。phoenix-cli スキルでは px のフラグを、phoenix-graphql スキルのリファレンス（project-spans-traces.md、sessions.md、annotations.md）では GraphQL のフィールドとミューテーションの入力を説明しています。このスキルには、独自のリファレンスファイルは含まれていません。

操作	Phoenix CLI（px）	GraphQL（phoenix-gql または任意のクライアント）
サンプル、展開、掘り下げ	px trace list、px trace get <trace-id>、px span get <span-id>、px session get <session-id>	Project.spans(filterCondition: "parent_span is None")、getTraceByOtelId、getSpanByOtelId、セッションの node(id:)
既存のメモを確認	get／list で --include-notes を指定	Span.spanNotes、name == "note" を条件とする Trace.traceAnnotations／ProjectSession.sessionAnnotations
メモを書き込む	px trace add-note <trace-id> --text "..." --identifier "$CODING_ANNOTATION_IDENTIFIER"（px span add-note、px session add-note も同様）	createTraceNotes、createSpanNotes、createProjectSessionNotes — いずれも { note, annotatorKind: LLM, source: API, identifier } と、OTel ID（{ otelId }）またはノード ID（{ id }）によるエンティティ参照を受け取ります
軸足注釈を書き込む	px trace annotate <trace-id> --name <annotation-name> --label <label> --identifier "$CODING_ANNOTATION_IDENTIFIER"（span、session も同様）	createTraceAnnotations、createSpanAnnotations、createProjectSessionAnnotations — Phoenix のノード ID のみを使用し、name、label、explanation、annotatorKind: LLM、source: API、metadata: {}、identifier を渡します
注釈設定	px annotation-config list、create、update <identifier>	createAnnotationConfig、updateAnnotationConfig、addAnnotationConfigToProject
実行を破棄	px trace-annotations delete --identifier "$CODING_ANNOTATION_IDENTIFIER" --all -y（span-annotations、session-annotations も同様）	識別子で一括削除する方法はありません。実行に含まれる注釈のノード ID を集めてから、deleteTraceAnnotations、deleteSpanAnnotations、deleteProjectSessionAnnotations を実行してください

メモと注釈の書き込みは同期的に行われ、(entity, name, identifier) をキーとしてアップサートされます。ハーネスでミューテーションに承認手順が必要な場合は、各コマンドで行う書き込みの内容を説明し、ミューテーションごとに個別の呼び出しにしてください。

フェーズ 1：オープンコーディング

自由形式でメモを記述します。目にした内容を書き、当てはまると思うカテゴリは書かないでください。カテゴリ分けはフェーズ 2 で行います。

プロセス

1. コーディングアノテーション識別子を選び、サイドカーがまだ存在しないことを確認します
2. 単位を選びます — トレース、スパン、またはセッション
3. 調査します — 選んだ単位でエンティティを1つ取得し、その入力、出力、例外、ツール呼び出し、取得されたコンテキストを確認します（セッション単位の場合は、子トレース全体の軌跡も確認します）
4. 記録します — 問題があった場合は、具体的な文を1つ書きます。問題がなければスキップします
5. 保存します — サーバーにメモを書き込み、サイドカーに行を追加します
6. サンプルがなくなるか、飽和状態になるまで繰り返します

調査

• トレース単位 — 1つのトレースの入力 → ツール呼び出し → 取得されたコンテキスト → 出力を、一つのストーリーとして読みます。
• スパン単位 — 1つの操作の入力／出力を読み、コンテキストを把握するために周囲のスパンも確認します。
• セッション単位 — トレースの並びを順に読みます。データとなるのは個々のトレースではなく、トレース全体の軌跡です。

スパンのステータスが ERROR のものをサンプリングしないでください。 OTel の status_code が ERROR に切り替わるのは、インストルメンターが発生した例外を捕捉した場合だけです。ハルシネーション、不適切なトーン、検索漏れ、ツール選択の誤りは、すべて OK または UNSET として正常に完了します。エラーステータスで絞り込むと、このワークフローで明らかにしようとしている対象が除外されてしまいます。

確認する項目

これは分類体系ではなくチェックリストです。分類は後で行います。最初に問題が起きた箇所を記録してください。下流の症状は、独立した原因がある場合に限り、別のメモとして記録します。

• 明示的なエラー — ツール、LLM、またはリトリーバーのスパンにある例外やエラーメッセージ
• コストとレイテンシ — 通常より多いトークン数や、遅いスパン
• 検索品質 — 関連性がない、不足している、またはスコアが低いチャンク
• 応答品質 — ハルシネーション、事実誤認、不適切なトーン、不適切な拒否
• ツールの使用 — 誤ったツール、形式の不正な呼び出し、結果の誤処理
• 軌跡 — ループ、回り道、未完了のタスク。セッション全体では、コンテキストの喪失や目標の逸脱
• インストルメンテーションの欠落 — スパンや属性の欠落。可視化できていない箇所も発見事項です

既存の評価やアノテーションは、数ある入力の1つとして扱ってください。ステータスではなく内容を読んでください。成功ステータスでも属性にエラーが隠れていることがあり、例外が想定された動作である場合もあります。

使用するツールにかかわらず、取得する内容は次のとおりです。最近のトレースをサンプリングします（トレース ID、ルートスパン名、ステータス、ルートスパンの input.value／output.value）。1つのトレースを、開始時刻順のスパンに展開します。単位がスパンの場合は、IDを指定して単一のスパンを詳細確認します。また、これからレビューするエンティティに既存のメモがないか確認します。メモはサーバー側に、予約名 note のアノテーションとして保存されています。いつものことですが、データが冗長な場合もあるため、コンテキストを膨らませすぎないよう注意してください。

メモの記録

調査するセッション、トレース、またはスパンごとに、サーバーにメモを送信し（書き込み先を参照）、ローカルにもコピーを保存してください。各書き込みにはメモのテキストと、コーディングアノテーション識別子を設定した明示的な identifier を含めます。エンティティごとに、その都度記録してください。最後にまとめてメモを書き込んではいけません。

サーバーへのメモの書き込みが成功するたびに、JSONL の行を1つ $NOTES_SIDECAR に追加してください。サイドカーは軸コーディングで読み込まれるもので、サーバーへの往復はありません。

{"entity_kind":"trace","entity_id":"<trace-id>","note":"<text>","identifier":"<original identifier value, unsanitized>","ts":"<ISO-8601 UTC>"}

良いメモの条件

良くないメモ	良いメモ
「回答が間違っている」	「店舗の閉店時刻を午後6時と回答したが、ポリシーでは午後9時になっている」
「検索の問題」	「返品についての質問に対して、配送に関するドキュメントを取得した」

飽和状態

観察内容が新しくなくなったら終了します。直近のエンティティ10～15件で既出の問題が繰り返される、以前のメモを言い換えていることに気づく、またはスキップの数がメモの数を上回る、といった場合が目安です。収集を続けている間は、分類ごとにまとめるのを避けてください。すべてのトレースにアノテーションを付ける必要はありません。問題のないトレースにアノテーションを付けると、シグナルが薄まります。

フェーズ間：続行するか、提案する

飽和したら、軸足コーディングに進むかどうかを判断します。

• ユーザーがカテゴリ、分類体系、件数、評価対象、修正の優先順位を求めた場合、またはタスクを最初から最後までのエラー分析として示した場合は、そのままフェーズ 2 に進みます。
• それ以外の場合はここで止めます。メモから明らかになったことを要約し、軸足コーディングに進むかどうかを提案して、開始せずにユーザーの回答を待ちます。ここで実行を終える場合は、Wrapping up に従ってください。

フェーズ 2：軸足コーディング

オープンコーディングのメモを、エンティティの各ディメンションを個別に判定するアノテーションにまとめます。各アノテーションでは、あるディメンションについての一つの問いに、いくつかのラベルで回答します。エンティティのメモが触れているディメンションごとにアノテーションを一つ付与するため、トレースに二つまたは三つのアノテーションが付く場合があります。出力するのは、二つから四つのラベルを持つ、複数の狭いアノテーションです。無関係な懸念事項にまたがるラベルを持つ、幅広い単一の <app>_failure_mode アノテーションではありません。幅広いアノテーションはディメンションごとに集計できず、一つの項目を判定する評価で再利用できません。また、二つの点で失敗したエンティティに一つのラベルを無理に割り当てることになります。

プロセス

1. 設定 — コーディングアノテーション識別子をオープンコーディングの値に設定し、サイドカーパスを導出します（Resuming a run を参照）
2. 収集 — $NOTES_SIDECAR からこの実行のメモを読み取ります。ファイルが存在しない場合、この CWD ではこの識別子のオープンコーディングが実行されていません。停止して、まずフェーズ 1 を実行します。エンティティごとに最新の ts を優先します。不正な形式の行は、隣接する行に触れずに修正するか削除します。他のレビュアーや以前の実行のメモを含めるには、サーバーから取得します（予約名 note のアノテーション）。
3. グループ化 — エンティティについて同じ問いに答えるメモをまとめます（「適切なツールを選んだか？」「回答は取得した内容に根拠を置いていたか？」「依頼されたタスクを完了したか？」）。各グループはディメンションの候補です。メモのテキストを基にボトムアップで進め、ディメンションのリストから始めないでください。
4. 定義 — 各ディメンションについて、その問いを表すアノテーション名（tool_selection、answer_faithfulness）を付け、ラベルを選びます。メモに記述された失敗の結果に加え、後で評価が合格したエンティティにも同じアノテーションを適用できるよう、合格を表す値を一つ選びます。ディメンション内のラベルは相互に排他的です。一つのエンティティに対して二つのラベルが同時に当てはまる可能性がある場合、それらは別のディメンションに属します。
5. 属性付け — 各ディメンションがどのレベルに属するかを決定します（Choosing the level を参照）
6. 設定 — ディメンションごとに一つのカテゴリ型アノテーション設定を登録します（Annotation configs を参照）
7. 記録 — メモに記載されたエンティティごとに、そのメモが触れているディメンションにつき一つのアノテーションを書き込み、アノテーションごとにサイドカーの行を一つ追加します
8. 定量化 — $AXIAL_SIDECAR からディメンションごとのラベル数を数えます。現在の行を (annotation_name, axial_label) でグループ化し、(entity, annotation_name) ごとに最新の ts を優先します。サーバーへのクエリは行いません。サイドカーにはこの実行で書き込んだラベルだけが含まれます。

次元の設計

• アノテーション1つにつき質問は1つです。 名前が質問（tool_selection）、ラベルが回答（hallucinated_tool）です。ツールの選択とハーネスの安定性を一度に評価すると、アノテーションが2つ必要になります。
• ラベルセットは小さくします。 通常は2～4個です。ラベルが5個を超えるアノテーションは、ほぼ間違いなく複数の次元を扱っているため、分割してください。
• ラベルは構成要素ではなく、結果を表します。 retrieval や tool_use は次元名であり、ラベルではありません。ラベルがシステムの一部を表す名詞になっている場合は、それを独立したアノテーションに昇格させ、結果をラベルとして定義してください。
• 1回の実行から得られる次元は少数です。 通常は3～6個です。各メモは少なくとも1つの次元のラベルに対応する必要があります。どこにも当てはまらないメモがある場合は、新しい次元を設けるか、既存の次元の定義が狭すぎないかを確認してください。
• エージェントの評価とインフラを分けます。 プロバイダーのエラー、永続化の失敗、UIのクラッシュも重要な所見ですが、エージェントの振る舞いではありません。モデルの誤りと並べて記載するのではなく、独自の次元を設けてください。

粒度の選択

軸足コーディングでは、特に指定がなければオープンコーディングの単位を引き継ぎますが、アノテーションは、それを根拠づけたメモとは異なるレベルに設定できます。どちらの方向にも設定できます。たとえば、「返品について聞かれたのに配送について回答した」というトレースレベルのメモは、検索が一貫して原因だと判明した時点で、検索スパンに対するスパンレベルの retrieval_relevance ラベルにつながります。1ターンだけの混乱に関するトレースレベルのメモは、「ターンをまたいで文脈を追跡できない」というパターンが明らかになった時点で、セッションレベルの context_tracking ラベルにつながります。また、セッションレベルのドリフトに関するメモから、特定の1ターンを原因として特定し、トレースレベルのラベルを付けることもできます。各アノテーションは、その次元が実際に関係するレベルに設定してください。1回の実行でも、次元によってレベルが異なる場合があります。

メモを取ったエンティティを分類してください。候補の抽出元は $NOTES_SIDECAR であり、ラベルはメモのテキストと前後の文脈を読んでから記入します。エラー状態を基準にエンティティを選択しないでください。そうすると、発生した例外しか捉えられず、幻覚、不適切なトーン、検索ミスといった大半の失敗パターンが除外されます。

アノテーション設定

次元が安定したら（書き込みごとではなく、「グループ化」と「定義」の後に）、記録を始める前に次元ごとにカテゴリ型アノテーション設定を1つ登録します。

1. 各設定には次元名を付けます。 設定名はアノテーション名（tool_selection、answer_faithfulness）と同じにします。これにより、Phoenixが両者を関連付けます。汎用的な category は使わず、すべての次元をまとめた設定も作成しないでください。
2. プロジェクトに既存のアノテーション設定がないか確認します。 すでに同じ次元を評価する設定がある場合は、その名前とラベルを再利用し、メモから明らかになった結果が不足している場合に限り、値を追加してください。新しい名前で重複に近い設定を作成しないでください。
3. 各設定を作成または更新し、その次元の最終的なラベルを値として設定して、プロジェクトに関連付けます。

設定がなくてもアノテーションの記録は問題なく行えますが、設定があることで、その次元がPhoenix UIで正式な項目になります。人間のアノテーターは自由記述ではなくドロップダウンからラベルを選べるようになり、後続の実行でも語彙が統一され、表記のばらつきを防げます。記録中に新しいラベルが出てきた場合は、そのラベルを使って記録する前に、該当する次元の設定に追加してください。

優れたアノテーションとは

アノテーションが後で役立つのは、フィルタリング、集計、監査ができる場合に限られます。そのため、次の点に注意してください。

1. 次元に名前を付け、結果をラベルにします。 tool_selection = hallucinated_tool とし、hallucinated_tool = true や failure_mode = hallucinated_tool とはしません。
2. アノテーションごとに次元は1つにします。 関連性と忠実性の両方を判断するなら、アノテーションは2つ必要です。ツールの選択とタスクの完了を判断する場合も同様です。
3. 責任を持つエンティティにアノテーションを付けます。 検索にはリトリーバーのスパン、出力にはLLMのスパンを使います。エンドツーエンドの判断に限り、トレースまたはセッションを使います。
4. 最初に発生した失敗にラベルを付けます。 下流への影響は、それ自体が独立した問題である場合に限り、別途ラベルを付けます。
5. スコアよりラベルを優先します。 少数のラベルセットを一貫して適用すれば、きれいに集計できます。スコアは、設定で尺度が定義されている場合にのみ使用します。
6. 説明に根拠を記載します。 「キャンセルに関する質問に対して、オンボーディングのドキュメントを検索した」とし、「検索が悪かった」とはしません。
7. 実行間で名前とラベルを安定させます。 _v2 の接尾辞を付けたり、名前が合うからといって別のプロジェクトの設定を流用したりしません。

ラベルの記録

各エンティティについて、メモが扱う各次元ごとに、次の内容でアノテーションを1つ記録します。

• name：その次元のアノテーション名。例：retrieval_relevance
• label：結果。例：off_topic
• explanation（任意）：例：「返品について質問されたが、配送のドキュメントを検索した」
• annotator kind：独自の判断には LLM、ユーザーが提示した判断に限り HUMAN
• identifier：コーディングアノテーションの識別子

サーバーは任意のスコアも受け付けます。書き込みは (entity_id, name, identifier) をキーにアップサートされるため、名前が異なれば、同じ識別子のもとで1つのエンティティに複数のアノテーションを付けられます。サーバーの既定の書き込みモードでは、処理が非同期でキューに登録されます。ツールで同期モードが利用できる場合は、続行する前に行が適用されるよう、そちらを優先してください。

書き込みのたびに、$AXIAL_SIDECAR にJSONLの行を1つ追加します。アノテーションごとに1行記録するため、2つの次元でラベル付けされたエンティティには、2行記録します。

{"entity_kind":"trace","entity_id":"<trace-id>","annotation_name":"<annotation-name>","axial_label":"<label>","explanation":"<optional explanation>","identifier":"<original identifier value, unsanitized>","ts":"<ISO-8601 UTC>"}

entity_kind（"trace"、"span"、または "session"）は、アノテーションを書き込んだレベルに対応します。identifier はサニタイズ前の値です。サニタイズ後の値はファイル名にのみ使われます。ラベルを修正するには、該当する行を置き換えるか、新しい行を追加します。(entity_kind, entity_id, annotation_name) ごとに最新の ts が現在の値となり、サーバーでのアップサートと一致します。

次元の例

各キーがアノテーション名で、その値がそのアノテーションのラベルです。1回の実行で生成するのは、このうち数個であり、ツリーではありません。

tool_selection: [correct, wrong_tool, hallucinated_tool, unnecessary_call]
retrieval_relevance: [relevant, off_topic, nothing_retrieved]
answer_faithfulness: [grounded, invented_fact, invented_citation]
context_tracking: [kept, ignored_preference, goal_drift]
task_completion: [completed, partial, abandoned]

優れた次元とは

• 相互排他的な回答が得られる1つの質問をすること。2つのラベルが同時に当てはまる場合は、次元を分けます。
• 判断する挙動に基づいた名前を付けること。結果はラベルに含めます（「tool_selection」=「wrong_tool」とし、「bad_output」とはしません）。
• 修正につながること。失敗ラベルへの対処法を挙げられない場合、その次元は曖昧すぎます。
• データに基づいていること。事前の思い込みではなく、実際のメモの文面から導き出します。

完了時

フェーズ 1 またはフェーズ 2 の後に実行が終了した場合、いずれにも適用されます。

軸方向コーディングを実行した場合は、作成したディメンションを列挙し、それぞれについてアノテーション設定を再利用、拡張、または作成したかを記載します。評価基準を判断するのはユーザーです。各ディメンションは、プロジェクトの設定ページ <endpoint>/projects/<project-node-id>/config にリンクします。このページには、そのプロジェクトのアノテーションの横にアノテーション設定が一覧表示されます。ほかのすべてのプロジェクトの設定も混在する、インスタンス全体のアノテーション設定ページにはリンクしないでください。

Phoenix UI のリンクをユーザーに共有します。レベルごとに 1 つ、つまりスパン、トレース、セッションのリンクを共有します。各リンクには、この実行のメモまたはアノテーションが実際に含まれ、この実行の作業で絞り込まれている必要があります。該当するデータがないレベルは省略します。各タブは独自の検索パラメーターからフィルターを読み込みます。認識できないパラメーターや誤記されたパラメーターは、通知なく無視され、フィルターなしのテーブルが表示されます。

コーディングアノテーション識別子で絞り込みます。アノテーションアクセサーは .label、.score、.explanation とともに .identifier を公開します。これにより、各リンクにはこの実行のメモと軸方向アノテーションだけが表示されます。そのレベルで記述したディメンションごとに <annotation-name> 条件を 1 つ追加し、or でつなぎます。軸方向コーディングを実行していない場合は、それらを省略します。

アノテーション対象のレベル	タブと検索パラメーター	フィルター式
span	/spans?spanFilterCondition=	annotations['note'].identifier == '<id>' or annotations['<annotation-name>'].identifier == '<id>'
trace	/traces?traceFilterCondition=	trace_annotations['note'].identifier == '<id>' or trace_annotations['<annotation-name>'].identifier == '<id>'
session	/sessions?sessionFilterCondition=	session_annotations['note'].identifier == '<id>' or session_annotations['<annotation-name>'].identifier == '<id>'

各式を URL エンコードして、対応するタブのパラメーターに設定します。

<endpoint>/projects/<project-node-id>/<tab>?<param>=<encoded-expression>

個別の所見を引用するときは、絞り込み済みのテーブルを共有するだけでなく、アノテーションが付いたエンティティにも直接リンクします。トレースの場合は、<endpoint>/projects/<project-node-id>/traces/<otel-trace-id> を使用します。スパンの場合は、そのトレース URL に selectedSpanNodeId=<span-node-id> を指定し、アノテーションが付いたスパンが選択された状態で開くようにします。取得したデータからスパンの Relay ノード ID と、対応する OpenTelemetry トレース ID を解決してください。選択パラメーターには OpenTelemetry スパン ID を指定できません。timeRangeKey=30d などの既存の検索パラメーターを保持し、追加する値は URL エンコードしてください。

実行の破棄 — 破壊的な操作のため、ユーザーの明示的な確認がある場合に限ります。トレース、スパン、セッションのそれぞれについて、コーディングアノテーション識別子で絞り込んだプロジェクトのアノテーションを削除します。各ディメンションは同じ識別子を共有しているため、これによりすべてのディメンションのラベルが一度に削除されます。サーバーは、この一括削除を許可するために、明示的な全件削除フラグ（または時間範囲）を必須とします。識別子によるフィルターは対象を絞り込みますが、それ単独では削除を許可しません。その後、$NOTES_SIDECAR と $AXIAL_SIDECAR を削除します。種類ごとの削除では、メモと軸方向アノテーションが同じ基盤のアノテーションテーブルを共有しているため、両方が一緒に削除されます。