Office agentsのOpenTelemetry設定 — 監査テレメトリを自社コレクターへ送る

Office agentsのカスタムOTELコレクターは、ExcelやWordなどで動くClaudeの全ターンを、トレースとして自社のOpenTelemetryコレクターへ送る機能です。保持期間・暗号化・SIEM連携を自社で決められます。対象はClaude Enterprise組織と、Amazon Bedrock・Google Vertex AI・ゲートウェイ経由の直接プロバイダー構成です。

送信先を設定すると、テレメトリはその宛先だけに向かいます。Anthropicへの二重送信は行われません。

Office agentsのカスタムコレクターで何が届くか

コレクターには、ユーザーの1ターンごとにスパンの木が届きます。プロンプト、モデル呼び出し、ツール実行、ファイルアップロード、コンテキストの圧縮(compaction)が記録されます。

ユーザー生成の内容を運ぶ属性(プロンプト本文、ツールの入出力、ドキュメントURL、ファイル名)も、伏せ字や間引きなしでそのまま届きます。逆に、アシスタントの応答テキストはスパンに含まれません。

送信の条件は次のとおりです。

• 送信形式はOTLP/HTTPで、宛先は {your_url}/v1/traces になります
• gRPCは使えません。アドインがOfficeのWebView内で動くためです
• メトリクスは送られません。office_agent.* のカウンター群はAnthropic宛てだけです
• ただしカウンターが増えるたびに、同名のスパンイベントが有効なスパンに付くので、同じ信号をトレースから読めます

Claude Enterprise組織での設定手順

OAuthで認証するClaude Enterprise組織では、組織管理者がClaude.aiの管理コンソールで設定します。場所はOrganization settingsのOffice agentsです。設定は組織全体に効きます。

gRPCを指定すると、設定の時点で拒否されます。

直接プロバイダー構成での3つの設定経路

BedrockやVertex AI、ゲートウェイの構成では、Claude.aiの管理コンソールを使いません。同じ2つのキー(otlp_endpoint と otlp_headers)を、3つの経路のどれかで渡します。otlp_headers の形式は、OpenTelemetry標準の OTEL_EXPORTER_OTLP_HEADERS と同じです。

otlp_endpoint が未設定か空なら、カスタムコレクターは構成されず、アドインは既定の動作に戻ります。この経路はMicrosoft Officeの展開向けで、Google Workspaceのアドインは別に設定します。

公式は、Claude Code向けの claude-for-msft-365-install プラグインを勧めています。マニフェスト生成、Entra拡張属性の登録、otlp_endpoint と otlp_headers を組み込んだブートストラップエンドポイントの用意まで、対話で進められます。以下の3経路は、手動で構成する場合のリファレンスです。

経路1: マニフェストのURLパラメーター

カスタムアドインのマニフェストにあるtaskpane URLに、クエリ文字列でキーを足します。値はURLエンコードします。マニフェストを入れた全ユーザーに同じ設定が効きます。

https://<addin-host>/taskpane.html?otlp_endpoint=https://otel-collector.your-domain.com&otlp_headers=Authorization=Bearer%20<token>

経路2: Azure Entra IDのディレクトリ拡張

ユーザー単位で変えたいときは、2つのキーをEntra IDのディレクトリ拡張属性として登録し、Microsoft Graphで割り当てます。アドインは、Nested App Authentication(NAA)で得たIDトークンからこれを読みます。

ユーザーごとの値は、ユーザーオブジェクトへのGraph PATCHで入れます。Azureは拡張属性の値を要素1つの配列としてトークンに載せますが、アドインが自動で取り出します。この経路では、マニフェストのURLパラメーターに entra_sso=1 が必要です。NAAのトークン取得を有効にするためです。

経路3: ブートストラップエンドポイントの応答

組織がJSONエンドポイントを持ち、アドインが起動時に呼ぶ構成なら、応答本文にキーを入れます。

{
  "otlp_endpoint": "https://otel-collector.your-domain.com",
  "otlp_headers": "Authorization=Bearer <token>"
}

エンドポイントのURLは、マニフェストのURLパラメーターの bootstrap_url、またはEntraの extn.bootstrap_url クレームで指定します。EntraのIDトークンを取得済みなら、Bearerの認可ヘッダーとしてこのエンドポイントに渡されます。ユーザーを認証してから、ユーザー別の設定を返せます。

