Claude Code ガイド

Appearance

トランスクリプトエントリでの最終トークン使用量の記録改善 ​

原文（日本語に翻訳） ​

トランスクリプトエントリを改善し、ストリーミングのプレースホルダーではなく最終的なトークン使用量を保持するようになりました。

原文（英語） ​

Improved transcript entries to carry final token usage instead of streaming placeholders

概要 ​

これまでトランスクリプトに記録されるトークン使用量は、ストリーミング中の中間値（プレースホルダー）が使われることがありました。今回の改善により、トランスクリプトエントリには応答完了後の正確な最終トークン使用量が記録されるようになりました。これにより、セッションのコストや使用量の分析がより正確に行えます。

基本的な使い方 ​

特別な操作は不要です。トランスクリプトを出力・エクスポートすると、自動的に正確なトークン使用量が含まれるようになります。

bash
# トランスクリプトをエクスポート
/export transcript.json

# エクスポートされた JSON に正確なトークン使用量が含まれる
# {
#   "role": "assistant",
#   "content": "...",
#   "usage": {
#     "input_tokens": 1234,    ← 正確な最終値
#     "output_tokens": 567     ← 正確な最終値
#   }
# }

実践例 ​

セッションのコスト分析 ​

各会話のトークン使用量を正確に把握することで、コストの見積もりや最適化が可能になります。

bash
# トランスクリプトをエクスポートして分析
/export session-transcript.json

# Python でトークン使用量を集計
import json

with open('session-transcript.json') as f:
    transcript = json.load(f)

total_input = sum(
    entry.get('usage', {}).get('input_tokens', 0)
    for entry in transcript
    if entry.get('role') == 'assistant'
)
total_output = sum(
    entry.get('usage', {}).get('output_tokens', 0)
    for entry in transcript
    if entry.get('role') == 'assistant'
)

print(f"入力トークン合計: {total_input}")
print(f"出力トークン合計: {total_output}")
# 改善後: 正確な値が表示される（改善前: プレースホルダー値が混在する場合があった）

OTEL メトリクスとの連携 ​

OTEL トレーシングと組み合わせることで、正確なトークン使用量をメトリクスとして記録できます。

bash
# OTEL 設定
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_SERVICE_NAME="claude-code"

# 正確なトークン使用量が OTEL スパンの属性として記録される
claude

# Grafana などで正確なトークン使用量のメトリクスを可視化

長いセッションでのトークン追跡 ​

複数のターンにわたる長いセッションでも、各ターンのトークン使用量が正確に記録されます。

bash
# セッションを通じて会話し、各ターンのトークンを追跡
claude

# 会話 1: 「このコードを解析してください」
# → usage: { input_tokens: 234, output_tokens: 456 }

# 会話 2: 「改善案を提案してください」  
# → usage: { input_tokens: 890, output_tokens: 321 }

# 改善後: ストリーミング完了後の正確な値が各エントリに記録される

SDK を使ったトークン使用量の監視 ​

Claude Code SDK を組み込んだアプリケーションでも、正確なトークン使用量を取得できます。

python
# SDK でのトランスクリプト取得例
import json

# /export で保存したトランスクリプトを読み込む
with open('transcript.json', 'r') as f:
    data = json.load(f)

# 各アシスタントメッセージのトークン使用量を確認
for entry in data:
    if entry.get('role') == 'assistant':
        usage = entry.get('usage', {})
        print(f"ターン: input={usage.get('input_tokens')}, output={usage.get('output_tokens')}")
# 改善後: 全エントリで正確な最終値が取得できる

注意点 ​

  • この改善はトランスクリプトのデータに記録される値の精度向上です。UI 上のトークン表示への影響は別途確認してください。
  • 過去のトランスクリプトファイル（この改善以前にエクスポートされたもの）の値は修正されません。
  • ストリーミング中（応答生成中）は中間値が表示される場合がありますが、完了後のトランスクリプトには最終値が記録されます。
  • トークン使用量は API の使用量として課金に影響するため、正確な値の記録はコスト管理において重要です。

関連情報 ​