Office 에이전트용 사용자 정의 OpenTelemetry 수집기 구성

Office 에이전트의 전체 감사 원격 분석을 자신의 OpenTelemetry(OTEL) 수집기로 라우팅할 수 있습니다. 이를 통해 조직은 보존, 암호화 및 SIEM 또는 관찰성 플랫폼과의 통합을 완전히 제어할 수 있습니다.

이 가이드는 사용자 정의 수집기를 활성화하는 방법, 수신할 데이터, 그리고 전체 스팬 스키마 참조를 다룹니다.

사용자 정의 OTEL 수집기는 Claude Enterprise 조직 및 직접 공급자 배포(Amazon Bedrock, Google Vertex AI 또는 게이트웨이)에서 사용할 수 있습니다.

수신할 내용

사용자 정의 수집기를 구성하면 Office 에이전트는 모든 사용자 턴을 포함하는 추적 데이터를 전송합니다. 각 턴은 프롬프트, 모델 호출, 도구 실행, 파일 업로드 및 컨텍스트 압축 이벤트를 캡처하는 스팬 트리를 생성합니다.

수집기는 사용자 생성 콘텐츠(프롬프트 텍스트, 도구 입력 및 출력, 문서 URL 및 파일 이름)를 포함한 모든 스팬 속성을 수신합니다. 속성이 수정되거나 필터링되지 않습니다. 어시스턴트 응답 텍스트는 내보낸 스팬 데이터에 포함되지 않습니다. 조직이 이 데이터를 소유합니다.

중요: 메트릭은 사용자 정의 수집기로 전송되지 않습니다. office_agent.* 카운터 네임스페이스는 Anthropic으로만 라우팅됩니다. 그러나 모든 카운터 증가는 활성 스팬의 스팬 이벤트로도 나타나므로 동일한 신호를 추적에서 사용할 수 있습니다.

원격 분석은 OTLP/HTTP를 통해 {your_url}/v1/traces의 엔드포인트로 전송됩니다. Office WebView에서 추가 기능이 실행되므로 gRPC는 지원되지 않습니다.

사용자 정의 수집기 활성화

설정은 조직이 Claude로 인증하는 방식에 따라 다릅니다.

중요: 사용자 정의 엔드포인트가 구성되면 원격 분석은 수집기로만 전송됩니다. 스팬은 Anthropic으로 이중 전송되지 않습니다.

Claude Enterprise(OAuth) 조직

조직 관리자는 Claude.ai 관리 콘솔의 조직 설정 > Office 에이전트에서 수집기 엔드포인트를 설정합니다. 설정은 조직 전체에 적용됩니다.

설정	설명
`otlp_endpoint`	OTLP 수집기의 기본 URL입니다. 추가 기능은 /v1/traces를 추가합니다. HTTPS를 강력히 권장합니다.
`otlp_headers`	선택적 인증 헤더로, OpenTelemetry 사양에 따라 형식화됩니다: key1=value1,key2=value2

프로토콜은 HTTP 기반 OTLP여야 합니다. gRPC는 구성 시 거부됩니다.

직접 공급자 배포(Amazon Bedrock, Google Vertex AI, 게이트웨이)

Claude.ai가 아닌 자신의 모델 공급자에 대해 인증하는 배포의 경우, 수집기 엔드포인트는 세 가지 구성 채널 중 하나를 통해 제공됩니다. 세 가지 모두 동일한 두 개의 키를 사용합니다.

권장: Claude Code용 claude-in-office 플러그인을 사용하세요. 매니페스트 생성, Entra 확장 속성 등록 및 otlp_endpoint 및 otlp_headers가 미리 연결된 부트스트랩 엔드포인트 설정을 안내합니다. 아래의 세 가지 채널은 참조 및 수동 설정을 위해 문서화되어 있습니다.

