您可以將 Office 代理程式的完整稽核遙測資料路由到您自己的 OpenTelemetry (OTEL) 收集器。這讓您的組織能完全控制保留期、加密和與 SIEM 或可觀測性平台的整合。
本指南涵蓋如何啟用自訂收集器、您將收到的資料，以及完整的 span 結構描述參考。
自訂 OTEL 收集器適用於 Claude Enterprise 組織和直接提供者部署 (Amazon Bedrock、Google Vertex AI 或閘道)。
您將收到的內容
當您設定自訂收集器時，Office 代理程式會傳送涵蓋每個使用者回合的追蹤資料。每個回合會產生一個 span 樹狀結構，擷取提示、模型呼叫、工具執行、檔案上傳和內容壓縮事件。
您的收集器會接收所有 span 屬性，包括那些包含使用者產生內容的屬性 (提示文字、工具輸入和輸出、文件 URL 和檔案名稱)。不會編輯或篩選任何屬性。助理回應文字不包含在發出的 span 資料中。您的組織擁有此資料。
重要：指標不會傳送到自訂收集器。office_agent.* 計數器命名空間只會路由到 Anthropic。不過，每個計數器增量也會在作用中 span 上顯示為 span 事件，因此相同的訊號可在您的追蹤中取得。
遙測資料透過 OTLP/HTTP 傳送到您的端點 {your_url}/v1/traces。不支援 gRPC，因為增益集在 Office WebView 中執行。
啟用自訂收集器
設定方式取決於您的組織如何使用 Claude 進行驗證。
重要：設定自訂端點時，遙測資料會專門傳送到您的收集器。Span 不會同時傳送到 Anthropic。
Claude Enterprise (OAuth) 組織
組織管理員在 Claude.ai 管理主控台的 組織設定 > Office 代理程式中設定收集器端點。此設定適用於整個組織。
設定 | 說明 |
| 您的 OTLP 收集器的基礎 URL。增益集會附加 /v1/traces。強烈建議使用 HTTPS。 |
| 選用的驗證標頭，按照 OpenTelemetry 規格格式化：key1=value1,key2=value2 |
通訊協定必須是基於 HTTP 的 OTLP。gRPC 在設定時會被拒絕。
直接提供者部署 (Amazon Bedrock、Google Vertex AI、閘道)
對於針對您自己的模型提供者而非 Claude.ai 進行驗證的部署，收集器端點可透過三個設定通道之一提供。這三個通道都使用相同的兩個金鑰。
建議：使用 claude-in-office 外掛程式進行 Claude Code。它會引導您產生資訊清單、註冊 Entra 擴充屬性，以及建立預先配置 otlp_endpoint 和 otlp_headers 的啟動端點。以下三個通道已記錄供參考和手動設定之用。
金鑰 | 格式 | 說明 |
| HTTPS URL | 您的 OTLP 收集器的基礎 URL。增益集會移除任何尾部斜線並附加 /v1/traces。 |
| key1=value1,key2=value2 | 選用的驗證標頭。格式與 OpenTelemetry OTEL_EXPORTER_OTLP_HEADERS 環境變數相同。 |
如果 otlp_endpoint 未設定或為空，則不會設定自訂收集器，增益集會回復為預設行為。
注意：這些設定通道僅適用於 Microsoft Office 部署。Google Workspace 增益集的設定方式不同。
通道 1：資訊清單 URL 參數
將金鑰作為查詢字串參數附加到您自訂增益集資訊清單中的工作窗格 URL：
URL 編碼這些值。這會將設定套用到安裝資訊清單的每個使用者。
通道 2：Azure Entra ID 目錄擴充
針對每個使用者的設定，將金鑰註冊為 Entra ID 目錄擴充屬性，並透過 Microsoft Graph 指派它們。增益集使用巢狀應用程式驗證 (NAA) 從使用者的 ID 權杖讀取它們。
已發行 ID 權杖中的宣告名稱遵循 Azure 的目錄擴充格式：
宣告 | 對應至 |
| otlp_endpoint |
| otlp_headers |
使用針對使用者物件的 Graph PATCH 為每個使用者設定這些。Azure 在 ID 權杖中將目錄擴充值編碼為單一元素陣列；增益集會自動解除包裝它們。此通道需要資訊清單 URL 參數中的 entra_sso=1 以啟用 NAA 權杖取得。
通道 3：Bootstrap 端點回應
如果您的部署使用 bootstrap 端點（您的組織託管的 JSON 端點，該加入項在啟動時呼叫），請在回應本文中包含金鑰：
{
"otlp_endpoint": "https://otel-collector.your-domain.com",
"otlp_headers": "Authorization=Bearer <token>"
}Bootstrap 端點 URL 本身是透過資訊清單 URL 參數或 Entra extn.bootstrap_url 宣告中的 bootstrap_url 設定的。如果已取得 Entra ID 權杖，它會作為 Bearer 授權標頭傳遞至 bootstrap 端點，以便您的端點可以在傳回每個使用者設定之前驗證使用者。
優先順序
當多個通道提供值時，後面的通道會覆寫前面的通道：首先讀取資訊清單參數，然後是 Entra 宣告，然後是 bootstrap 回應。Bootstrap 回應優先。
如果您還沒有，最快的方式是 claude-in-office 外掛程式。
部署模式
自訂收集器匯出在兩種部署模式上都可用：
Claude.ai Enterprise (OAuth)：完整稽核軌跡，包括使用者身分識別 (
user.email、user.account_uuid、organization.id)、MCP 伺服器中繼資料和檔案上傳記錄。直接提供者 (Bedrock、Vertex AI、閘道)：核心稽核軌跡 (提示、工具輸入和輸出、文件 URL)，但沒有使用者身分識別、沒有 MCP 中繼資料和沒有檔案上傳跨度。使用者歸因需要將
session.id與您自己的身分識別提供者日誌相互關聯。
核心稽核承載在兩種模式中都相同。直接提供者部署缺少 Claude.ai 帳戶內容，因此從 Claude.ai 使用者或組織設定檔衍生的屬性不存在。請參閱下方跨度結構描述中的 [claude.ai-only] 標籤以取得完整清單。
表面和廠商標籤
每個跨度都包含兩個標籤，用於識別哪個 Office 應用程式和平台產生了它。使用這些作為篩選和儀表板的主要維度。
標籤 | 值 |
| sheet (Excel/Google Sheets)、doc (Word)、slide (PowerPoint) |
| m (Microsoft) |
跨度參考
每個使用者回合會產生最多五種跨度類型的父/子樹。標記為 [content] 的屬性會攜帶使用者產生的資料；這些構成您的稽核承載。標記為 [claude.ai-only] 的屬性只有在使用者使用 Claude 帳戶登入時才會填入；它們在 Bedrock、Vertex AI 和閘道部署上不存在。缺少的屬性會從跨度中完全省略（沒有具有 null 值的金鑰）。
file.upload 跨度和所有 mcp.* 屬性也是 [claude.ai-only]，因為檔案上傳和 MCP 伺服器連線是 Claude 平台功能。
對於直接提供者部署，使用者身分識別應透過 session.id 和 document.url 相互關聯，並與您的身分識別提供者的工作階段日誌聯結。
資源屬性
這些屬性出現在每個跨度上：
屬性 | 描述 |
| 固定值：office-agent |
| 固定值：1.0.0 |
| 建置提交識別碼 |
agent.query (根跨度)
每個使用者回合一個跨度。這是跨度樹的根，並攜帶工作階段身分識別、文件內容和 MCP 伺服器狀態。SpanKind：INTERNAL。
屬性 | 描述 |
| sheet | doc | slide |
| m |
| 使用者的提示 (前 4000 個字元) |
| 不透明的工作階段識別碼 |
| 使用者的電子郵件地址 |
| 確定性雜湊值區間 (電子郵件的 SHA-256，mod 30) |
| Claude 帳戶 UUID |
| 開啟的 Office 文件的 URL |
| Claude 組織 UUID |
| Claude 訂閱層級 |
| Claude 組織類型 |
| 使用者為此工作階段選擇的模型 |
| PC | Mac | OfficeOnline | iOS | Android | Universal |
| Office 組建編號 |
| 已設定的 MCP 伺服器數量 |
| 成功連線的 MCP 伺服器數量 |
| 連線失敗的 MCP 伺服器數量 |
| success | error | timeout | no_auth | not_attempted |
| MCP 登錄擷取持續時間 |
| MCP 登錄擷取 HTTP 狀態碼 |
| 序列化的 MCP 伺服器詳細資訊（名稱、工具計數、錯誤訊息） |
| 附加到此回合的檔案數量 |
| 上傳的總位元組數 |
| 影像附件的數量 |
| 文件附件的數量 |
| 其他附件的數量 |
| 例外類別名稱（失敗時出現） |
| 查詢失敗的階段（失敗時出現） |
agent.stream
每次對 Claude 的 API 呼叫一個 span，作為查詢 span 的子項。SpanKind：CLIENT。
屬性 | 說明 |
| 用於此呼叫的模型 ID |
| 要求的最大輸出令牌數 |
| 串流開始時對話中的訊息數 |
| 計費的輸入令牌（來自 API 回應） |
| 計費的輸出令牌（來自 API 回應） |
| 從提示快取提供的令牌 |
| 寫入提示快取的令牌 |
| end_turn | tool_use | max_tokens | 等 |
| Anthropic API request-id 標頭，可用於支援相關性 |
提示快取注意事項：此增益集無條件要求提示快取。cache_read_tokens 和 cache_creation_tokens 屬性是從提供者的 API 回應設定的，當回應不包含它們時會被省略。提示快取適用於 Claude 開發者平台；截至本文撰寫時，Amazon Bedrock 和 Google Vertex AI 尚未透過增益集使用的用戶端傳回這些欄位。當支援在您的提供者上推出時，這些屬性將自動開始出現。
agent.tool_execution
每個工具呼叫一個跨度，作為串流跨度的子項。SpanKind：INTERNAL。這是模型對文件採取的操作的主要記錄。
屬性 | 說明 |
| 工具識別碼（例如 get_cell_ranges、execute_office_js、edit_slide_xml） |
| 此工具叫用的唯一識別碼 |
| server | client |
| first_party | mcp | server |
| read | write | read_write |
| manual | auto_accept | deferred |
| 序列化的工具輸入（前 4000 個字元） |
| 布林值 |
| 序列化的工具輸出（前 4000 個字元） |
| 完整輸出長度（以字元為單位）（用於偵測截斷） |
| 錯誤分類（失敗時出現） |
| 讀取的儲存格（僅限工作表表面） |
| 寫入的儲存格（僅限工作表表面） |
| 複製的儲存格（僅限工作表表面） |
注意：tool.accept_decision 屬性記錄了權限決定的方式：manual（使用者核准了此特定操作）、auto_accept（使用者先前已授予常設核准）或 deferred（操作已排隊等待稍後審查）。使用此功能來審計整個組織的核准模式。
agent.compaction
每次對話一個跨度的自動摘要，當上下文接近視窗限制時觸發。SpanKind：CLIENT。
屬性 | 描述 |
| 摘要前的令牌計數 |
| 摘要後的令牌計數 |
| 差值 |
| 布林值 |
| 目前始終為反應式 |
此跨度也包含 agent.surface、agent.vendor、session.id、user.email [claude.ai-only]、user.bucket [claude.ai-only]、office.platform 和 office.version，從根跨度複製，以便您可以獨立查詢壓縮事件。
file.upload [claude.ai-only]
每個個別檔案上傳一個跨度，作為查詢跨度的子項。SpanKind：CLIENT。此跨度類型僅在使用 Claude.ai 帳戶登入時出現。檔案上傳在直接提供者部署上不可用。
屬性 | 描述 |
| 原始檔案名稱 |
| 檔案大小 |
| MIME 類型 |
| Anthropic Files API 識別碼 |
| 布林值 |
跨度事件
跨度事件是附加到上述跨度的時間戳記標記。它們捕捉生命週期轉換和計數器等效信號。
agent.query：exception {exception.type}；file_upload {file_id, mime_type, content_category}agent.stream：first_token；stream_complete；stream_error {exception.type}agent.tool_execution：tool_init；tool_run；tool_result；tool_error {error_type}agent.compaction：compaction_start；compaction_complete；compaction_error {exception.type}file.upload：exception {exception.type}
每個內部產品計數器也在目前活躍的跨度上記錄一個同名的跨度事件，在您的追蹤資料中提供相當於指標串流的功能。office_agent.token.usage 事件在每個 agent.stream 跨度上發出，每個非零令牌類型一次，具有屬性 {token_usage.type: input | output | cacheRead | cacheCreation, token_usage.model, token_usage.token_count}。這反映了其他 Anthropic 產品發出的 *.token.usage 計數器形狀，因此單一收集器可以通過按 service.name 分組來聚合產品間的令牌成本。
表面特定行為
遙測架構在所有表面上都是一致的。這些是差異：
試算表 (Excel)：
agent.tool_execution跨度包含sheet.cells_read、sheet.cells_written和sheet.cells_copied屬性。當使用者在編輯儲存格時工具嘗試寫入時，會出現office_agent.cell_edit_collision_total跨度事件。文件 (Word)：document-edit 漏斗事件追蹤編輯生命週期：
office_agent.doc_edit_received_total、office_agent.doc_edit_parsed_total、office_agent.doc_edit_applied_total、office_agent.doc_proposed_edit_reviewed_total。沒有sheet.cells_*屬性。投影片 (PowerPoint)：除了通用架構外，沒有表面特定的屬性或事件。
重建使用者工作階段
Claude.ai 部署
按
user.email（或user.account_uuid）和session.id篩選跨度。按開始時間戳記排序
agent.query跨度；每個都是一個使用者回合。對於每個回合，
user.message是提示，document.url是正在處理的檔案。子
agent.tool_execution跨度（按時間戳記排序）是採取的動作：tool.input是嘗試的內容，tool.output是結果，tool.accept_decision記錄使用者是否明確批准。
直接提供者部署
在此模式下，增益集沒有 Claude.ai 使用者身份，因此跨度不包含 user.email 或 user.account_uuid。要將活動歸因於使用者：
按
session.id篩選跨度以隔離一個連續的增益集工作階段。使用
document.url來識別正在處理的檔案。將工作階段與您的身分識別提供者的日誌相互關聯：Entra 登入事件、閘道存取日誌，或您的啟動端點的要求日誌（接收使用者的 Entra ID 權杖作為 Bearer 標頭）。
工作階段歸屬於使用者後，每回合的重建相同：按時間戳記排序的 agent.query，包含
user.message、tool.input、tool.output和tool.accept_decision提供稽核軌跡。
這會在兩種部署模式中產生完整、有序的互動記錄。