Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

ヘッドレス/SDKモードで tool_decision OTelテレメトリーイベントが送出されていなかった問題を修正しました（anthropics/claude-code#26059）

原文（英語） ​

Fixed tool_decision OTel telemetry event not being emitted in headless/SDK mode (anthropics/claude-code#26059)

概要 ​

Claude CodeはOpenTelemetry（OTel）を使用してテレメトリーデータを送出する機能を持っています。tool_decision イベントはClaudeがどのツールを使用するかを決定した際に記録される重要なテレメトリーイベントですが、ヘッドレスモードやSDKモードで動作している場合、このイベントが正しく送出されていませんでした。この修正により、ヘッドレス/SDKモードでも tool_decision イベントが正常に記録・送出されるようになります。

基本的な使い方 ​

OTelテレメトリーを有効にするには、環境変数を設定します。

bash
# OpenTelemetryエンドポイントの設定
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_SERVICE_NAME="claude-code"

# ヘッドレスモードで実行（修正後はtool_decisionイベントが送出される）
claude --headless "ファイルの一覧を取得してください"

実践例 ​

ユースケース1: CI/CDパイプラインでのテレメトリー収集 ​

自動化されたパイプライン内でClaude Codeを使用し、ツール使用状況をモニタリングする場合。

bash
#!/bin/bash
# CI/CDパイプラインスクリプト

# OTelコレクターの設定
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.example.com"
export OTEL_SERVICE_NAME="claude-code-ci"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production,service.version=1.0.0"

# ヘッドレスモードでClaude Codeを実行
# 修正後: tool_decisionイベントが正しく送出される
claude --headless "このリポジトリのコード品質を分析してください"

# OTelコレクターでtool_decisionイベントを確認できる:
# - イベント名: tool_decision
# - 属性: tool.name, tool.approved, session.id など

ユースケース2: SDK経由での利用とモニタリング ​

Claude Code SDKを使用してプログラムから呼び出す場合のテレメトリー収集。

javascript
// Claude Code SDK を使用した例
const { ClaudeCode } = require('@anthropic-ai/claude-code');

// OTelトレーサーの設定
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces',
  }),
});
sdk.start();

// Claude Code SDKの実行
// 修正後: tool_decisionイベントが正しくOTelに送出される
const claude = new ClaudeCode();
await claude.run({
  prompt: 'プロジェクトの依存関係を確認してください',
  headless: true,
});

// Jaeger/Zipkin等でtool_decisionスパンが確認可能になる

ユースケース3: Grafana/Jaegerでのツール使用状況の可視化 ​

OTelで収集した tool_decision イベントをダッシュボードで可視化する場合。

yaml
# docker-compose.yml: OTelコレクター + Jaeger の設定例
version: '3'
services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    ports:
      - "4318:4318"
    volumes:
      - ./otel-config.yaml:/etc/otelcol-contrib/config.yaml

  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"
bash
# Claude Codeのテレメトリー設定
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"

# ヘッドレスモードで実行
claude --headless "テストを実行してください"

# Jaeger UI (http://localhost:16686) で
# tool_decisionスパンを含むトレースが確認できる（修正後）

注意点 ​

  • OTelテレメトリーは環境変数 OTEL_EXPORTER_OTLP_ENDPOINT が設定されている場合のみ有効です。
  • ヘッドレスモードは --headless フラグまたはCI環境で自動的に有効になる場合があります。
  • tool_decision イベントにはツール名、承認状態、セッションIDなどの情報が含まれます。
  • テレメトリーデータにはセンシティブな情報が含まれる可能性があるため、エンドポイントの設定には注意が必要です。
  • この修正はOTelを使用していない環境には影響しません。

関連情報 ​