Claude Code ガイド

Appearance

OpenTelemetry: LLM リクエストスパンに stop_reason 等の属性を追加 ​

原文（日本語に翻訳） ​

OpenTelemetry: LLM リクエストスパンに stop_reason、gen_ai.response.finish_reasons、および OTEL_LOG_USER_PROMPTS の背後にゲートされた user_system_prompt を追加しました。

原文（英語） ​

OpenTelemetry: added stop_reason, gen_ai.response.finish_reasons, and user_system_prompt (gated behind OTEL_LOG_USER_PROMPTS) to LLM request spans

概要 ​

Claude Code v2.1.121 では、OpenTelemetry の LLM リクエストスパンに3つの新しい属性が追加されました。stop_reason と gen_ai.response.finish_reasons により、モデルの応答がどのように終了したかを追跡できます。また user_system_prompt は OTEL_LOG_USER_PROMPTS=1 環境変数を設定した場合のみ記録される機密性の高い属性で、システムプロンプトの内容を観測できます。可観測性パイプラインでの LLM 利用分析が大幅に強化されます。

基本的な使い方 ​

bash
# OpenTelemetry エンドポイントを設定
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 通常の使用（stop_reason と finish_reasons が記録される）
claude "コードを書いてください"

# システムプロンプトも記録したい場合（注意: 機密情報が含まれる可能性あり）
export OTEL_LOG_USER_PROMPTS=1
claude "コードを書いてください"

実践例 ​

スパンデータの構造 ​

LLM リクエストスパンには以下の新しい属性が含まれます：

json
{
  "name": "llm.request",
  "attributes": {
    "gen_ai.system": "anthropic",
    "gen_ai.request.model": "claude-sonnet-4-6",
    "stop_reason": "end_turn",
    "gen_ai.response.finish_reasons": ["end_turn"],
    // OTEL_LOG_USER_PROMPTS=1 の場合のみ:
    "user_system_prompt": "You are a helpful assistant..."
  }
}

Grafana での stop_reason 分析 ​

promql
# stop_reason の分布を可視化
count by (stop_reason) (
  rate(claude_code_llm_requests_total[5m])
)

# max_tokens による打ち切り率を監視
rate(claude_code_llm_requests_total{stop_reason="max_tokens"}[5m])
  / rate(claude_code_llm_requests_total[5m])

セキュリティに注意したプロンプトログ ​

bash
# 本番環境では OTEL_LOG_USER_PROMPTS を無効（デフォルト）に保つ
# 開発・デバッグ環境のみで有効化

# 開発環境のみ
if [ "$ENV" = "development" ]; then
  export OTEL_LOG_USER_PROMPTS=1
fi

export OTEL_EXPORTER_OTLP_ENDPOINT=http://dev-jaeger:4317
claude "デバッグをお願いします"

stop_reason の値と意味 ​

値意味
end_turn正常に応答が完了した
max_tokensトークン上限に達した
stop_sequenceストップシーケンスに一致した
tool_useツール呼び出しのために停止

注意点 ​

  • user_system_prompt には機密情報が含まれる可能性があります。OTEL_LOG_USER_PROMPTS=1 は信頼できる観測環境でのみ使用してください
  • gen_ai.response.finish_reasons は OpenTelemetry の GenAI セマンティック規約に準拠したフィールドです
  • これらの属性は OpenTelemetry を設定した場合のみ記録されます
  • 大量のリクエストがある環境では、ストレージコストを考慮してデータ保持ポリシーを設定してください

関連情報 ​