Configurar un recopilador personalizado de OpenTelemetry para agentes de Office

Puedes enrutar la telemetría de auditoría completa de los agentes de Office a tu propio recopilador de OpenTelemetry (OTEL). Esto le da a tu organización control total sobre la retención, el cifrado y la integración con tu SIEM o plataforma de observabilidad.

Esta guía cubre cómo habilitar un recopilador personalizado, qué datos recibirás y la referencia completa del esquema de spans.

Los recopiladores OTEL personalizados están disponibles para organizaciones de Claude Enterprise y para implementaciones de proveedores directos (Amazon Bedrock, Google Vertex AI o una puerta de enlace).

Lo que recibirás

Cuando configures un recopilador personalizado, los agentes de Office envían datos de rastreo que cubren cada turno del usuario. Cada turno produce un árbol de spans que captura el prompt, las llamadas al modelo, las ejecuciones de herramientas, las cargas de archivos y los eventos de compactación de contexto.

Tu recopilador recibe todos los atributos de span, incluidos los que contienen contenido generado por el usuario (texto de prompt, entradas y salidas de herramientas, URLs de documentos y nombres de archivo). No se redactan ni filtran atributos. El texto de respuesta del asistente no se incluye en los datos de span emitidos. Tu organización es propietaria de estos datos.

Importante: Las métricas no se envían a recopiladores personalizados. El espacio de nombres del contador office_agent.* se enruta solo a Anthropic. Sin embargo, cada incremento de contador también aparece como un evento de span en el span activo, por lo que las mismas señales están disponibles en tus trazas.

La telemetría se envía a través de OTLP/HTTP a tu punto de conexión en {your_url}/v1/traces. gRPC no es compatible porque el complemento se ejecuta en una WebView de Office.

Habilitar un recopilador personalizado

La configuración varía según cómo tu organización se autentica con Claude.

Importante: Cuando se configura un punto de conexión personalizado, la telemetría va exclusivamente a tu recopilador. Los spans no se envían de forma dual a Anthropic.

Organizaciones de Claude Enterprise (OAuth)

Un administrador de la organización establece el punto de conexión del recopilador en la consola de administración de Claude.ai en Configuración de la organización > Agentes de Office. La configuración se aplica en toda la organización.

Configuración	Descripción
`otlp_endpoint`	URL base de tu recopilador OTLP. El complemento añade /v1/traces. Se recomienda encarecidamente HTTPS.
`otlp_headers`	Encabezados de autenticación opcionales, formateados según la especificación de OpenTelemetry: clave1=valor1,clave2=valor2

El protocolo debe ser OTLP basado en HTTP. gRPC se rechaza en el momento de la configuración.

Implementaciones de proveedores directos (Amazon Bedrock, Google Vertex AI, puerta de enlace)

Para implementaciones que se autentican contra tu propio proveedor de modelo en lugar de Claude.ai, el punto de conexión del recopilador se proporciona a través de uno de tres canales de configuración. Los tres utilizan las mismas dos claves.

Recomendado: Usa el complemento claude-in-office para Claude Code. Te guía a través de la generación del manifiesto, el registro de atributos de extensión de Entra y la configuración de un punto de conexión de arranque con otlp_endpoint y otlp_headers preconfigurados. Los tres canales a continuación se documentan como referencia y para configuración manual.

Clave	Formato	Descripción
`otlp_endpoint`	URL HTTPS	URL base de tu recopilador OTLP. El complemento elimina cualquier barra diagonal final y añade /v1/traces.
`otlp_headers`	clave1=valor1,clave2=valor2	Encabezados de autenticación opcionales. Mismo formato que la variable de entorno OTEL_EXPORTER_OTLP_HEADERS de OpenTelemetry.

Si otlp_endpoint no está establecido o está vacío, no se configura ningún recopilador personalizado y el complemento vuelve al comportamiento predeterminado.

Nota: Estos canales de configuración se aplican solo a implementaciones de Microsoft Office. Los complementos de Google Workspace se configuran por separado.

Canal 1: Parámetro de URL de manifiesto

Añade las claves como parámetros de cadena de consulta a la URL del panel de tareas en tu manifiesto de complemento personalizado:

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

Codifica en URL los valores. Esto aplica la configuración a cada usuario que instale el manifiesto.

Canal 2: Extensión de directorio de Azure Entra ID

Para configuración por usuario, registra las claves como atributos de extensión de directorio de Entra ID y asígnalas a través de Microsoft Graph. El complemento las lee del token de ID del usuario utilizando Autenticación de aplicación anidada (NAA).

