Claude Code ガイド

Appearance

原文（日本語） ​

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

原文（英語） ​

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

概要 ​

Claude Code v2.1.41では、OpenTelemetry（OTel）のイベントとトレーススパンにspeed属性が追加されました。この属性により、Fast modeとNormal modeのどちらで実行されたかを可視化・分析できるようになり、パフォーマンス監視とデバッグが容易になりました。

Fast modeとは ​

Fast modeは、Claude Code v2.1.36で導入された機能で、Opus 4.6モデルでより高速な応答を実現します。同じモデルを使用しながら、出力速度を向上させることで、開発ワークフローを加速します。

Fast modeの有効化 ​

bash
# Fast modeを有効化
> /fast

# Fast modeを無効化（Normal modeに戻す）
> /fast off

基本的な使い方 ​

OpenTelemetryの設定 ​

Claude CodeでOpenTelemetryを有効にします。

bash
# 環境変数でOTelを有効化
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_SERVICE_NAME=claude-code

# Claude Codeを起動
claude

speed属性の確認 ​

OTelバックエンド（Jaeger、Zipkin、Datadogなど）でトレースを確認すると、各スパンにspeed属性が含まれています。

json
{
  "traceId": "abc123...",
  "spanId": "def456...",
  "attributes": {
    "speed": "fast",
    "model": "claude-opus-4-6",
    "tool": "Bash",
    "duration_ms": 1234
  }
}

実践例 ​

パフォーマンスモニタリング ​

Fast modeとNormal modeのパフォーマンスを比較分析します。

bash
# OpenTelemetryバックエンドでクエリを実行
# Fast modeのリクエスト平均応答時間
SELECT AVG(duration_ms) FROM spans WHERE speed = 'fast'

# Normal modeのリクエスト平均応答時間
SELECT AVG(duration_ms) FROM spans WHERE speed = 'normal'

# 速度向上率を計算
# Fast mode: 1200ms
# Normal mode: 2400ms
# 改善率: 50%

Datadogでの可視化 ​

Datadogダッシュボードで、speed属性を使用してメトリクスを可視化します。

yaml
# Datadog APM Dashboard設定例
metrics:
  - name: claude_code.request.duration
    filters:
      - speed:fast
      - speed:normal

visualization:
  type: timeseries
  split_by: speed

Jaegerでのトレース分析 ​

Jaeger UIで、Fast modeのトレースのみをフィルタリングして表示します。

text
# Jaeger UI検索クエリ
service: claude-code
tag: speed=fast

# 結果:
Trace 1: Tool call - Bash (1.2s) [speed=fast]
Trace 2: File read (0.3s) [speed=fast]
Trace 3: Code generation (2.1s) [speed=fast]

Prometheusメトリクスの活用 ​

Prometheusでspeed別のメトリクスを収集・集計します。

promql
# Fast modeのリクエスト数
sum(rate(claude_code_requests_total{speed="fast"}[5m]))

# Normal modeのリクエスト数
sum(rate(claude_code_requests_total{speed="normal"}[5m]))

# speed別のP95レイテンシ
histogram_quantile(0.95,
  sum(rate(claude_code_request_duration_bucket[5m])) by (le, speed)
)

アラート設定 ​

Fast modeのパフォーマンス低下を検出するアラートを設定します。

yaml
# Prometheus Alert Rules
groups:
  - name: claude_code_performance
    rules:
      - alert: FastModeSlowdown
        expr: |
          avg(claude_code_request_duration_seconds{speed="fast"})
          >
          avg(claude_code_request_duration_seconds{speed="normal"}) * 0.8
        for: 5m
        annotations:
          summary: "Fast mode is not performing as expected"
          description: "Fast mode latency is only 20% better than normal mode"

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

Grafanaでspeed属性を活用したダッシュボードを作成します。

json
{
  "dashboard": {
    "title": "Claude Code Performance by Speed",
    "panels": [
      {
        "title": "Request Count by Speed",
        "targets": [
          {
            "expr": "sum by (speed) (rate(claude_code_requests_total[5m]))"
          }
        ]
      },
      {
        "title": "Latency Comparison",
        "targets": [
          {
            "expr": "histogram_quantile(0.95, sum by (le, speed) (rate(claude_code_request_duration_bucket[5m])))"
          }
        ]
      }
    ]
  }
}

この機能の利点 ​

可視化の向上 ​

  • Fast modeとNormal modeの使用状況を明確に把握
  • モード別のパフォーマンスメトリクスを取得
  • トレースデータでのフィルタリングが容易

パフォーマンス分析 ​

  • Fast modeの効果を定量的に測定
  • ボトルネックの特定が容易
  • A/Bテストやパフォーマンスチューニングに活用

運用監視の改善 ​

  • モード別のSLI/SLO設定が可能
  • 異常検知の精度向上
  • トラブルシューティングの効率化

speed属性の値 ​

値説明
fastFast modeで実行されたリクエスト
normalNormal mode（デフォルト）で実行されたリクエスト

注意点 ​

  • OpenTelemetryの設定が必要です（デフォルトでは無効）
  • すべてのスパンとイベントにspeed属性が追加されます
  • この属性はv2.1.41以降で利用可能です
  • OTelバックエンドによっては、属性のインデックス作成が必要な場合があります

OpenTelemetry設定例 ​

基本的な設定 ​

bash
# 環境変数
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_SERVICE_NAME=claude-code
export OTEL_TRACES_SAMPLER=always_on

Datadog向け設定 ​

bash
export DD_AGENT_HOST=localhost
export DD_TRACE_AGENT_PORT=8126
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Jaeger向け設定 ​

bash
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_TRACES_SAMPLER=always_on

関連情報 ​