키	형식	설명
`otlp_endpoint`	HTTPS URL	OTLP 수집기의 기본 URL입니다. 추가 기능은 후행 슬래시를 제거하고 /v1/traces를 추가합니다.
`otlp_headers`	key1=value1,key2=value2	선택적 인증 헤더입니다. OpenTelemetry OTEL_EXPORTER_OTLP_HEADERS 환경 변수와 동일한 형식입니다.

otlp_endpoint가 설정되지 않았거나 비어 있으면 사용자 정의 수집기가 구성되지 않으며 추가 기능은 기본 동작으로 폴백됩니다.

참고: 이러한 구성 채널은 Microsoft Office 배포에만 적용됩니다. Google Workspace 추가 기능은 별도로 구성됩니다.

채널 1: 매니페스트 URL 매개변수

사용자 정의 추가 기능 매니페스트의 작업 창 URL에 키를 쿼리 문자열 매개변수로 추가합니다:

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

값을 URL 인코딩합니다. 이는 매니페스트를 설치하는 모든 사용자에게 구성을 적용합니다.

채널 2: Azure Entra ID 디렉터리 확장

사용자별 구성의 경우 키를 Entra ID 디렉터리 확장 속성으로 등록하고 Microsoft Graph를 통해 할당합니다. 추가 기능은 Nested App Authentication(NAA)을 사용하여 사용자의 ID 토큰에서 읽습니다.

발급된 ID 토큰의 클레임 이름은 Azure의 디렉터리 확장 형식을 따릅니다:

클레임	매핑 대상
`extn.otlp_endpoint`	otlp_endpoint
`extn.otlp_headers`	otlp_headers

사용자 개체에 대한 Graph PATCH를 사용하여 사용자별로 설정합니다. Azure는 디렉터리 확장 값을 ID 토큰의 단일 요소 배열로 인코딩합니다. 추가 기능은 자동으로 래핑을 해제합니다. 이 채널은 NAA 토큰 획득을 활성화하기 위해 매니페스트 URL 매개변수에 entra_sso=1이 필요합니다.

채널 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): 사용자 ID(user.email, user.account_uuid, organization.id)를 포함한 전체 감사 추적, MCP 서버 메타데이터 및 파일 업로드 기록.
직접 공급자(Bedrock, Vertex AI, 게이트웨이): 핵심 감사 추적(프롬프트, 도구 입력 및 출력, 문서 URL)이지만 사용자 ID 없음, MCP 메타데이터 없음, 파일 업로드 스팬 없음. 사용자 속성은 session.id를 자신의 ID 공급자 로그와 상호 연관시켜야 합니다.

핵심 감사 페이로드는 두 모드 모두에서 동일합니다. 직접 공급자 배포는 Claude.ai 계정 컨텍스트가 없으므로 Claude.ai 사용자 또는 조직 프로필에서 파생된 속성이 없습니다. 전체 목록은 아래 스팬 스키마의 [claude.ai-only] 태그를 참조하세요.

표면 및 공급자 레이블

모든 스팬에는 어느 Office 애플리케이션과 플랫폼이 생성했는지 식별하는 두 개의 레이블이 포함됩니다. 이를 필터링 및 대시보드의 주요 차원으로 사용하세요.

레이블	값
`agent.surface`	sheet(Excel/Google Sheets), doc(Word), slide(PowerPoint)
`agent.vendor`	m(Microsoft)

스팬 참조

각 사용자 턴은 최대 5가지 스팬 유형의 부모/자식 트리를 생성합니다. [content]로 표시된 속성은 사용자 생성 데이터를 전달합니다. 이는 감사 페이로드를 형성합니다. [claude.ai-only]로 표시된 속성은 사용자가 Claude 계정으로 로그인할 때만 채워집니다. Bedrock, Vertex AI 및 게이트웨이 배포에서는 없습니다. 없는 속성은 스팬에서 완전히 생략됩니다(null 값이 있는 키 없음).

file.upload 스팬 및 모든 mcp.* 속성도 [claude.ai-only]입니다. 파일 업로드 및 MCP 서버 연결은 Claude 플랫폼 기능이기 때문입니다.