Los nombres de reclamación en el token de ID emitido siguen el formato de extensión de directorio de Azure:

Reclamación	Se asigna a
`extn.otlp_endpoint`	otlp_endpoint
`extn.otlp_headers`	otlp_headers

Establece estos por usuario con un PATCH de Graph contra el objeto de usuario. Azure codifica los valores de extensión de directorio como matrices de un solo elemento en el token de ID; el complemento los desenvuelve automáticamente. Este canal requiere entra_sso=1 en los parámetros de URL del manifiesto para habilitar la adquisición de tokens NAA.

Canal 3: Respuesta del punto de conexión de arranque

Si tu implementación utiliza un punto de conexión de arranque (un punto de conexión JSON que tu organización aloja y que el complemento llama al iniciarse), incluye las claves en el cuerpo de la respuesta:

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

La URL del punto de conexión de arranque se configura a través de bootstrap_url en los parámetros de URL del manifiesto o en una notificación de Entra extn.bootstrap_url. Si se adquirió un token de ID de Entra, se pasa al punto de conexión de arranque como encabezado de autorización Bearer para que tu punto de conexión pueda autenticar al usuario antes de devolver la configuración por usuario.

Precedencia

Cuando varios canales proporcionan un valor, los canales posteriores anulan los anteriores: primero se leen los parámetros del manifiesto, luego las notificaciones de Entra, luego la respuesta de arranque. La respuesta de arranque gana.

Si aún no lo has hecho, la ruta más rápida es el complemento claude-in-office.

Modos de implementación

La exportación de recopilador personalizado está disponible en ambos modos de implementación:

Claude.ai Enterprise (OAuth): registro de auditoría completo que incluye identidad del usuario (user.email, user.account_uuid, organization.id), metadatos del servidor MCP y registros de carga de archivos.
Proveedor directo (Bedrock, Vertex AI, puerta de enlace): registro de auditoría principal (indicaciones, entradas y salidas de herramientas, URL de documentos) pero sin identidad del usuario, sin metadatos de MCP y sin intervalos de carga de archivos. La atribución de usuarios requiere correlacionar session.id con tus propios registros del proveedor de identidad.

La carga útil de auditoría principal es idéntica en ambos modos. Las implementaciones de proveedor directo carecen de contexto de cuenta de Claude.ai, por lo que los atributos derivados del perfil de usuario u organización de Claude.ai están ausentes. Consulta las etiquetas [claude.ai-only] en el esquema de intervalo a continuación para obtener la lista completa.

Etiquetas de superficie y proveedor

Cada intervalo incluye dos etiquetas que identifican qué aplicación de Office y plataforma lo generaron. Úsalas como tus dimensiones principales para filtrado y paneles.

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

Referencia de intervalo

Cada turno del usuario produce un árbol padre/hijo de hasta cinco tipos de intervalo. Los atributos marcados [content] llevan datos generados por el usuario; estos forman tu carga útil de auditoría. Los atributos marcados [claude.ai-only] se rellenan solo cuando el usuario inicia sesión con una cuenta de Claude; están ausentes en implementaciones de Bedrock, Vertex AI y puerta de enlace. Los atributos ausentes se omiten del intervalo por completo (sin clave con valor nulo).

El intervalo file.upload y todos los atributos mcp.* también son [claude.ai-only], ya que la carga de archivos y las conexiones del servidor MCP son características de la plataforma Claude.

Para implementaciones de proveedor directo, la identidad del usuario debe correlacionarse a través de session.id y document.url, unidos contra los registros de sesión de tu proveedor de identidad.

Atributos de recursos

Estos atributos aparecen en cada intervalo:

Atributo	Descripción
`service.name`	Valor fijo: office-agent
`service.version`	Valor fijo: 1.0.0
`git.sha`	Identificador de confirmación de compilación

agent.query (intervalo raíz)

Un intervalo por turno del usuario. Este es la raíz del árbol de intervalos y lleva identidad de sesión, contexto de documento y estado del servidor MCP. SpanKind: INTERNAL.