複数の経路が食い違ったときの優先順位

読み込み順は、マニフェストのパラメーター、Entraのクレーム、ブートストラップ応答の順です。後から読むものが前の値を上書きするので、ブートストラップ応答が最優先になります。

全社共通の既定をマニフェストに書き、部署ごとの例外だけをブートストラップ応答で返す、といった二層の運用が成り立ちます。

コレクター側の受け口を用意する

受け側は、OTLP/HTTPのトレースを受けられるコレクターであれば足ります。次は、OpenTelemetry Collectorで受け口を開く場合の一般的な設定例です。公式の記載ではなく、Office agentsの送信仕様(OTLP/HTTP・/v1/traces)に合わせた例示です。

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
 
exporters:
  debug:
    verbosity: detailed
 
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]

最初は debug エクスポーターで受信内容を目視し、スパンが届くのを確かめてから、SIEMや保管先のエクスポーターへ差し替える進め方が安全です。公式ページには、アドインからの送信でCORSの許可が要るかどうかの記載がありません。OfficeのWebViewから送る性質上、疎通しないときはゲートウェイ側のヘッダー設定を疑う価値があります。

認証方式で変わるもの — OAuthと直接プロバイダーの比較

コアの監査ペイロード(プロンプト、ツールの入出力、ドキュメントURL)は、どちらの構成でも同じです。差が出るのは、Claude.aiのアカウント文脈に由来する属性です。

直接プロバイダーでは、ユーザーへの紐付けを自社側で組み立てます。session.id を、自社IdPのログと突き合わせる形です。

スパンの構造と読むべき属性

1ターンは、最大5種類のスパンの親子関係になります。agent.query が根で、その下に agent.stream、さらに agent.tool_execution が続きます。agent.compaction は会話の自動要約のたびに、file.upload はファイルごとに出ます。

すべてのスパンに、Officeアプリとベンダーを示す2つのラベルが付きます。ダッシュボードの主な絞り込み軸は、これらになります。

リソース属性は全スパン共通で、service.name は office-agent、service.version は 1.0.0 の固定値です。git.sha にビルドのコミットIDが入ります。

agent.query(ターンの根)

1ターンにつき1つで、セッション、ドキュメント、MCPの状態を持ちます。user.message はプロンプトの先頭4,000文字です。document.url は開いている文書のURL、session.id は不透明なセッション識別子です。

Claude.ai限定の属性として、user.email、user.account_uuid、organization.id、org.rate_limit_tier、org.typeがあります。user.bucket は、メールアドレスのSHA-256を30で割った余りです。ユーザーの集計を、メールを出さずに分けたいときに使えます。

失敗したターンには、error.name と、失敗した段階を示す agent.query_phase が付きます。

agent.stream(Claude APIの1呼び出し)

model、max_tokens、input_tokens、output_tokens、stop_reason などを持ちます。request_id はAnthropic APIのリクエストIDで、サポートへの問い合わせに使えます。

プロンプトキャッシュはアドインが常に要求します。cache_read_tokens と cache_creation_tokens は、プロバイダーの応答に含まれるときだけ付きます。公式によると、BedrockとVertex AIは現状、アドインが使うクライアント経由でこれらの値を返しません。対応した時点で自動的に現れます。

agent.tool_execution(ドキュメントへの操作の記録)

モデルがドキュメントに何をしたかの一次記録です。監査で最も見る層になります。

tool.accept_decision の意味は次のとおりです。manual はユーザーがその操作を個別に承認したこと、auto_accept は事前の常時承認、deferred は後の確認に回したことを指します。組織内の承認パターンを、この値の分布で監査できます。

入出力は4,000文字で切られます。長い出力を丸ごと保全したい監査要件がある場合は、tool.output_chars と実際の文字列の長さを比べて、欠けた分を検出します。

Excelでは、sheet.cells_read、sheet.cells_written、sheet.cells_copied も付きます。

agent.compactionとfile.upload

agent.compaction は、コンテキストが上限に近づいて自動要約したときに出ます。要約前後のトークン数(compaction.pre_tokens compaction.post_tokens)と、差分の compaction.tokens_saved、成否の compaction.success が入ります。compaction.trigger は現状、常に reactive です。根のスパンの属性の一部も複製されるので、圧縮だけを単独で検索できます。