직접 공급자 배포의 경우 사용자 ID는 session.id 및 document.url을 통해 상호 연관되어야 하며, ID 공급자의 세션 로그와 조인되어야 합니다.

리소스 속성

이 속성들은 모든 스팬에 나타납니다:

속성	설명
`service.name`	고정 값: office-agent
`service.version`	고정 값: 1.0.0
`git.sha`	빌드 커밋 식별자

agent.query(루트 스팬)

사용자 턴당 하나의 스팬입니다. 이는 스팬 트리의 루트이며 세션 ID, 문서 컨텍스트 및 MCP 서버 상태를 전달합니다. SpanKind: INTERNAL.

속성	설명
`agent.surface`	sheet \| doc \| slide
`agent.vendor`	m
`user.message [content]`	사용자의 프롬프트(처음 4000자)
`session.id`	불투명 세션 식별자
`user.email [claude.ai-only]`	사용자의 이메일 주소
`user.bucket [claude.ai-only]`	결정론적 해시 버킷(이메일의 SHA-256, mod 30)
`user.account_uuid [claude.ai-only]`	Claude 계정 UUID
`document.url [content]`	열린 Office 문서의 URL
`organization.id [claude.ai-only]`	Claude 조직 UUID
`org.rate_limit_tier [claude.ai-only]`	Claude 구독 계층
`org.type [claude.ai-only]`	Claude 조직 유형
`agent.selected_model`	이 세션에서 사용자가 선택한 모델
`office.platform`	PC \| Mac \| OfficeOnline \| iOS \| Android \| Universal
`office.version`	Office 빌드 번호
`mcp.configured_count [claude.ai-only]`	구성된 MCP 서버 수
`mcp.connected_count [claude.ai-only]`	성공적으로 연결된 MCP 서버 수
`mcp.failed_count [claude.ai-only]`	연결에 실패한 MCP 서버 수
`mcp.fetch_status [claude.ai-only]`	success \| error \| timeout \| no_auth \| not_attempted
`mcp.fetch_duration_ms [claude.ai-only]`	MCP 레지스트리 가져오기 소요 시간
`mcp.fetch_http_status [claude.ai-only]`	MCP 레지스트리 가져오기 HTTP 상태 코드
`mcp.servers [content] [claude.ai-only]`	직렬화된 MCP 서버 세부 정보(이름, 도구 수, 오류 메시지)
`file.upload.count [claude.ai-only]`	이 턴에 첨부된 파일 수
`file.upload.total_bytes [claude.ai-only]`	업로드된 총 바이트
`file.upload.image_count [claude.ai-only]`	이미지 첨부 수
`file.upload.document_count [claude.ai-only]`	문서 첨부 수
`file.upload.other_count [claude.ai-only]`	기타 첨부 수
`error.name`	예외 클래스 이름(실패 시 표시)
`agent.query_phase`	쿼리가 실패한 단계(실패 시 표시)

agent.stream

Claude에 대한 각 API 호출당 하나의 스팬으로, 쿼리 스팬의 자식입니다. SpanKind: CLIENT.

속성	설명
`model`	이 호출에 사용된 모델 ID
`max_tokens`	요청된 최대 출력 토큰
`agent.message_count`	스트림 시작 시 대화의 메시지 수
`input_tokens`	청구된 입력 토큰(API 응답에서)
`output_tokens`	청구된 출력 토큰(API 응답에서)
`cache_read_tokens`	프롬프트 캐시에서 제공된 토큰
`cache_creation_tokens`	프롬프트 캐시에 기록된 토큰
`stop_reason`	end_turn \| tool_use \| max_tokens \| 기타
`request_id`	Anthropic API request-id 헤더, 지원 상관관계에 사용 가능

