mlflow-trace-analysis

MLflow トレースを分析する

トレース ID またはセッション ID、設定済みのバックエンド、報告された動作、期待される結果を使用します。取得済みのトレースは再利用します。複数ターンの会話については、セッション分析を参照してください。

前提条件

不明なトレース ID を検索する前に、フィルター、時間範囲、ページネーションについてトレースの取得を読んでください。取得済みのトレースは再利用してください。このスキルがインストールされていない場合は、検索ガイドとインストール済み CLI のヘルプを使用してください。

既存の証拠を優先してください。利用可能なトレースがない場合に限り、安全であれば通常のインストルメント済みエントリーポイントを通じて一度だけ再現します。それ以外の場合は、証拠が不足していることを報告してください。HUMAN フィードバックを記録するのは、許可を得ており、特定済みのトレースに関連付けられている場合に限ります。

手順 1：トレースを取得する

完全な JSON を一度だけファイルに取得します。パイプ経由の CLI 出力が大きいと、実行ツールによって切り詰められることがあります。get に --output フラグは不要です。ネストされたスパンの診断には --extract-fields を使用しないでください。

mlflow traces get --trace-id <TRACE_ID> > /tmp/trace.json

手順 2：スパンツリーを調べる

状態、評価、親リンクを要約します。

jq '{state: .info.state,
     spans: [.data.spans[] | {span_id, parent_span_id, name, status}],
     error_spans: [.data.spans[] | select(.status.code == "STATUS_CODE_ERROR") | .name],
     assessments: .info.assessments}' /tmp/trace.json

手順 3：フィードバックを読む

仮説を立てる前に、フィードバックのソース、値、トップレベルの根拠、有効性、スコープを読み取ります。HUMAN フィードバックは報告された体験を示すものであり、スパンと照合して裏付けてください。LLM_JUDGE/CODE フィードバックは誤っていたり、設定が不適切だったりする可能性があります。feedback.error はスコアリングの失敗を意味し、アプリケーションの失敗を意味するものではありません。エラーまたは上書きされた判定は、品質に関する結論から除外してください。正当なゼロ／false の値は有効です。期待値は望ましい出力を示すラベルであり、スコアではありません。

手順 4：入力と出力をたどる

ルートから最初の相違点まで、実際の入力と出力をたどり、その後の影響を確認します。MLflow スパンの生の I/O は通常、attributes["mlflow.spanInputs"] / attributes["mlflow.spanOutputs"] 内のシリアライズ済み JSON です。解釈する前にパースしてください。ルートが空のラッパーの場合は、子孫を調べます。その他の OTel ソースやバージョンでは、このスキーマを前提とせず、生のキーを調べてください。

手順 5：エラーとパフォーマンスを確認する

例外イベントとステータスメッセージを確認します。OK は実行の成功を意味し、出力の正しさを意味するものではありません。STATUS_CODE_UNSET 自体はエラーではありません。パフォーマンスを調べる際は、外側のラッパー、重複する子処理、インストルメントされていない区間を区別してください。名前が繰り返されているだけでは、リトライがあった証拠にはなりません。記録されたトークン使用量を確認し、コストを推測したり、トークン数の急増だけで注入があったと判断したりしないでください。

手順 6：ソースを確認する

利用可能な場合は、決定的なスパンで観測されたデータを、関連するソース／設定と照合します。関数名は手掛かりであり、自動ログ記録された名前はフレームワークの慣例に従います。観測された事実、考えられる原因、不足している証拠を区別してください。診断だけを目的として、コードを編集したり、スコアラーを作成したり、評価を実行したりしないでください。

取得の失敗、裏付けのない回答、その後の伝播については、返金ポリシーの証拠表を参照してください。

検証

観測された動作と期待される動作、トレース ID と決定的なスパン ID、証拠の連鎖、確信度、最小限の対処法を報告します。プレビューだけに頼らず、実際のスパン I/O とフィードバックの意味に基づいて主張を確認してください。証拠が不足している場合は、不確実性を解消するために必要な情報を示します。仮説を確認済みの根本原因として扱わないでください。

参考資料

• フィールド、単位、CLI と SDK の表現、OTel 属性、評価の解釈については、トレース構造を参照してください。
• 上限付きバッチ、繰り返し発生する障害、コンポーネントのボトルネックについては、複数トレースの分析を参照してください。
• 複数ターンにわたる伝播については、セッション分析を参照してください。
• ユーザーが実装を依頼した場合は、インストール済みであれば診断結果とトレース ID を mlflow-agent-improvement に渡してください。調査自体は証拠と推奨事項の提示までとします。