Claude Code ガイド

Appearance

原文（日本語訳） ​

OTelイベントとトレーススパンに、fast modeの可視化のためのspeed属性を追加しました。

原文（英語） ​

Added speed attribute to OTel events and trace spans for fast mode visibility

概要 ​

Claude Code 2.1.39では、OpenTelemetry（OTel）のイベントとトレーススパンにspeed属性が追加され、fast modeが有効な場合の動作を監視・分析できるようになりました。これにより、通常モードとfast modeのパフォーマンス比較や、コスト分析が容易になりました。

fast modeとは ​

fast modeは、同じClaude Opus 4.6モデルを使用しつつ、より高速な出力を提供するモードです。/fastコマンドで切り替えられます。

bash
# fast modeの切り替え
/fast

# fast mode: ON → より速い応答
# fast mode: OFF → 通常速度

speed属性の仕様 ​

属性値 ​

  • speed: "normal" - 通常モード
  • speed: "fast" - fast mode有効

適用されるイベント ​

  1. claude_code.user_prompt - ユーザープロンプト送信時
  2. claude_code.tool_result - ツール実行完了時
  3. claude_code.api_request - API リクエスト時
  4. すべてのトレーススパン

実践例 ​

OpenTelemetryの設定 ​

bash
# OTel エクスポートの有効化
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# Claude Codeを起動
claude

SigNozでのモニタリング ​

bash
# Docker Compose で SigNoz を起動
git clone https://github.com/SigNoz/signoz
cd signoz/deploy
docker-compose up -d

# Claude Code のテレメトリを送信
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
claude

SigNozダッシュボードでクエリを実行:

sql
-- fast mode と通常モードの応答時間比較
SELECT
  attributes['speed'] as mode,
  AVG(duration_ms) as avg_response_time,
  COUNT(*) as request_count
FROM traces
WHERE service_name = 'claude-code'
  AND span_name = 'claude_code.api_request'
GROUP BY attributes['speed']

Grafanaでの可視化 ​

yaml
# prometheus.yml の設定
scrape_configs:
  - job_name: 'claude-code'
    static_configs:
      - targets: ['localhost:9090']

Grafanaダッシュボードのクエリ例:

promql
# fast mode使用率
sum(claude_code_requests{speed="fast"})
/
sum(claude_code_requests)

# モード別の平均レイテンシ
avg(claude_code_latency_ms) by (speed)

Datadogでの分析 ​

bash
# Datadog Agent経由でメトリクスを送信
export DD_AGENT_HOST=localhost
export DD_TRACE_AGENT_PORT=8126
export OTEL_EXPORTER_OTLP_ENDPOINT=http://$DD_AGENT_HOST:4317

claude

Datadogでのクエリ:

avg:claude_code.response_time{speed:fast}
avg:claude_code.response_time{speed:normal}

Honeycombでの詳細分析 ​

bash
# Honeycomb への送信設定
export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=YOUR_API_KEY"

claude

Honeycombクエリビルダー:

BREAKDOWN: speed
CALCULATE: P50(duration_ms), P95(duration_ms), P99(duration_ms)
FILTER: span.name = "claude_code.api_request"

パフォーマンス分析の実例 ​

レイテンシ比較 ​

python
# Python スクリプトで分析
import pandas as pd
from opentelemetry import trace

# トレースデータを取得
traces = get_traces(service_name="claude-code")

df = pd.DataFrame(traces)

# モード別の統計
stats = df.groupby('speed')['duration_ms'].describe()
print(stats)

# 出力例:
#         count   mean    std    min    25%    50%    75%    max
# speed
# fast     1000   245    52     180    210    240    275    380
# normal   1000   380    78     250    320    370    430    590

コスト効率分析 ​

javascript
// Node.js での分析例
const { traces } = require('./telemetry-data.json');

const analysis = traces.reduce((acc, trace) => {
  const mode = trace.attributes.speed;
  acc[mode] = acc[mode] || { count: 0, totalCost: 0 };
  acc[mode].count++;
  acc[mode].totalCost += trace.attributes.api_cost;
  return acc;
}, {});

Object.entries(analysis).forEach(([mode, data]) => {
  console.log(`${mode} mode:`);
  console.log(`  Average cost: $${(data.totalCost / data.count).toFixed(4)}`);
  console.log(`  Total requests: ${data.count}`);
});

カスタムダッシュボード ​

json
{
  "dashboard": {
    "title": "Claude Code Performance by Speed Mode",
    "panels": [
      {
        "title": "Response Time Comparison",
        "targets": [
          {
            "expr": "histogram_quantile(0.5, claude_code_duration_ms{speed=\"fast\"})",
            "legendFormat": "Fast Mode P50"
          },
          {
            "expr": "histogram_quantile(0.5, claude_code_duration_ms{speed=\"normal\"})",
            "legendFormat": "Normal Mode P50"
          }
        ]
      },
      {
        "title": "Mode Usage Distribution",
        "targets": [
          {
            "expr": "sum(claude_code_requests) by (speed)",
            "legendFormat": "{{speed}}"
          }
        ]
      }
    ]
  }
}

注意点 ​

  • テレメトリの有効化: CLAUDE_CODE_ENABLE_TELEMETRY=1が必要です
  • プライバシー: プロンプト内容は含まれません。長さのみが記録されます
  • コスト: fast modeと通常モードの料金は同じですが、使用パターンによってコストが変わる可能性があります
  • エクスポーター設定: OTLPエンドポイントを適切に設定してください

トラブルシューティング ​

テレメトリが送信されない ​

bash
# デバッグモードで確認
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOG_LEVEL=debug
claude

# OTLP エンドポイントの確認
curl -v http://localhost:4317

speed属性が表示されない ​

Claude Code 2.1.39以降を使用していることを確認してください。

bash
claude --version
# 出力: Claude Code 2.1.39 以上であることを確認

メトリクスの確認 ​

bash
# Prometheus形式でエクスポート
export OTEL_METRICS_EXPORTER=prometheus
export OTEL_EXPORTER_PROMETHEUS_PORT=9090

# メトリクスエンドポイントを確認
curl http://localhost:9090/metrics | grep claude_code

関連情報 ​