Claude Code ガイド

Appearance

原文（日本語訳） ​

ワークフローが生成したエージェントから発せられるテレメトリに workflow.run_id と workflow.name というOpenTelemetry属性が追加され、OTelデータからワークフロー実行のアクティビティを再構成できるようになりました。

原文（英語） ​

Added workflow.run_id and workflow.name OpenTelemetry attributes to telemetry emitted by workflow-spawned agents, so a workflow run's activity can be reconstructed from OTel data

概要 ​

Claude Codeのダイナミックワークフローは、Claudeが書いたスクリプトが数十〜数百のサブエージェントを一括で生成・調整する機能です。これまでは、1回のワークフロー実行から生成された大量のエージェントのテレメトリ（トークン数、コスト、ツール実行スパンなど）を、OTelバックエンド側で「同じワークフロー実行に属するもの」として横断的に紐付ける標準的な手段がありませんでした。今回の変更で、ワークフローが生成する各エージェントのテレメトリに workflow.run_id（実行ごとに一意なID）と workflow.name（ワークフロー名、例: deep-research や保存済みコマンド名）という属性が付与されるようになり、OTelバックエンド上でこれらの属性によるフィルタ・グループ化を行うだけで、1回のワークフロー実行全体のアクティビティ（各フェーズ、各エージェントのコストやツール利用状況など）を再構成できます。

基本的な使い方 ​

まずOpenTelemetryのテレメトリ出力を有効化します。

bash
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

claude

この状態でワークフローを実行すると、生成されるエージェントごとのテレメトリに workflow.run_id と workflow.name が自動的に付与されます。

text
> use a workflow to audit every route handler under src/routes/ for missing authentication checks

バックエンド（Grafana、SigNoz、Honeycombなど）で workflow.run_id="<実行ID>" を条件に絞り込むだけで、その1回の実行に属する全エージェントのスパン・メトリクスを横断的に確認できます。

実践例 ​

1回のワークフロー実行のコストを集計する ​

ワークフローは一度に数十〜数百のエージェントを生成するため、実行全体でどれだけコストがかかったかを把握したい場面が多くあります。workflow.run_id でグループ化すれば、claude_code.cost.usage メトリクスを実行単位で合算できます。

promql
# Prometheus/Grafanaでの集計例
sum by (workflow_run_id, workflow_name) (
  claude_code_cost_usage_total
)

これにより、「deep-research ワークフローの実行Aは合計何ドルかかったか」「保存した /audit-routes コマンドを繰り返し実行したときのコスト推移はどうか」といった分析がダッシュボード上で簡単に行えるようになります。

ワークフロー実行のタイムラインを再構成する ​

/workflows のTUI画面はセッション内でしか進捗を確認できませんが、OTelのトレース（CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 などでトレースを有効化した場合）と組み合わせれば、workflow.run_id をキーにしてそのワークフロー実行に属する全エージェントのスパンを1つのタイムラインとして再構成できます。

bash
# Trace側の設定を追加
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
# バックエンドでのクエリイメージ（Jaeger/Tempoなど）
workflow.run_id = "wf-8f2a1c"

これにより、CLIセッションが終了した後や、CI/CD上で claude -p からヘッドレス実行したワークフローについても、後からOTelデータだけを見て「どのフェーズにどれだけ時間がかかったか」「どのエージェントが失敗・再試行したか」を監査・デバッグできます。

注意点 ​

  • workflow.run_id / workflow.name は、ワークフローが生成したエージェント由来のテレメトリにのみ付与されます。通常の会話でのサブエージェント（Task toolによるもの）には付与されず、agent_id / parent_agent_id / subagent_type といった既存の属性がそのまま使われます。両者を混同しないよう注意してください。
  • ワークフロー機能を利用するにはClaude Code v2.1.154以降が必要です。組織で disableWorkflows を設定している場合や CLAUDE_CODE_DISABLE_WORKFLOWS=1 を設定している場合は、そもそもワークフローが使えないため本属性も発行されません。
  • OTelテレメトリ自体は既定で無効です。CLAUDE_CODE_ENABLE_TELEMETRY=1 を設定し、OTEL_METRICS_EXPORTER / OTEL_LOGS_EXPORTER（トレースが必要な場合は追加で OTEL_TRACES_EXPORTER と CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1）を有効にしないと、そもそも workflow.run_id を含むデータは出力されません。
  • ワークフローは1回の実行で最大1,000エージェント・同時実行16エージェントという上限があるため、大規模な実行では workflow.run_id でグルーピングした際に非常に多くのスパン・メトリクスが集約対象になる点を踏まえてダッシュボードのクエリ性能を確認してください。
  • バージョン番号（2.1.202）やこの属性の正確な発行タイミングは実際のchangelogに準拠していますが、属性名の具体的なデータ型・出力先（メトリクス/ログ/トレースいずれに付与されるか）は公式ドキュメントの更新を都度確認してください。

関連情報 ​