Configurar um coletor OpenTelemetry personalizado para agentes do Office

Você pode rotear telemetria de auditoria completa de agentes do Office para seu próprio coletor OpenTelemetry (OTEL). Isso oferece à sua organização controle total sobre retenção, criptografia e integração com sua plataforma SIEM ou de observabilidade.

Este guia aborda como ativar um coletor personalizado, quais dados você receberá e a referência completa do esquema de span.

Coletores OTEL personalizados estão disponíveis para organizações Claude Enterprise e para implantações de provedor direto (Amazon Bedrock, Google Vertex AI ou um gateway).

O que você receberá

Quando você configura um coletor personalizado, os agentes do Office enviam dados de rastreamento cobrindo cada turno do usuário. Cada turno produz uma árvore de spans capturando o prompt, chamadas de modelo, execuções de ferramentas, uploads de arquivos e eventos de compactação de contexto.

Seu coletor recebe todos os atributos de span, incluindo aqueles que contêm conteúdo gerado pelo usuário (texto de prompt, entradas e saídas de ferramentas, URLs de documentos e nomes de arquivos). Nenhum atributo é redatado ou filtrado. O texto de resposta do assistente não está incluído nos dados de span emitidos. Sua organização é proprietária desses dados.

Importante: Métricas não são enviadas para coletores personalizados. O namespace do contador office_agent.* é roteado apenas para Anthropic. No entanto, cada incremento de contador também aparece como um evento de span no span ativo, portanto, os mesmos sinais estão disponíveis em seus rastreamentos.

A telemetria é enviada via OTLP/HTTP para seu endpoint em {your_url}/v1/traces. gRPC não é suportado porque o suplemento é executado em uma WebView do Office.

Ativar um coletor personalizado

A configuração difere dependendo de como sua organização se autentica com Claude.

Importante: Quando um endpoint personalizado é configurado, a telemetria vai exclusivamente para seu coletor. Os spans não são enviados duplamente para Anthropic.

Organizações Claude Enterprise (OAuth)

Um administrador da organização define o endpoint do coletor no console de administração Claude.ai em Configurações da organização > Agentes do Office. A configuração se aplica em toda a organização.

Configuração	Descrição
`otlp_endpoint`	URL base do seu coletor OTLP. O suplemento acrescenta /v1/traces. HTTPS fortemente recomendado.
`otlp_headers`	Cabeçalhos de autenticação opcionais, formatados de acordo com a especificação OpenTelemetry: key1=value1,key2=value2

O protocolo deve ser OTLP baseado em HTTP. gRPC é rejeitado no momento da configuração.

Implantações de provedor direto (Amazon Bedrock, Google Vertex AI, gateway)

Para implantações que se autenticam contra seu próprio provedor de modelo em vez de Claude.ai, o endpoint do coletor é fornecido através de um dos três canais de configuração. Todos os três usam as mesmas duas chaves.

Recomendado: Use o plugin claude-in-office para Claude Code. Ele o orienta na geração do manifesto, registro de atributos de extensão Entra e configuração de um endpoint de bootstrap com otlp_endpoint e otlp_headers pré-configurados. Os três canais abaixo estão documentados para referência e configuração manual.

Chave	Formato	Descrição
`otlp_endpoint`	URL HTTPS	URL base do seu coletor OTLP. O suplemento remove qualquer barra à direita e acrescenta /v1/traces.
`otlp_headers`	key1=value1,key2=value2	Cabeçalhos de autenticação opcionais. Mesmo formato que a variável de ambiente OTEL_EXPORTER_OTLP_HEADERS do OpenTelemetry.

Se otlp_endpoint não estiver definido ou estiver vazio, nenhum coletor personalizado é configurado e o suplemento volta ao comportamento padrão.

Nota: Esses canais de configuração se aplicam apenas a implantações do Microsoft Office. Os suplementos do Google Workspace são configurados separadamente.

Canal 1: Parâmetro de URL do manifesto

Acrescente as chaves como parâmetros de string de consulta à URL do painel de tarefas em seu manifesto de suplemento personalizado:

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

Codifique os valores em URL. Isso aplica a configuração a cada usuário que instala o manifesto.

Canal 2: Extensão de diretório do Azure Entra ID

Para configuração por usuário, registre as chaves como atributos de extensão de diretório do Entra ID e atribua-as via Microsoft Graph. O suplemento as lê do token de ID do usuário usando Autenticação de Aplicativo Aninhado (NAA).