프롬프트 캐싱 참고: 애드인은 프롬프트 캐싱을 무조건 요청합니다. cache_read_tokens 및 cache_creation_tokens 속성은 제공자의 API 응답에서 설정되며, 응답에 포함되지 않으면 생략됩니다. 프롬프트 캐싱은 Claude Developer Platform에서 사용 가능합니다. 현재 Amazon Bedrock 및 Google Vertex AI는 애드인이 사용하는 클라이언트를 통해 이러한 필드를 아직 반환하지 않습니다. 제공자에서 지원이 시작되면 이러한 속성이 자동으로 나타나기 시작합니다.

agent.tool_execution

스트림 스팬의 자식으로 도구 호출당 하나의 스팬입니다. SpanKind: INTERNAL. 이것은 모델이 문서에 대해 취한 작업의 주요 기록입니다.

속성	설명
`tool_name`	도구 식별자(예: get_cell_ranges, execute_office_js, edit_slide_xml)
`tool.id`	이 도구 호출의 고유 ID
`tool.caller`	server \| client
`tool.owner`	first_party \| mcp \| server
`tool.read_write`	read \| write \| read_write
`tool.accept_decision`	manual \| auto_accept \| deferred
`tool.input [content]`	직렬화된 도구 입력(처음 4000자)
`tool.success`	부울
`tool.output [content]`	직렬화된 도구 출력(처음 4000자)
`tool.output_chars`	전체 출력 길이(문자 단위)(잘림 감지에 사용)
`tool.error_type`	오류 분류(실패 시 표시)
`sheet.cells_read`	읽은 셀(시트 표면만)
`sheet.cells_written`	기록된 셀(시트 표면만)
`sheet.cells_copied`	복사된 셀(시트 표면만)

참고: tool.accept_decision 속성은 권한 결정이 어떻게 내려졌는지 기록합니다: manual(사용자가 이 특정 작업을 승인함), auto_accept(사용자가 이전에 지속적인 승인을 부여함), 또는 deferred(작업이 나중에 검토하기 위해 대기열에 추가됨). 이를 사용하여 조직 전체의 승인 패턴을 감사합니다.

agent.compaction

대화당 하나의 스팬으로 자동 요약을 수행하며, 컨텍스트가 윈도우 제한에 접근할 때 실행됩니다. SpanKind: CLIENT.

속성	설명
`compaction.pre_tokens`	요약 전 토큰 수
`compaction.post_tokens`	요약 후 토큰 수
`compaction.tokens_saved`	차이
`compaction.success`	부울
`compaction.trigger`	현재 항상 반응형

이 스팬은 또한 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 계정으로 로그인할 때만 나타납니다. 파일 업로드는 직접 공급자 배포에서 사용할 수 없습니다.

속성	설명
`file.upload.filename [content]`	원본 파일명
`file.upload.size_bytes`	파일 크기
`file.upload.mime_type`	MIME 유형
`file.upload.file_id`	Anthropic Files API 식별자
`file.upload.success`	부울

스팬 이벤트

스팬 이벤트는 위의 스팬에 첨부된 타임스탬프 마커입니다. 이들은 생명주기 전환 및 카운터 동등 신호를 캡처합니다.

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 스팬에서 0이 아닌 토큰 유형당 한 번씩 발생하며, {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): 문서 편집 깔때기 이벤트는 편집 생명주기를 추적합니다: 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 사용자 ID가 없으므로 스팬에는 user.email 또는 user.account_uuid가 없습니다. 활동을 사용자에게 귀속시키려면:

session.id로 스팬을 필터링하여 하나의 연속 추가 기능 세션을 격리합니다.
document.url을 사용하여 작업 중인 파일을 식별합니다.
세션을 ID 공급자의 로그와 연관시킵니다: Entra 로그인 이벤트, 게이트웨이 액세스 로그 또는 부트스트랩 엔드포인트의 요청 로그(Bearer 헤더로 사용자의 Entra ID 토큰을 수신).
세션이 사용자에게 할당되면 턴별 재구성은 동일합니다: 타임스탬프로 정렬된 agent.query, user.message, tool.input, tool.output, tool.accept_decision이 감사 추적을 제공합니다.

이는 두 배포 모드 모두에서 상호작용의 완전하고 순서가 지정된 기록을 생성합니다.