トレース

Trackioのトレースは、ユーザーのリクエスト、アシスタントの応答、およびそれらを生成した操作をキャプチャします。ダッシュボードのTracesページを開くと、リクエストの検索、モデルおよびツール操作の確認、レイテンシ、トークン、コスト、ステータスの合計値の表示を行うことができます。

会話のログを記録する

OpenAIスタイルのメッセージを指定して、Traceをtrackio.log()に渡します:

import trackio

trackio.init(project="research-agent")
trackio.log(
    {
        "trace": trackio.Trace(
            messages=[
                {"role": "user", "content": "Find agent training datasets."},
                {"role": "assistant", "content": "Here are three datasets..."},
            ],
            metadata={"session_id": "session-123", "environment": "production"},
        )
    }
)
trackio.finish()

メッセージにはtool_callsとtoolの結果を含めることができます。トレースに明示的なスパンがない場合、ダッシュボードはこれらの呼び出しと結果をツール操作としてペアリングし、確認しやすくします。

実行スパンを追加する

タイミング、階層構造、モデルの使用状況、コスト、または操作のステータスが必要な場合は、spansを使用します。各スパンは辞書です。最小限のフィールドはid、name、kindです。

trackio.Trace(
    messages=messages,
    spans=[
        {
            "id": "research",
            "name": "answer-research-question",
            "kind": "span",
            "start_time": "2026-08-19T12:00:00Z",
            "end_time": "2026-08-19T12:00:03Z",
            "status": "success",
        },
        {
            "id": "generation-1",
            "parent_id": "research",
            "name": "provider-request",
            "kind": "generation",
            "start_time": "2026-08-19T12:00:00Z",
            "end_time": "2026-08-19T12:00:01.2Z",
            "model": "my-model",
            "input": {"messages": messages},
            "output": {"text": "I will search for datasets."},
            "usage": {"input_tokens": 8439, "output_tokens": 188},
            "cost_usd": 0.0042,
            "status": "success",
        },
        {
            "id": "tool-1",
            "parent_id": "research",
            "name": "hf search",
            "kind": "tool",
            "start_time": "2026-08-19T12:00:01.3Z",
            "end_time": "2026-08-19T12:00:02Z",
            "input": {"query": "agent training datasets"},
            "output": {"datasets": ["example/dataset"]},
            "status": "success",
        },
    ],
)

サポートされているスパンフィールド:

トレースのレイテンシーは、最も早いスパンの開始から最も遅いスパンの終了までの実時間です。end_time を持つスパンがない場合、代わりに最も長い単一の duration_ms が使用されます。トークン数とコストの合計は、個々のスパンの値を足し合わせたものであり、usage および cost_usd は親スパンの集計値ではなく、ローカルな操作を記述すべきです。親スパンが子スパンの合計を繰り返すと、二重計上が発生します。Trackio はモデルの価格カタログを管理していません。計装処理で実際のコストを供給する必要があります。

status が error または failed の場合、または error を保持している場合、そのスパンは失敗として報告されます。メッセージから派生したスパンでは、メッセージが is_error、error、またはエラーの status を設定している場合、ツール結果はその操作を失敗とマークします。OpenAI 形式のツール結果には成功シグナルが含まれないため、これらの操作は成功と仮定するのではなく、ステータスなしのままにされます。

CLIからトレースをインスペクトする

ダッシュボードはトレースを読み取る唯一の方法ではありません。CLIはローカルデータに対して、または--spaceを指定してSpaceに対して動作します:

trackio list traces --project research-agent
trackio list traces --project research-agent --search "rate limit"
trackio get trace --project research-agent --trace-id <id>
trackio get trace-summary --project research-agent

trackio get trace は、スパンごとのレイテンシ、モデル、トークン数、コスト、エラーを表示する実行ツリーを出力します。trackio get trace-summary は、すべてのスパンを操作名ごとにグループ化し、呼び出し回数、エラー、平均および最悪ケースのレイテンシ、トークン使用量、コストを報告します。コストの大部分を占める操作や、最も頻繁に失敗する操作を特定するのに役立ちます。両方とも--jsonを受け付けます。

それ以外のものについては、spansはJSONカラムであるため、json_eachがtrackio query projectと組み合わせて使用できます:

trackio query project --project research-agent --sql "
SELECT json_extract(s.value, '\$.name') AS operation,
       SUM(COALESCE(json_extract(s.value, '\$.usage.input_tokens'), 0)) AS input_tokens
FROM traces, json_each(traces.spans) AS s
GROUP BY operation ORDER BY input_tokens DESC"

Hugging Face Hubでのトレースの表示

記録されたすべてのトレースは、Hub のエージェントトレースビューアがレンダリングする形式で、エージェントセッションの .jsonl ファイルとしても書き出されます。Trackio が Space で実行されている場合、バケットは /data にマウントされるため、これらのファイルはバケット内の traces/{project}/{run}/{trace_id}.jsonl に保存されます。バケットのファイルブラウザから 1 つを開くと、会話、そのツール呼び出し、およびそれらの結果をステップバイステップで確認できます。

Trackio は Pi のセッション形式（バージョン 3）を出力します。これは Hub がネイティブでサポートしています。Hub には Session Trace Simple Format もドキュメント化されていますが、この仕様に従って書き出されたファイルは、現在のところビューアでレンダリングされません。

セッションファイルはレンダリングの成果物であり、真のソースではありません。traces テーブルが権威ある情報源であり、このページの他のすべて — 検索、スパンツリー、trace-summary、直接の SQL 実行 — はそこから読み取ります。セッションファイルが保持するのは、ビューアが表示できる詳細をスパンから補強した線形な会話です:

トークン使用量は、それを生成したアシスタントのターンに紐付けられ、すべてのターンで繰り返し表示されることはありません。これにより、ビューアでの二重カウントを防止しています。スパンの階層構造、duration_ms、スパンごとのmetadata、およびツール以外のスパンのkindは、このフォーマットには該当する場所がなく、SQLite に保持されます。

セッションファイルはtrackio/プレフィックスの内部ではなく隣に配置されるため、バケットをローカルに同期するtrackio CLI コマンドは、すべてのトレースの2番目のコピーを取得しません。TRACKIO_TRACE_SESSIONS_DIRを設定することで、セッションファイルを別の場所に書き出すことができます。

トレースレベルのメタデータ

Spans は、レイテンシ、コスト、ステータスの優先的な情報源です。トレースに Spans が存在しない場合、または Spans がこれらの値を省略している場合は、ダッシュボードはこれらの metadata キーにフォールバックします:

検索

トレース検索は、メッセージの内容、トレースのメタデータ、および各スパンのid、name、kind、model、status、error、metadataに一致します。スパンのinputおよびoutputペイロードはインデックス付けされていません。これらは生成のたびに会話全体を繰り返し含めることが多いため、インデックス付けすると検索価値がほとんどないにもかかわらず、保存されるトレースのサイズが膨大になるためです。

メッセージ、メタデータ、スパンのインプット、またはスパンのアウトプット内のネストされたTrackioメディア値はトレースとともに保存され、画像はインスペクター内でインライン表示されます。