Os nomes de declaração no token de ID emitido seguem o formato de extensão de diretório do Azure:

Declaração	Mapeia para
`extn.otlp_endpoint`	otlp_endpoint
`extn.otlp_headers`	otlp_headers

Defina estes por usuário com um PATCH do Graph contra o objeto de usuário. O Azure codifica valores de extensão de diretório como matrizes de um único elemento no token de ID; o suplemento as desembrulha automaticamente. Este canal requer entra_sso=1 nos parâmetros de URL do manifesto para ativar a aquisição de token NAA.

Canal 3: Resposta do endpoint de bootstrap

Se sua implantação usa um endpoint de bootstrap (um endpoint JSON que sua organização hospeda e que o complemento chama na inicialização), inclua as chaves no corpo da resposta:

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

A URL do endpoint de bootstrap é configurada via bootstrap_url nos parâmetros de URL do manifesto ou em uma declaração extn.bootstrap_url do Entra. Se um token de ID do Entra foi adquirido, ele é passado para o endpoint de bootstrap como um cabeçalho de autorização Bearer, para que seu endpoint possa autenticar o usuário antes de retornar a configuração por usuário.

Precedência

Quando vários canais fornecem um valor, os canais posteriores substituem os anteriores: os parâmetros do manifesto são lidos primeiro, depois as declarações do Entra, depois a resposta de bootstrap. A resposta de bootstrap vence.

Se ainda não o fez, o caminho mais rápido é o plugin claude-in-office.

Modos de implantação

A exportação de coletor personalizado está disponível em ambos os modos de implantação:

Claude.ai Enterprise (OAuth): trilha de auditoria completa incluindo identidade do usuário (user.email, user.account_uuid, organization.id), metadados do servidor MCP e registros de upload de arquivo.
Provedor direto (Bedrock, Vertex AI, gateway): trilha de auditoria principal (prompts, entradas e saídas de ferramentas, URLs de documentos), mas sem identidade do usuário, sem metadados de MCP e sem períodos de upload de arquivo. A atribuição de usuário requer correlacionar session.id com seus próprios logs do provedor de identidade.

A carga útil de auditoria principal é idêntica em ambos os modos. As implantações de provedor direto carecem de contexto de conta Claude.ai, portanto, os atributos derivados do perfil de usuário ou organização Claude.ai estão ausentes. Consulte as tags [claude.ai-only] no esquema de span abaixo para a lista completa.

Rótulos de superfície e fornecedor

Cada span inclui dois rótulos identificando qual aplicativo Office e plataforma o geraram. Use-os como suas dimensões principais para filtragem e painéis.

Rótulo	Valores
`agent.surface`	sheet (Excel/Google Sheets), doc (Word), slide (PowerPoint)
`agent.vendor`	m (Microsoft)

Referência de span

Cada turno do usuário produz uma árvore pai/filho de até cinco tipos de span. Os atributos marcados [content] carregam dados gerados pelo usuário; estes formam sua carga útil de auditoria. Os atributos marcados [claude.ai-only] são preenchidos apenas quando o usuário faz login com uma conta Claude; eles estão ausentes em implantações Bedrock, Vertex AI e gateway. Os atributos ausentes são omitidos do span inteiramente (sem chave com valor nulo).

O span file.upload e todos os atributos mcp.* também são [claude.ai-only], pois upload de arquivo e conexões de servidor MCP são recursos da plataforma Claude.

Para implantações de provedor direto, a identidade do usuário deve ser correlacionada via session.id e document.url, unidas aos logs de sessão do seu provedor de identidade.

Atributos de recurso

Estes atributos aparecem em cada span:

Atributo	Descrição
`service.name`	Valor fixo: office-agent
`service.version`	Valor fixo: 1.0.0
`git.sha`	Identificador de commit de compilação

agent.query (span raiz)

Um span por turno do usuário. Este é a raiz da árvore de span e carrega identidade de sessão, contexto de documento e status do servidor MCP. SpanKind: INTERNAL.

