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-for-msft-365-install 플러그인을 사용하세요. 매니페스트 생성, 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를 통해 할당합니다. 추가 기능은 중첩 앱 인증(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-for-msft-365-install 플러그인입니다.

배포 모드

사용자 정의 수집기 내보내기는 두 배포 모드 모두에서 사용 가능합니다:

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), doc(Word), slide(PowerPoint), mail(Outlook)
`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 \| mail
`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 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): 공통 스키마 이외의 표면별 속성이나 이벤트가 없습니다.
메일(Outlook): 공통 스키마 이외의 표면별 속성이나 이벤트가 없습니다.

사용자 세션 재구성

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 로그인 이벤트, 게이트웨이 액세스 로그 또는 부트스트랩 엔드포인트의 요청 로그(사용자의 Entra ID 토큰을 Bearer 헤더로 수신).
세션이 사용자에게 할당되면 턴별 재구성은 동일합니다: 타임스탬프 순서로 정렬된 agent.query 스팬, user.message, tool.input, tool.output, tool.accept_decision이 감사 추적을 제공합니다.

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