Atributo	Descripción
`agent.surface`	sheet \| doc \| slide
`agent.vendor`	m
`user.message [content]`	La indicación del usuario (primeros 4000 caracteres)
`session.id`	Identificador de sesión opaco
`user.email [claude.ai-only]`	Dirección de correo electrónico del usuario
`user.bucket [claude.ai-only]`	Depósito de hash determinista (SHA-256 de correo electrónico, mod 30)
`user.account_uuid [claude.ai-only]`	UUID de cuenta de Claude
`document.url [content]`	URL del documento de Office abierto
`organization.id [claude.ai-only]`	UUID de organización de Claude
`org.rate_limit_tier [claude.ai-only]`	Nivel de suscripción de Claude
`org.type [claude.ai-only]`	Tipo de organización de Claude
`agent.selected_model`	Modelo seleccionado por el usuario para esta sesión
`office.platform`	PC \| Mac \| OfficeOnline \| iOS \| Android \| Universal
`office.version`	Número de compilación de 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 exitosamente
`mcp.failed_count [claude.ai-only]`	Número de servidores MCP que no se conectaron
`mcp.fetch_status [claude.ai-only]`	success \| error \| timeout \| no_auth \| not_attempted
`mcp.fetch_duration_ms [claude.ai-only]`	Duración de la obtención del registro MCP
`mcp.fetch_http_status [claude.ai-only]`	Código de estado HTTP de obtención del registro MCP
`mcp.servers [content] [claude.ai-only]`	Detalles serializados del servidor MCP (nombres, conteos de herramientas, mensajes de error)
`file.upload.count [claude.ai-only]`	Número de archivos adjuntos en este turno
`file.upload.total_bytes [claude.ai-only]`	Total de bytes cargados
`file.upload.image_count [claude.ai-only]`	Número de adjuntos de imagen
`file.upload.document_count [claude.ai-only]`	Número de adjuntos de documento
`file.upload.other_count [claude.ai-only]`	Número de otros adjuntos
`error.name`	Nombre de clase de excepción (presente en caso de fallo)
`agent.query_phase`	Fase en la que falló la consulta (presente en caso de fallo)

agent.stream

Un span por cada llamada a la API de Claude, como hijo del span de consulta. SpanKind: CLIENT.

Atributo	Descripción
`model`	ID del modelo utilizado para esta llamada
`max_tokens`	Tokens de salida máximos solicitados
`agent.message_count`	Número de mensajes en la conversación al inicio de la transmisión
`input_tokens`	Tokens de entrada facturados (de la respuesta de API)
`output_tokens`	Tokens de salida facturados (de la respuesta de API)
`cache_read_tokens`	Tokens servidos desde la caché de indicaciones
`cache_creation_tokens`	Tokens escritos en la caché de indicaciones
`stop_reason`	end_turn \| tool_use \| max_tokens \| etc.
`request_id`	Encabezado request-id de la API de Anthropic, utilizable para correlación de soporte

Nota sobre almacenamiento en caché de indicaciones: El complemento solicita almacenamiento en caché de indicaciones incondicionalmente. Los atributos cache_read_tokens y cache_creation_tokens se establecen a partir de la respuesta de API del proveedor y se omiten cuando la respuesta no los incluye. El almacenamiento en caché de indicaciones está disponible para la Plataforma de Desarrolladores de Claude; en el momento de escribir esto, Amazon Bedrock y Google Vertex AI aún no devuelven estos campos a través del cliente que utiliza el complemento. Cuando el soporte llegue a su proveedor, estos atributos comenzarán a aparecer automáticamente.

`agent.tool_execution`

Un intervalo por llamada de herramienta, como elemento secundario del intervalo de transmisión. SpanKind: INTERNAL. Este es el registro principal de qué acciones realizó el modelo contra el documento.

Atributo	Descripción
`tool_name`	Identificador de herramienta (p. ej. get_cell_ranges, execute_office_js, edit_slide_xml)
`tool.id`	ID único de esta invocación de herramienta
`tool.caller`	servidor \| cliente
`tool.owner`	first_party \| mcp \| servidor
`tool.read_write`	lectura \| escritura \| lectura_escritura
`tool.accept_decision`	manual \| auto_accept \| deferred
`tool.input [content]`	Entrada de herramienta serializada (primeros 4000 caracteres)
`tool.success`	Booleano
`tool.output [content]`	Salida de herramienta serializada (primeros 4000 caracteres)
`tool.output_chars`	Longitud completa de salida en caracteres (utilizar para detectar truncamiento)
`tool.error_type`	Clasificación de error (presente en caso de fallo)
`sheet.cells_read`	Celdas leídas (solo superficie de hoja)
`sheet.cells_written`	Celdas escritas (solo superficie de hoja)
`sheet.cells_copied`	Celdas copiadas (solo superficie de hoja)