Atributo	Descrição
`agent.surface`	sheet \| doc \| slide
`agent.vendor`	m
`user.message [content]`	O prompt do usuário (primeiros 4000 caracteres)
`session.id`	Identificador de sessão opaco
`user.email [claude.ai-only]`	Endereço de email do usuário
`user.bucket [claude.ai-only]`	Bucket de hash determinístico (SHA-256 de email, mod 30)
`user.account_uuid [claude.ai-only]`	UUID da conta Claude
`document.url [content]`	URL do documento Office aberto
`organization.id [claude.ai-only]`	UUID da organização Claude
`org.rate_limit_tier [claude.ai-only]`	Nível de assinatura Claude
`org.type [claude.ai-only]`	Tipo de organização Claude
`agent.selected_model`	Modelo selecionado pelo usuário para esta sessão
`office.platform`	PC \| Mac \| OfficeOnline \| iOS \| Android \| Universal
`office.version`	Número de compilação do Office
`mcp.configured_count [claude.ai-only]`	Número de servidores MCP configurados
`mcp.connected_count [claude.ai-only]`	Número de servidores MCP conectados com sucesso
`mcp.failed_count [claude.ai-only]`	Número de servidores MCP que falharam ao conectar
`mcp.fetch_status [claude.ai-only]`	sucesso \| erro \| tempo limite \| sem autenticação \| não tentado
`mcp.fetch_duration_ms [claude.ai-only]`	Duração da busca do registro MCP
`mcp.fetch_http_status [claude.ai-only]`	Código de status HTTP da busca do registro MCP
`mcp.servers [content] [claude.ai-only]`	Detalhes serializados do servidor MCP (nomes, contagens de ferramentas, mensagens de erro)
`file.upload.count [claude.ai-only]`	Número de arquivos anexados a este turno
`file.upload.total_bytes [claude.ai-only]`	Total de bytes enviados
`file.upload.image_count [claude.ai-only]`	Número de anexos de imagem
`file.upload.document_count [claude.ai-only]`	Número de anexos de documento
`file.upload.other_count [claude.ai-only]`	Número de outros anexos
`error.name`	Nome da classe de exceção (presente em caso de falha)
`agent.query_phase`	Fase em que a consulta falhou (presente em caso de falha)

agent.stream

Um span por chamada de API para Claude, como filho do span de consulta. SpanKind: CLIENT.

Atributo	Descrição
`model`	ID do modelo usado para esta chamada
`max_tokens`	Tokens de saída máximos solicitados
`agent.message_count`	Número de mensagens na conversa no início do stream
`input_tokens`	Tokens de entrada faturados (da resposta da API)
`output_tokens`	Tokens de saída faturados (da resposta da API)
`cache_read_tokens`	Tokens fornecidos do cache de prompt
`cache_creation_tokens`	Tokens gravados no cache de prompt
`stop_reason`	end_turn \| tool_use \| max_tokens \| etc.
`request_id`	Cabeçalho request-id da API Anthropic, utilizável para correlação de suporte

Nota sobre cache de prompt: O add-in solicita cache de prompt incondicionalmente. Os atributos cache_read_tokens e cache_creation_tokens são definidos a partir da resposta da API do provedor e são omitidos quando a resposta não os inclui. O cache de prompt está disponível para a Plataforma de Desenvolvedores Claude; até o momento, Amazon Bedrock e Google Vertex AI ainda não retornam esses campos através do cliente que o add-in usa. Quando o suporte chegar ao seu provedor, esses atributos começarão a aparecer automaticamente.

`agent.tool_execution`

Um span por chamada de ferramenta, como filho do span de stream. SpanKind: INTERNAL. Este é o registro principal das ações que o modelo executou no documento.

Atributo	Descrição
`tool_name`	Identificador da ferramenta (ex: get_cell_ranges, execute_office_js, edit_slide_xml)
`tool.id`	ID único desta invocação de ferramenta
`tool.caller`	servidor \| cliente
`tool.owner`	first_party \| mcp \| servidor
`tool.read_write`	leitura \| escrita \| leitura_escrita
`tool.accept_decision`	manual \| auto_accept \| deferred
`tool.input [content]`	Entrada de ferramenta serializada (primeiros 4000 caracteres)
`tool.success`	Booleano
`tool.output [content]`	Saída de ferramenta serializada (primeiros 4000 caracteres)
`tool.output_chars`	Comprimento total da saída em caracteres (use para detectar truncamento)
`tool.error_type`	Classificação de erro (presente em caso de falha)
`sheet.cells_read`	Células lidas (apenas superfície da planilha)
`sheet.cells_written`	Células gravadas (apenas superfície da planilha)
`sheet.cells_copied`	Células copiadas (apenas superfície da planilha)

