Claude Media
Claude ConsoleのOpenTelemetry送信先を作る — OTLP設定と配信エラー対処
Anthropicチュートリアル

Claude ConsoleのOpenTelemetry送信先を作る — OTLP設定と配信エラー対処

Claude Consoleで送信先(destination)を追加し、Messages APIとManaged AgentsのスパンをOTLP対応の監視基盤へ送る手順です。ワークスペースの絞り込みと配信エラーの原因も扱います。

読了目安 約11分

Claude APIのリクエストを自社の監視基盤で追うには、Claude Consoleで「送信先(destination)」を1つ作ります。コードは変えません。送信先に監視基盤のOTLPエンドポイントと認証ヘッダーを登録すると、Messages APIのリクエストとManaged Agentsのセッションごとのスパンが届きます。機能の状態はベータです。

追加できるのは組織のAdminロールだけで、Developerロールは一覧を見られます。この記事は、追加画面の入力項目、ワークスペースの絞り込み、届いたかの確認、Failing や Disabled になったときの切り分けを、上から順に扱います。

送信先を作る前に用意する3つのもの

先に揃えるのは次の3点です。

  • Claude Console組織のAdminロール
  • HTTPSの443番ポートでprotobuf形式を受け付けるOTLP/HTTPエンドポイント
  • そのエンドポイントの認証情報(APIキーなど)

自前のOpenTelemetry Collectorを使う場合、OTLP/HTTPレシーバーの既定は4318番ポートです。そのままでは送信先として使えないので、レシーバーをHTTPSの443番で受けるよう設定するか、手前にロードバランサーかリバースプロキシを置きます。

Claude Platform on AWSの組織は、AWSコンソール経由でConsoleにサインインします。Console側にはWorkspace Adminロールがなく、追加や変更の権限はIAMポリシーで決まります。

Consoleで送信先を追加する手順

手順

送信先の追加から疎通確認まで

  1. 1

    設定ページを開く

    ConsoleのOpenTelemetry設定ページ(settings/telemetry-destinations)でAdd destinationを押します。

  2. 2

    項目を入力する

    Provider、OTLP endpoint URL、Request headers、Content mode、Workspacesを埋めます。各項目は次の表のとおりです。

  3. 3

    保存して Test を押す

    Add destinationで保存し、送信先のMore actionsメニューからTestを実行します。テストスパンが届いたか、失敗した理由が画面に出ます。

  4. 4

    監視基盤でスパンを探す

    anthropic.test というスパンが監視基盤に届いていれば、疎通は成功です。

入力項目は次のとおりです。

項目入れる内容
Provider入れる内容使う監視基盤。載っていなければCustom
Name入れる内容任意。「自社の監視基盤」など
OTLP endpoint URL入れる内容監視基盤のOTLP/HTTPのベースURL。IPアドレスでなくホスト名で指定する
Request headers入れる内容各リクエストに付けるヘッダー。認証情報は値に入れる
Content mode入れる内容Metadata onlyかFull content
Workspaces入れる内容All / Selected / All except

Advanced settingsには、OTLP traces endpoint URLと、Full content時の最大コンテンツサイズ(MB)があります。

Providerに一覧のサービスを選ぶと、OTLP endpoint URL、Request headers、OTLP traces endpoint URLの代わりに、そのサービス向けの項目(APIキーなど)をConsoleが尋ねます。一覧のサービスはArize AI、Braintrust、Databricks、Datadog、Grafana Cloud、Honeycomb、Langfuse、LangSmith、New Relic、PostHog、Sentry、Splunkです。

落とし穴

OTLP endpoint URLの末尾に /v1/traces を付けると届かない