Nota: El atributo tool.accept_decision registra cómo se tomó la decisión de permiso: manual (el usuario aprobó esta acción específica), auto_accept (el usuario había otorgado previamente aprobación permanente), o deferred (la acción fue puesta en cola para revisión posterior). Utilice esto para auditar patrones de aprobación en toda su organización.

`agent.compaction`

Un intervalo por conversación de auto-resumen, activado cuando el contexto se aproxima al límite de ventana. SpanKind: CLIENT.

Atributo	Descripción
`compaction.pre_tokens`	Recuento de tokens antes del resumen
`compaction.post_tokens`	Recuento de tokens después del resumen
`compaction.tokens_saved`	Delta
`compaction.success`	Booleano
`compaction.trigger`	Actualmente siempre reactivo

Este intervalo también lleva agent.surface, agent.vendor, session.id, user.email [claude.ai-only], user.bucket [claude.ai-only], office.platform, y office.version, duplicados del intervalo raíz para que puedas consultar eventos de compactación de forma independiente.

file.upload [claude.ai-only]

Un intervalo por carga de archivo individual, como hijo del intervalo de consulta. SpanKind: CLIENT. Este tipo de intervalo solo aparece cuando los usuarios inician sesión con una cuenta de Claude.ai. La carga de archivos no está disponible en implementaciones de proveedores directos.

Atributo	Descripción
`file.upload.filename [content]`	Nombre de archivo original
`file.upload.size_bytes`	Tamaño del archivo
`file.upload.mime_type`	Tipo MIME
`file.upload.file_id`	Identificador de API de Archivos de Anthropic
`file.upload.success`	Booleano

Eventos de intervalo

Los eventos de intervalo son marcadores con marca de tiempo adjuntos a los intervalos anteriores. Capturan transiciones de ciclo de vida y señales 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 producto interno también registra un evento de intervalo con el mismo nombre en el intervalo actualmente activo, proporcionando el equivalente del flujo de métricas dentro de tus datos de rastreo. El evento office_agent.token.usage se emite en cada intervalo agent.stream, una vez por tipo de token distinto de cero, con atributos {token_usage.type: input | output | cacheRead | cacheCreation, token_usage.model, token_usage.token_count}. Esto refleja la forma del contador *.token.usage emitido por otros productos de Anthropic, por lo que un único recopilador puede agregar el costo de tokens entre productos agrupando por service.name.

Comportamiento específico de la superficie

El esquema de telemetría es consistente en todas las superficies. Estas son las diferencias:

Hojas (Excel): los intervalos agent.tool_execution incluyen atributos sheet.cells_read, sheet.cells_written, y sheet.cells_copied. Los eventos de intervalo office_agent.cell_edit_collision_total aparecen cuando un usuario está editando una celda mientras una herramienta intenta escribir.
Documentos (Word): los eventos del embudo de edición de documentos rastrean el ciclo de vida de la edición: 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. Sin atributos sheet.cells_*.
Diapositivas (PowerPoint): sin atributos o eventos específicos de la superficie más allá del esquema común.

Reconstruyendo una sesión de usuario

Implementaciones de Claude.ai

Filtra intervalos por user.email (o user.account_uuid) y session.id.
Ordena intervalos agent.query por marca de tiempo de inicio; cada uno es un turno del usuario.
Para cada turno, user.message es el mensaje y document.url es el archivo en el que se está trabajando.
Los intervalos secundarios agent.tool_execution, ordenados por marca de tiempo, son las acciones realizadas: tool.input es lo que se intentó, tool.output es el resultado, tool.accept_decision registra si el usuario aprobó explícitamente.

Implementaciones de proveedores directos

El complemento no tiene identidad de usuario de Claude.ai en este modo, por lo que los intervalos no llevan user.email ni user.account_uuid. Para atribuir actividad a un usuario:

Filtra intervalos por session.id para aislar una sesión de complemento continua.
Utiliza document.url para identificar el archivo en el que estás trabajando.
Correlaciona la sesión con los registros de tu proveedor de identidad: eventos de inicio de sesión de Entra, registros de acceso de puerta de enlace o el registro de solicitudes del punto de conexión de arranque (que recibe el token de Entra ID del usuario como encabezado Bearer).
Una vez que una sesión se atribuye a un usuario, la reconstrucción por turno es idéntica: agent.query ordenados por marca de tiempo, con user.message, tool.input, tool.output y tool.accept_decision proporcionando el registro de auditoría.

Esto produce una transcripción completa y ordenada de la interacción en ambos modos de implementación.