Nota: O atributo tool.accept_decision registra como a decisão de permissão foi tomada: manual (o usuário aprovou esta ação específica), auto_accept (o usuário havia concedido aprovação permanente anteriormente), ou deferred (a ação foi enfileirada para revisão posterior). Use isso para auditar padrões de aprovação em sua organização.

`agent.compaction`

Um span por conversa com auto-resumo, acionado quando o contexto se aproxima do limite da janela. SpanKind: CLIENT.

Atributo	Descrição
`compaction.pre_tokens`	Contagem de tokens antes do resumo
`compaction.post_tokens`	Contagem de tokens após o resumo
`compaction.tokens_saved`	Delta
`compaction.success`	Booleano
`compaction.trigger`	Atualmente sempre reativo

Este span também carrega agent.surface, agent.vendor, session.id, user.email [claude.ai-only], user.bucket [claude.ai-only], office.platform e office.version, duplicados do span raiz para que você possa consultar eventos de compactação independentemente.

file.upload [claude.ai-only]

Um span por upload de arquivo individual, como filho do span de consulta. SpanKind: CLIENT. Este tipo de span aparece apenas quando os usuários fazem login com uma conta Claude.ai. O upload de arquivo não está disponível em implantações de provedor direto.

Atributo	Descrição
`file.upload.filename [content]`	Nome do arquivo original
`file.upload.size_bytes`	Tamanho do arquivo
`file.upload.mime_type`	Tipo MIME
`file.upload.file_id`	Identificador da API de Arquivos Anthropic
`file.upload.success`	Booleano

Eventos de span

Eventos de span são marcadores com timestamp anexados aos spans acima. Eles capturam transições de ciclo de vida e sinais equivalentes a contadores.

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}

Cada contador de produto interno também registra um evento de span com o mesmo nome no span ativo no momento, fornecendo o equivalente do fluxo de métricas dentro dos seus dados de rastreamento. O evento office_agent.token.usage é emitido em cada span agent.stream, uma vez por tipo de token diferente de zero, com atributos {token_usage.type: input | output | cacheRead | cacheCreation, token_usage.model, token_usage.token_count}. Isso espelha a forma do contador *.token.usage emitido por outros produtos Anthropic, para que um único coletor possa agregar o custo de token entre produtos agrupando em service.name.

Comportamento específico da superfície

O esquema de telemetria é consistente em todas as superfícies. Estas são as diferenças:

Sheets (Excel): os spans agent.tool_execution incluem atributos sheet.cells_read, sheet.cells_written e sheet.cells_copied. Eventos de span office_agent.cell_edit_collision_total aparecem quando um usuário está no meio de uma edição de célula enquanto uma ferramenta tenta escrever.
Documents (Word): eventos de funil de edição de documento rastreiam o ciclo de vida da edição: 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. Sem atributos sheet.cells_*.
Slides (PowerPoint): nenhum atributo ou evento específico da superfície além do esquema comum.

Reconstruindo uma sessão de usuário

Implantações Claude.ai

Filtre spans por user.email (ou user.account_uuid) e session.id.
Ordene spans agent.query por timestamp de início; cada um é um turno do usuário.
Para cada turno, user.message é o prompt e document.url é o arquivo sendo trabalhado.
Spans filhos agent.tool_execution, ordenados por timestamp, são as ações tomadas: tool.input é o que foi tentado, tool.output é o resultado, tool.accept_decision registra se o usuário aprovou explicitamente.

Implantações de provedor direto

O suplemento não tem identidade de usuário Claude.ai neste modo, portanto os spans não carregam user.email ou user.account_uuid. Para atribuir atividade a um usuário:

Filtre spans por session.id para isolar uma sessão contínua do suplemento.
Use document.url para identificar o arquivo sendo trabalhado.
Correlacione a sessão com os logs do seu provedor de identidade: eventos de entrada do Entra, logs de acesso do gateway ou o log de solicitação do seu endpoint de bootstrap (que recebe o token de ID do Entra do usuário como um cabeçalho Bearer).
Depois que uma sessão é atribuída a um usuário, a reconstrução por turno é idêntica: agent.query ordenado por timestamp, com user.message, tool.input, tool.output e tool.accept_decision fornecendo a trilha de auditoria.

Isso produz uma transcrição completa e ordenada da interação em ambos os modos de implantação.