ベースURLだけを入れます。/v1/traces はClaude API側が足すので、自分で付けるとパスが二重になり、監視基盤から404が返ります。パスの接頭辞(https://gateway.example.com/otlp のような形)は付けて構いません。トレース用のURLが「ベースURL + /v1/traces」の形にならない監視基盤は、Advanced settingsのOTLP traces endpoint URLにフルURLを入れます。このURLのホストは、OTLP endpoint URLと同じでなければなりません。

認証情報の入れ方と、保存後に見えなくなる値

認証情報はRequest headersの値にだけ入れます。保存後、Consoleは値を再表示しません。あとから変更するときは、ヘッダーの値を入れ直す前提で動きます。

OTLP endpoint URLのホストを変えて編集するときも、ヘッダーの値を入れ直す必要があります。OTLP traces endpoint URLを設定している送信先は、同じ新しいホストに揃えるか、その欄を空にします。

Content modeはMetadata onlyが既定

Metadata onlyのスパンには、識別子、タイミング、ステータス、トークン数、エージェントやツールの名前と説明、MCPサーバー名が入ります。Full contentは、これに加えてモデルへのプロンプトと応答を含みます。

Full contentでは、1スパンに入れる内容の既定上限が0.75MBです。超えた分はAPI側で切り詰められ、anthropic.content.truncated が true になります。切り詰めは、システムプロンプトと古いメッセージから順に落とす方式です。1Mトークンのコンテキストウィンドウを丸ごと残すには、約4MBが必要とされています。監視基盤やその手前のプロキシが大きなリクエストを拒むなら、Maximum content sizeを下げる側に倒します。

HIPAA、FERPA、K-12のデータ取り扱い制限がAnthropicとの間にある組織では、Content modeにFull contentを選んでも、送信先にはメタデータだけが出ます。Full contentにしたのにプロンプトが見えないときは、まずここを疑います。

ワークスペースで送信するスパンを絞る

送信先は、自分が対象にしたワークスペースのスパンだけを受け取ります。Workspacesの選択肢は3つです。

対象範囲

Workspacesの3つの選び方

  • All

    組織内の全ワークスペースが対象です。Defaultワークスペースと、あとから作ったワークスペースも含みます。

  • Selected

    選んだワークスペースだけが対象です。

  • All except

    Allから、選んだワークスペースを除きます。

SelectedとAll exceptでは、選択肢の下に出る検索ボックスでワークスペースを選びます。Claude APIは、リクエストやセッションが動いたワークスペースを対象にしている有効な送信先すべてにスパンを送ります。同じスパンを複数の送信先に配ることもできます。

あとから対象を変えるには、OpenTelemetry設定ページのWorkspaceフィルターをAllにしたまま、送信先のMore actionsからEditを選びます。ワークスペースの作り方はClaude Consoleのワークスペース作成手順にあります。

組織のDeveloperロールと、あるワークスペースのWorkspace Adminロールを両方持つ人は、Selectedの送信先にそのワークスペースを追加・削除できます。Workspaceフィルターをそのワークスペースにして、送信先のMore actionsを開きます。

スパンが届いたか確認する

テストスパンとは別に、実際のリクエストでも確かめます。

  1. 対象ワークスペースを選び、ConsoleのプレイグラウンドでMessages APIのリクエストを1回送る(アプリからのリクエストや、Managed Agentsのセッション開始でも構いません)
  2. 設定ページのDelivery列がHealthyになるのを待つ(1分ほどかかることがあります)
  3. 監視基盤で service.name が claude-platform のスパンを探す

Delivery列の状態は最大1分ほど遅れて表示されます。

Delivery列の状態と、自動で止まる条件

状態意味
Healthy意味直近の配信が成功した
Failing意味直近の配信が失敗した。ホバーでエラーが見える
No data意味まだ配信を試していない
Disabled意味スパンを受け取っていない。ホバーで理由が見える

次の3つのどれかに当たると、Claude APIは送信先をDisabledにします。

  • エンドポイントが 3xx のリダイレクトを返した
  • エンドポイントのホスト名が、公開されていないIPアドレスに解決された
  • 24時間、配信がすべて失敗し続けた

Disabledの送信先にはスパンが送られません。原因を直したあと、WorkspaceフィルターをAllにして、More actionsからEnableを押します。再開までは1分ほどです。

3xxのリダイレクトと公開されていないIPへの解決は、どちらもリトライではなく自動停止の対象です。Collectorの手前にリダイレクトを返す仕組みや、社内向けの名前解決を挟んでいないかを確かめます。

配信のルール

  • 少なくとも1回の配信で、同じスパンが重複して届くことがある。重複はトレースIDとスパンIDで取り除く
  • ベストエフォートで、配信前に失われたスパンは再送されない
  • 最初のリクエストはgzip圧縮で、Content-Encoding: gzip が付く。エンドポイントが 400 か 415 で返すと、圧縮なしで即座に送り直す
  • 再試行は、タイムアウト、接続・TLS・DNSの失敗、408 / 429 / 5xx のときだけ。回数には限りがある
  • TLSハンドシェイクとレスポンスヘッダーは、それぞれ5秒以内に返す必要がある。配信全体の上限は10秒
  • User-Agent は Claude-Platform

配信エラーの原因

Failingの送信先は、ホバーで出るエラーから原因を絞れます。

表示されるエラー疑う箇所
HTTP error (status 401) / (status 403)疑う箇所認証ヘッダーの誤り
HTTP error (status 404)疑う箇所OTLP endpoint URLまたはOTLP traces endpoint URLのパスの誤り
DNS resolution failure疑う箇所ホスト名が名前解決できない
TLS failure疑う箇所エンドポイントの証明書などTLSの問題
Timeout疑う箇所エンドポイントが時間内に応答しない
Connection failure疑う箇所エンドポイントに接続できない

404が出たら、先ほどの /v1/traces の二重付与を最初に確かめます。401と403は、ヘッダーの値が保存後に見えない設計なので、入れ直して保存するのが早道です。

送信先が Healthy なのにスパンが見つからないときは、別の原因があります。

  • そのワークスペースを対象にした、有効な送信先がない
  • 送信先が対象にし始めた直後で、スパンの到着に最大1分かかっている
  • Full contentなのにプロンプトが見えない場合は、前述のデータ取り扱い制限

上限と、CLI・APIからの追加

制限値は次のとおりです。

数字

送信先まわりの上限

  • 送信先の数

    10

    無効な送信先も含む

  • ヘッダー数

    20

    1つの送信先あたり

  • 選択できるワークスペース

    1,000

    1つの送信先あたり

組織単位

このほか、ヘッダー名は128バイト、ヘッダー値は4,096バイト、ヘッダーの名前と値の合計は16,384バイト、エンドポイントURLは2,048文字までです。

Console以外に、Admin APIとCLIからも追加できます。AdminとしてCLIにサインインするか、環境変数 ANTHROPIC_API_KEY にAdmin APIキーを入れて実行します。CLIのAdminサインインでは、ANTHROPIC_API_KEY を未設定にします。設定されているとプロファイルより優先されるためです。

例えば、次のような形になります(ドキュメントの例に沿った形です)。

ant auth login --profile admin --scope "org:admin"
ant --profile admin \
  beta:organization:telemetry-destinations create \
  --endpoint-url https://gateway.example.com/otlp \
  --headers '{authorization: "Bearer YOUR_KEY"}' \
  --traces.content-mode metadata_only \
  --workspaces.type all

curlでは POST /v1/organizations/telemetry_destinations を呼び、anthropic-beta: telemetry-destinations-2026-08-11 ヘッダーを付けます。リクエスト本体は endpoint_url、headers、traces.content_mode、workspaces.type を持ちます。

作成リクエストはConsoleの設定からProviderを除いたものを受け取ります。監視基盤のエンドポイントURLとヘッダーは自分で入れます。Full contentで上限を変えるなら traces.max_content_bytes にバイト数を指定します。一覧・変更・削除と、ワークスペース1件ずつの追加・削除は、telemetry destinations APIの別メソッドです。

アプリ側のトレースとつなぐ

何もしなければ、APIのスパンは独自のトレースとして届きます。自分のアプリのトレースの下に入れたいときは、リクエストにW3Cの traceparent ヘッダーを付けます。ヘッダーのsampledフラグがオフなら、そのリクエストのスパンは出ません。Claude SDKのトレースを有効にして、自分のスパンの内側でSDKを呼べば、自分のスパン、SDKのスパン、APIのスパンの順に入れ子になります。三者を同じ監視基盤へ送ると1本のトレースとして見えます。

APIはMCPコネクタ経由でMCPサーバーを呼ぶとき、params._meta にも traceparent を入れて渡します。MCPサーバー側のスパンも、APIのスパンの下に置けます。

他の面のOpenTelemetryとの住み分け

ここで扱ったのは、Claude APIが外へ出すスパンです。Claude Codeの利用量とコストはClaude CodeのOpenTelemetry設定、Agent SDKのクライアント側はAgent SDKのOpenTelemetry実装ガイドで扱っています。送信元も設定場所も別です。

監査ログの観点では、Claude Compliance APIとOpenTelemetryの違いも合わせて読めます。

Providerの選び方

Providerに載っていない監視基盤はCustomで登録できます。OTLP/HTTPを受け付けるなら、載っていなくても送れます。載っている基盤を選ぶと、必要な入力が減ります。

送信先に流れた後のデータは、選んだ監視基盤のサービス側で、そのサービスの保持期間とアクセス制御に従って保管されます。Anthropicの手元の扱いとは別になるため、Full contentにするなら、監視基盤側の保持設定が自社の要件に合うかを先に確かめます。ゼロデータリテンション(ZDR)の対象でも、Messages APIのFull contentは使えます。その場合、APIは配信するまでメモリー上にだけ内容を保持します。Managed AgentsはZDRの対象外で、OpenTelemetryを使ってもデータ保持の扱いは変わりません。

まとめ

運用で効くのは3点です。ベースURLに /v1/traces を付けないこと、ワークスペースの範囲を最初に決めておくこと、ヘッダーの値は保存後に見えない前提で控えを別に持つことです。

Testの anthropic.test スパンで疎通を確認し、それでも届かなければDelivery列のホバー表示から原因を引きます。24時間配信が失敗し続けると自動で止まるので、監視基盤を移すときは古い送信先を放置せず、編集か削除で片付けます。

この記事を共有:XはてブLinkedIn

関連する記事

Anthropic をもっと見る →