file.upload はClaude.ai限定です。ファイル名(内容属性)、サイズ、MIMEタイプ、Files APIのファイルID、成否が記録されます。

スパンイベントとトークン集計

スパンには、ライフサイクルの節目を示すイベントも付きます。

• agent.stream: first_token、stream_complete、stream_error
• agent.tool_execution: tool_init、tool_run、tool_result、tool_error
• agent.compaction: compaction_start、compaction_complete、compaction_error

office_agent.token.usage イベントは agent.stream のスパンごとに、0でないトークン種別1つにつき1回出ます。属性は token_usage.type(input / output / cacheRead / cacheCreation)、token_usage.model、token_usage.token_count です。他のAnthropic製品の *.token.usage カウンターと同じ形なので、service.name でグループ化すれば、1つのコレクターで製品横断のトークン集計ができます。

アプリごとの追加イベントもあります。Excelでは、ユーザーがセルを編集中にツールが書き込もうとしたときの office_agent.cell_edit_collision_total が出ます。Wordでは、編集の受信から適用、提案編集のレビューまでを追う office_agent.doc_edit_received_total、doc_edit_parsed_total、doc_edit_applied_total、doc_proposed_edit_reviewed_total が出ます。PowerPointとOutlookには、共通スキーマ以外の属性やイベントはありません。

ユーザーセッションを時系列で再構成する

クエリ側の手順は、構成によって入口だけが違います。

Claude.ai(OAuth)の場合は、次の順です。

1. user.email または user.account_uuid と session.id でスパンを絞る
2. agent.query を開始時刻で並べる。1件が1ターンになる
3. ターンごとに、user.message がプロンプト、document.url が作業中のファイルを表す
4. 子の agent.tool_execution を時刻順に読む。tool.input が試みた操作、tool.output が結果、tool.accept_decision が承認の有無を示す

直接プロバイダーの場合、アドインはClaude.aiのユーザー情報を持たないため、user.email も user.account_uuid も付きません。ユーザーへの帰属は次のように行います。

1. session.id で、1回の連続したアドインセッションを切り出す
2. document.url で、作業対象のファイルを特定する
3. EntraのサインインイベントやゲートウェイのアクセスログをIdPのログと照合する。ブートストラップエンドポイントのリクエストログも使える。そこにはユーザーのEntra IDトークンがBearerとして届く
4. セッションの持ち主が決まれば、以降のターン単位の再構成はOAuthの場合と同じ

どちらの構成でも、やり取りの順序付きの記録が得られます。

設定前に確認したい落とし穴

• 本文が伏せ字にならない: プロンプトやツール出力に業務データが載ります。コレクター以降の保管先のアクセス権と保持期間は、設計の最初に決めておく前提です
• 応答テキストは無い: アシスタントの返答そのものは、スパンからは復元できません。ツール入出力とプロンプトまでが記録範囲です
• メトリクスは自社側に来ない: 集計が必要ならスパンイベントから作ります
• Anthropic側のテレメトリも止まる: カスタム宛先を設定するとスパンは自社だけに向かうので、Anthropic側での同じ観測は前提にできません
• HTTPS推奨: otlp_headers に認証トークンを入れるため、平文のHTTPは避けます

Claude CodeやCoworkのOpenTelemetryとの違い

Claude Codeは、環境変数で OTEL_EXPORTER_OTLP_PROTOCOL を選び、gRPCも使えます。Claude CodeのOpenTelemetry監視設定がその手順です。Office agentsは、設定キーが otlp_endpoint と otlp_headers の2つで、プロトコルはHTTPに固定されています。

Coworkの側はCoworkのOpenTelemetry監視設定にまとまっています。OTelとは別に、Anthropic側に保持されたセッション内容を取得するAPIもあります。役割の違いはCompliance APIとはで確認できます。

まとめ

Office agentsのカスタムコレクターは、Excel・Word・PowerPoint・Outlookの全ターンを、プロンプトとツール入出力つきで自社のトレース基盤に集める仕組みです。設定はEnterpriseなら管理コンソール、直接プロバイダーならマニフェスト・Entra・ブートストラップの3経路です。

使い道の中心は agent.tool_execution で、承認の経緯まで含めて操作履歴を残せます。ユーザー帰属は、OAuth構成ならスパン自体に載り、直接プロバイダーでは session.id とIdPログの突き合わせが必要です。この差が、設計の分かれ目になります。