Codexのセッション分析に必要なデータを調べた

はじめに

Codexで開発していると、同じファイルの再読み込みや過剰な調査など、無駄な処理が発生することがあります。

こうした無駄を減らすために、過去のセッションを分析し、次回以降の開発効率を改善できないかと考えました。

今回は、分析に必要な情報を整理し、Codexが記録しているデータから適切なデータソースを検討しました。

想定読者

• Codex CLIで開発している方
• Codexの無駄な処理やトークン消費を減らしたい方

結論

• Codexのセッション分析には、主にRollout JSONL・OpenTelemetry（OTel）・SQLiteを利用できる
• 無駄な処理とその原因を調べるためには、Rollout JSONLを使うのが効果的そう

1. 何を分析するべきか

今回の目的は、成果物の品質を維持しながらトークン消費量を減らすことです。

そこで、削減対象となる無駄な処理を5種類に分類しました。

種類	具体例	分析に必要な情報
不要な処理	関係ないファイルを読む	依頼内容・処理内容
重複した処理	同じファイルを何度も読む	実行履歴・再実行の理由
非効率な処理	件数確認だけなのに大量出力する	処理目的・コマンド・出力内容
手戻り	仕様を確認せず実装し、修正し直す	指示・変更内容・修正経緯
過剰な処理	軽微な変更で全テストを繰り返す	変更範囲・テストの実行理由

ここで重要なのは、処理の実行履歴だけでは無駄と判断できないことです。

例えば、同じファイルを3回読んでいても、途中で変更されていれば再読み込みが必要だったかもしれません。

無駄を判断するには、実行内容に加えて、なぜその処理を実行したのかが分かる前後の文脈も必要です。

2. Codexが記録しているデータを調べる

必要な情報を取得できるデータソースとして、次の3つを比較しました。

データ	記録内容	主な用途
Rollout JSONL	会話・ツール呼び出し・実行結果・トークン情報	処理の経緯や原因の分析
OpenTelemetry（OTel）	実行イベント・処理時間・集計値	遅延や実行時間の分析
SQLite	セッション管理情報・内部ログなど	セッション検索・内部診断

OTelはLogs・Traces・Metricsを使って実行状況を観測する仕組みで、利用には設定が必要です。

参考：Codex公式ドキュメント：Observability and telemetry

どのデータを使うべきか

今回知りたいのは、ツールの実行時間よりも、どの処理が無駄で、なぜ発生したのかです。

Rollout JSONLには、ツールの実行履歴だけでなく、ユーザーの指示やCodexの応答も記録されています。

処理の前後関係を追いやすいため、今回はRollout JSONLを使うことにしました。

3. Rollout JSONLの中身を調べる

Rollout JSONLには、主に次の情報が記録されています。

• セッション情報：セッションID・モデル・作業ディレクトリなど
• 実行履歴：ユーザーの指示・Codexの応答・ツール呼び出しと結果
• トークン使用量：入力・出力・キャッシュ済みトークン数など

3-1. 保存場所と確認方法

Rollout JSONLは、通常以下の場所に保存されています。

~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl

Windowsでは、PowerShellで直近のファイルを取得できます。

$file = Get-ChildItem "$HOME\.codex\sessions" -Recurse -Filter "rollout-*.jsonl" |
    Sort-Object LastWriteTime -Descending |
    Select-Object -First 1

先頭5行を確認するには、次のコマンドを実行します。

Get-Content $file.FullName -TotalCount 5

3-2. データ構造

JSONL（JSON Lines）は、1行に1つのJSONオブジェクトを記録する形式です。

Rollout JSONLでは、各行のtypeで記録内容を区別します。

type	内容
session_meta	セッションID・作業ディレクトリ
turn_context	モデル・実行環境
response_item	Codexの応答・ツール呼び出し・結果
event_msg	ユーザー入力・実行イベント・トークン情報
token_usage_record	応答ごとのトークン使用量

※記録形式はCodexのバージョンによって異なります。

3-3. ツール呼び出しと実行結果

例えば、Codexがmain.tsを読み込むと、次のような記録が残ります（説明用に一部のフィールドを省略しています）。

① ツール呼び出し

{
  "type": "response_item",
  "payload": {
    "type": "function_call",
    "name": "exec_command",
    "arguments": "{\"cmd\":\"Get-Content main.ts\"}",
    "call_id": "call_01"
  }
}

② 実行結果

{
  "type": "response_item",
  "payload": {
    "type": "function_call_output",
    "call_id": "call_01",
    "output": "export function main() { ... }"
  }
}

ツール呼び出しと実行結果は別々に記録されますが、同じcall_idで紐付けられています。

これにより、どのツールで何を実行し、どんな結果が返されたのかを追跡できます。

さらに前後のメッセージを調べれば、実行に至った経緯も確認できます。

※内部推論がすべて記録されるわけではないため、実行理由は文脈から推定する場合もあります。

3-4. トークン使用量

Rollout JSONLには、次のトークン情報も記録されています。

項目	内容
input_tokens	入力トークン数
cached_input_tokens	キャッシュ済み入力トークン数
output_tokens	出力トークン数
reasoning_output_tokens	推論に使用した出力トークン数
total_tokens	合計トークン数

※キャッシュ済み入力はinput_tokensに、推論トークンはoutput_tokensに含まれます。

新しいバージョンではtoken_usage_record、従来の形式ではevent_msg内のtoken_countなどから取得できます。

これらを使えば、セッション全体やモデル応答ごとのトークン使用量を調べられます。

ただし、個々のツール呼び出しによる消費量を直接示すものではないため、ツールの出力サイズなども参考にします。

3-5. 無駄な処理を分析できるか

Rollout JSONLには、最初に挙げた5種類の無駄を調べるための基本情報が揃っています。

例えば、重複した処理なら同じコマンドの実行履歴を探し、手戻りなら実装・テスト・修正の経緯を追跡できます。

必要に応じてGitの変更履歴なども参照すれば、処理の必要性や原因をさらに詳しく調べられます。

4. 複数セッションの分析にも使えるか

複数のRollout JSONLを集計すれば、セッションを横断した分析も可能です。

例えば、5〜10セッションのトークン使用量やツール実行履歴を比較し、共通する非効率な処理を探せます。

ただし、タスクの難易度や作業内容は異なるため、トークン数だけで効率を比較せず、実行内容も確認する必要があります。

今後

Rollout JSONLは分析に必要な情報が豊富な一方、会話やツールの実行結果など、大量のデータを含みます。

これをそのままCodexに読み込ませると、分析自体に大量のトークンを使う可能性があります。

次回は、必要な情報だけを段階的に取得するスクリプトを作成し、実際のセッションを分析してみます。