Exportación de OpenTelemetry

La Exportación de OpenTelemetry transmite los datos de consumo de Cherri Code de tu equipo a un colector que gestionas. Cherri Code envía métricas (tokens, llamadas a herramientas y coste estimado) y registros (solicitudes de API, errores, correcciones, skills, hooks, plugins, eventos del ciclo de vida de los agentes en la nube y acciones registradas del Bot de Grok) a un único destino gestionado por el equipo. Los equipos también pueden activar el envío del contenido de las conversaciones: las instrucciones de los usuarios y las respuesta del asistente de los agentes en la nube y del Bot de Grok, así como los argumentos y resultados de las llamadas a herramientas MCP del Bot de Grok. La exportación se ejecuta en el servidor.

La Exportación de OpenTelemetry está disponible en el plan Enterprise. Los Admins la configuran en Configuración del equipo > Exportación de OpenTelemetry.

La Referencia del formato de transmisión documenta cada métrica, evento de registro y atributo.

Requisitos previos

• Un endpoint HTTPS que acepte OTLP/HTTP protobuf en /v1/metrics y /v1/logs. La ingesta de OTLP de Datadog Agent, OpenTelemetry Collector y ClickHouse/ClickStack funcionan.
• Un token Bearer o una clave de API que Cherri Code pueda enviar como encabezado de solicitud.
• El endpoint debe ser accesible desde Internet público. Cherri Code utiliza un conjunto fijo de IP de origen para el tráfico saliente.

IP de origen

Cherri Code entrega OTLP a través de un proxy de salida del servidor. El tráfico procede de estas direcciones estáticas (todas con /32):

Estas direcciones IP no se modifican sin previo aviso. Use TLS y la autenticación como control principal. Añada una lista de permitidos de IP si su red lo requiere.

Configuraciones de colectores

Cherri Code envía datos a tu colector mediante protobuf binario OTLP/HTTP. gRPC y JSON no son compatibles. Introduce la URL base HTTPS en Configuración del equipo sin el sufijo /v1; Cherri Code añade /v1/metrics y /v1/logs.

OpenTelemetry Collector básico

receivers:  otlp:    protocols:      http:        endpoint: 0.0.0.0:4318processors:  batch:exporters:  # Sustitúyelo por tu destino (datadog, clickhouse, logging, etc.)  logging:    verbosity: basicservice:  pipelines:    metrics:      receivers: [otlp]      processors: [batch]      exporters: [logging]    logs:      receivers: [otlp]      processors: [batch]      exporters: [logging]

Termina TLS delante del colector con un balanceador de carga, ingress o la configuración TLS de otelcol. Introduce https://otel.example.com en Cherri Code, no https://otel.example.com:4318/v1. Para la autenticación, termínala en el balanceador de carga o configura un encabezado estático que Cherri Code enviará, como Authorization: Bearer <token>.

Datadog Agent (ingesta de OTLP)

Activa la ingesta HTTP de OTLP y los registros en el Datadog Agent, y luego expón el Datadog Agent (o una puerta de enlace delante de él) mediante HTTPS:

logs_enabled: trueotlp_config:  receiver:    protocols:      http:        endpoint: 0.0.0.0:4318  logs:    enabled: true

Los equivalentes mediante variables de entorno son DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT=0.0.0.0:4318, DD_LOGS_ENABLED=true y DD_OTLP_CONFIG_LOGS_ENABLED=true. Expón el puerto 4318, o termina TLS en el puerto 443 y redirige mediante proxy al 4318.

En Cherri Code, la URL base es el endpoint público https:// que está delante de ese receptor. Añade los encabezados DD-API-KEY o site solo si tu gateway los espera; el Datadog Agent ya tiene api_key configurada de forma local.

Consulta la ingesta de OTLP en el Datadog Agent para obtener detalles sobre la configuración del Datadog Agent.

Databricks y destinos de tipo almacén de datos

Para destinos de almacén de datos como Databricks o ClickHouse, ejecute un colector con un receptor HTTP de OTLP y el exportador del proveedor, o reenvíe los datos mediante HTTP a su canalización de ingesta. La parte de Cherri Code es la misma: una URL base HTTPS que sirve protobuf en /v1/metrics y /v1/logs. Consuma las métricas como sumas de deltas y deduplique los registros mediante cursor.event.id.

Activar

En Configuración del equipo > Exportación de OpenTelemetry:

1. Crear destino con la URL base (sin /v1/...; Cherri Code añade las rutas) y los encabezados de autenticación
2. Probar conexión para verificar la URL y la autenticación
3. Activar. La exportación se inicia en aproximadamente un minuto.

Cada señal y familia de telemetría tiene su propio toggle. Las nuevas familias se activan de forma predeterminada, salvo que desactives auto_enable_new_families. El Contenido de las conversaciones es la excepción: permanece desactivado hasta que lo actives.

Contenido de las conversaciones

La familia conversation_content envía en flujo a tu colector el texto de las instrucciones del usuario y de las respuestas del asistente como registros cursor.conversation.user_message y cursor.conversation.assistant_message. También envía en flujo los argumentos y resultados de las llamadas a herramientas MCP del Bot de Grok como registros cursor.conversation.tool_io. Por ahora solo abarca los agentes en la nube y el Bot de Grok. Las conversaciones del IDE, la CLI y el escritorio aún no forman parte de esta familia. Es la única familia que transporta texto de mensajes o payloads de herramientas. La Referencia del formato de transmisión documenta la estructura de los registros.

Qué se envía una vez habilitados la activación del equipo y contenido de las conversaciones:

• Dos eventos de registro. cursor.conversation.user_message contiene una instrucción del usuario y cursor.conversation.assistant_message contiene la respuesta final del asistente. El nombre del evento identifica el rol. El cuerpo es el texto del mensaje.
• Depurado y limitado. Cherri Code depura el texto de los mensajes antes de exportarlo y limita el cuerpo de cada mensaje a 32 KiB. cursor.conversation.content_truncated es true cuando el cuerpo exportado es un prefijo del texto depurado.
• La E/S de herramientas va por separado. Con su toggle activado, cursor.conversation.tool_io añade los argumentos y resultados de las llamadas MCP del Bot de Grok, limitados a 8 KiB por lado. Consulta E/S de herramientas MCP.
• Misma identidad que los demás registros. Los registros incluyen los mismos IDs que todos los demás, incluidos los atributos de recurso opcionales cursor.user.*.
• Solo agentes en la nube y Bot de Grok. Las conversaciones de agentes en la nube llegan como cursor.surface=cloud_agent y las del Bot de Grok, como cursor.surface=grok_bot. Esta familia aún no exporta conversaciones del IDE, la CLI ni el escritorio. Los mensajes del Bot de Grok son independientes de la familia grok_bot_agent_actions, que requiere la grabación de acciones y transporta acciones en lugar de mensajes.

E/S de herramientas MCP

El registro cursor.grok_bot.mcp_tool_call demuestra que un Bot hizo una llamada MCP: a qué servidor, con qué herramienta, si tuvo éxito y cuánto tardó. Nunca incluye lo que el Bot envió ni lo que recibió, así que un revisor puede ver que se produjo una transición en Jira, pero no qué problema pasó a qué estado. cursor.conversation.tool_io incluye ese contenido, que se habilita con el toggle Tool I/O del destino.

Antes de activarlo, una llamada de un Bot a Jira aparece en tu colector como una fila cursor.grok_bot.mcp_tool_call cuyo cursor.tool.name indica la herramienta de transición y cuyo cursor.tool.status es success. Después de activarlo, la misma llamada genera además dos filas cursor.conversation.tool_io. La fila direction=arguments incluye el JSON que envió el Bot, como la clave del problema y el estado de destino. La fila direction=result incluye lo que devolvió Jira. Une las tres filas mediante cursor.grok_bot.tool_call.id.

Alcance y límites:

• Extractos, no payloads completos. Cada lado está limitado a 8 KiB. Un cuerpo recortado es un prefijo del texto depurado, se marca con cursor.conversation.content_truncated y no se puede analizar como JSON. La cabecera de una llamada de escritura (clave del objeto, destino, nuevo valor) cabe completa; los resultados de lectura largos se recortan.
• Contenido del resultado. Si la llamada tiene éxito, el registro del resultado incluye el texto y el contenido estructurado de la herramienta. Si falla, incluye el mensaje de error, rechazo o denegación. Cherri Code reemplaza los bytes de las imágenes por su tipo MIME.
• Secretos censurados, en la medida de lo posible. Cherri Code aplica el mismo depurador basado en patrones que usa para los comandos de shell y el texto de los mensajes: los formatos conocidos de credenciales, los bloques PEM y las direcciones de correo electrónico se sustituyen por marcadores [REDACTED: ...], de modo que una dirección de assignee se exporta como [REDACTED: Email]. También censura el valor de cualquier miembro JSON cuya clave corresponda a una credencial (password, token, api_key y similares; la Referencia del formato de transmisión los enumera), sea cual sea el aspecto del valor. La coincidencia de patrones no puede reconocer todos los secretos ni todos los datos personales. Una credencial asociada a una clave que no figura en la lista, dividida entre varios campos o en una fila de cabecera con un nombre de miembro inusual ({"k":"Authorization","v":"Basic ..."}) se exporta tal cual, al igual que un argumento que cite el mensaje de un compañero o un resultado que incluya el cuerpo de respuesta de un conector. Tu equipo asume ese riesgo residual, igual que con los prompts y las respuestas.
• Solo llamadas a conectores alojados. Las llamadas MCP del Bot de Grok que ejecuta Cherri Code (Jira, Slack, Linear y otros servidores alojados; sus filas mcp_tool_call muestran cursor.grok_bot.mcp.transport=http) generan E/S de herramientas. Los servidores stdio en la computadora del Bot de Grok, las herramientas integradas y las llamadas a herramientas del agente en la nube, el IDE y la CLI todavía no reportan payloads.

Qué exporta Cherri Code

Ámbito: cursor.telemetry 0.1.0.

Todo lo siguiente está activado de forma predeterminada para un destino nuevo, excepto conversation_content. Desactiva familias concretas en Configuración del equipo.

Métricas (temporalidad delta)

• cursor.token.usage: por cursor.token.type (input / output / cache_read / cache_creation)
• cursor.tool.calls: herramientas integradas y MCP (cursor.tool.kind)
• cursor.cost.usage: estimación aproximada en USD; no es una factura

Registros

• cursor.api.request: resumen de la llamada al modelo
• cursor.api.error: evento de error (sin mensajes sin procesar)
• cursor.api.correction: finalización de la facturación; vinculado mediante cursor.usage_event.id
• cursor.skill.activated
• cursor.hook.execution_complete
• cursor.plugin.installed
• cursor.cloud_agent.setup: started / completed / failed
• cursor.cloud_agent.artifact
• cursor.cloud_agent.pull_request: opened / creation_failed
• cursor.cloud_agent.mcp_auth_error: un servidor MCP rechazó las credenciales de la ejecución
• cursor.grok_bot.tool_result: cada llamada a herramienta integrada que hizo un Bot, con su resultado y duración
• cursor.grok_bot.tool_decision: quién permitió o rechazó una llamada a herramienta de un Bot (una persona, Auto-review, un hook o ningún control)
• cursor.grok_bot.mcp_tool_call: una llamada a herramienta de un conector (MCP) de un Bot
• cursor.grok_bot.shell_command: un comando de shell de un Bot, con los secretos eliminados, junto con el código de salida y la duración
• cursor.grok_bot.browser_navigation: una página a la que navegó el navegador del Bot
• cursor.grok_bot.computer_use_session: un resumen de sesión de computer use de un Bot
• cursor.grok_bot.file_transfer: un archivo transferido entre la computadora del Bot y la máquina de un usuario o una cuenta en la nube
• cursor.grok_bot.message_delivery: un mensaje que envió un Bot, a dónde se envió y si llegó
• cursor.grok_bot.routine_run: una ejecución de rutina finalizada
• cursor.grok_bot.guardrail: un bucle detectado, un sitio que bloquea al Bot o una solicitud de aprobación y su tiempo de espera
• cursor.grok_bot.delegation: trabajo que un Bot delegó a un subagente o agente en la nube, y el resultado devuelto
• cursor.conversation.user_message: una instrucción del usuario, depurada; requiere activación
• cursor.conversation.assistant_message: una respuesta del asistente, depurada; requiere activación
• cursor.conversation.tool_io: una de las partes (argumentos o resultado) de una llamada a herramienta MCP del Bot de Grok, depurada; requiere activación

Los eventos cursor.grok_bot.*, y cursor.skill.activated cuando un Bot lee una skill, contienen datos de grabación de acciones. Solo se envían después de que un administrador de equipo active la grabación de acciones en la página del Bot de Grok del panel de control; es un ajuste de equipo, desactivado de forma predeterminada, y el Modo de privacidad (Legacy) lo desactiva forzosamente.

Los eventos registrados son metadatos sobre lo que hizo el Bot, nunca el contenido con el que trabajó. En estos eventos nunca se exportan los argumentos ni los resultados de las herramientas, las rutas ni los nombres de archivo, el cuerpo ni los destinatarios de los mensajes, las credenciales ni los datos de tarjetas; los argumentos y resultados de MCP solo se envían en el registro cursor.conversation.tool_io, que requiere activación. El texto de los comandos de shell se exporta tras eliminar los secretos y con un límite de 8 KiB; a las URL del navegador se les quitan las cadenas de consulta, los fragmentos y las credenciales; y cuando una herramienta actuó sobre un sitio, solo se indica el nombre de host. La Referencia del formato de transmisión enumera todos los atributos de cada evento.

Los eventos cursor.conversation.* contienen el texto de los mensajes o los payload de herramientas y solo se envían después de que el equipo los active explícitamente y el destino active el toggle correspondiente a ese tipo. Consulta Contenido de las conversaciones y E/S de herramientas MCP.

Familias (controles de administrador; todas activadas de forma predeterminada excepto conversation_content)

• model_usage: métricas de tokens y coste; api.request / api.error / api.correction
• tool_calls: métrica tool.calls
• skills_hooks_plugins: registros de skill / hook / plugin, incluidas las activaciones de skills de un Bot
• cloud_agents: registros cloud_agent.*
• grok_bot_agent_actions: registros de acciones grok_bot.*; requiere grabación de acciones (Enterprise)
• conversation_content: registros de mensajes y de E/S de herramientas conversation.*; desactivada de forma predeterminada

Atributos útiles

• Recurso: service.name=cursor, cursor.team.id, superficie/punto de entrada y los atributos opcionales cursor.user.id, cursor.user.account_id y cursor.user.email; consulta Unir sesiones para atribuir los registros a una persona. El tráfico del Bot de Grok se exporta como cursor.surface=grok_bot en todas las familias; desktop ya no lo incluye. Una interacción iniciada por una rutina se exporta como cursor.entrypoint=automation.
• Registros: cursor.event.id (deduplicar) y cursor.request.id / cursor.conversation.id / cursor.usage_event.id cuando estén presentes
• Registros del Bot de Grok: cursor.grok_bot.turn.id, cursor.grok_bot.event.sequence, cursor.grok_bot.tool_call.id y cursor.grok_bot.decision.id; consulta Unir sesiones

Entrega

• Las métricas se entregan como máximo una vez. Las sumas delta pueden presentar breves interrupciones tras un error.
• Los registros se entregan al menos una vez. Deduplica por cursor.event.id para obtener consultas de exactamente una vez.
• No hay carga retroactiva de datos anteriores a la creación del destino.
• Editar el endpoint o las credenciales conserva el destino. Deshabilitarlo o eliminarlo descarta los datos en tránsito.

Autenticación

Cherri Code almacena los encabezados cifrados. Para rotar las credenciales, edita el destino y guarda. Los cambios se aplicarán en unos 30 segundos.

Limitaciones

• El coste no equivale a la facturación. cursor.cost.usage es una estimación aproximada. Una serie abarca tanto el consumo de la cuota incluida como el uso bajo demanda. En el caso de BYOK, refleja únicamente la tasa de tokens de Cherri Code, no el gasto del proveedor. Usa las API de Admin y facturación para consultar las facturas.
• Desactivar o eliminar un destino descarta los datos en tránsito. Rota las credenciales editando el destino en lugar de eliminarlo y volver a añadirlo.
• Los registros pueden llegar más de una vez. La entrega es de al menos una vez. Deduplica por cursor.event.id.
• Sin contenido de instrucciones ni payloads de herramientas a menos que actives la opción. El texto de los mensajes y los argumentos y resultados de las herramientas MCP solo se envían a través de la familia conversation_content, que requiere activación. Todos los demás eventos de registro incluyen ids, recuentos y atributos de baja cardinalidad. Consulta contenido de las conversaciones y E/S de herramientas MCP.
• Sin contexto de trazas ni carga retroactiva histórica. Los registros exportados no incluyen los campos trace_id ni span_id de OpenTelemetry, y Cherri Code no envía trazas. La exportación comienza al activar el destino.
• Los puntos de datos de las métricas no incluyen IDs de correlación. Usa atributos de registro para unir datos por conversación. Consulta Unir sesiones.
• Las métricas solo son deltas. Suma los deltas por serie. Un procesador estricto de delta a acumulativo puede descartar puntos con el tiempo de finalización invertido.

Unir sesiones

Las métricas (cursor.token.usage, cursor.tool.calls, cursor.cost.usage) son datos agregados. Los puntos de datos no incluyen conversation.id, request.id ni usage_event.id. Esto mantiene limitada la cardinalidad de las métricas. Para análisis por sesión o solicitud, usa los registros.

Qué significa cada id

• cursor.conversation.id es la clave de sesión. En el IDE y la CLI, es el UUID del chat de composer. Para los agentes en la nube, es el id de agente bc-... visible para el cliente. Para el Bot de Grok (grok_bot.* y cualquier registro con cursor.surface=grok_bot), es el identificador del Bot, y ese valor también es su id de conversación. El mismo valor aparece en los registros api.request, api.error, skill.activated, hook.execution_complete, cloud_agent.*, grok_bot.* y (cuando el equipo lo activa) conversation.* de esa ejecución cuando están disponibles.
• cursor.usage_event.id es la clave por solicitud en api.request, api.error y api.correction. Úsala para conciliar las exportaciones de consumo y facturación de Cherri Code, y para aplicar correcciones.
• cursor.request.id es un id opcional por llamada en la mayoría de los registros. Nunca aparece en api.correction, cloud_agent.* ni grok_bot.*.
• cursor.event.id es solo una clave de deduplicación, no una clave para unir distintos tipos de eventos.

Atribuir registros a una persona

cursor.user.account_id es el id del miembro en la Admin API. Únelo con id en la respuesta de GET /teams/members para identificar a la persona detrás de un registro. cursor.user.email identifica directamente al miembro. Ambos son opcionales y solo aparecen junto con cursor.user.id, así que no exijas que estén en todos los registros. La tabla de atributos de recurso incluye las reglas de presencia.

Agrupar la actividad del Bot de Grok

Cuatro atributos vinculan los registros de un Bot. cursor.grok_bot.turn.id identifica la interacción: aparece en todos los registros de grabación de acciones de la interacción y, para cursor.surface=grok_bot, también en los registros api.request y api.error de la interacción, por lo que las llamadas al modelo se unen con las acciones por interacción. Dentro de una interacción, cursor.grok_bot.event.sequence ordena las acciones sin depender de los relojes del cliente; ordena por este atributo, no por marca de tiempo, y no esperes que sea consecutivo. cursor.grok_bot.tool_call.id agrupa las filas de una llamada a herramienta, y cursor.grok_bot.decision.id une una solicitud de aprobación, la espera asociada y la respuesta de la persona.

Las acciones de los subagentes incluyen su propio cursor.grok_bot.turn.id y cursor.grok_bot.subagent.id, además de cursor.grok_bot.root_turn.id, la interacción visible para el usuario a la que sirven. Agrupa por root_turn.id para agregar las acciones de un subagente a la interacción que lo generó.

Por ejemplo, una interacción en la que el Bot ejecutó un comando que Auto-review escaló al usuario puede generar estos registros:

Todas las filas comparten el cursor.conversation.id del Bot. Agrupa por turn-1 para reconstruir la interacción, incluidas sus llamadas al modelo. Agrupa por call-7 para seguir la única llamada al shell: Auto-review la rechazó, una tarjeta le preguntó al usuario, este la permitió y la herramienta se ejecutó y devolvió success. card-2 vincula la pregunta y su espera con la respuesta. El texto del comando en sí aparece en la fila cursor.grok_bot.shell_command de la interacción, que no incluye tool_call.id. Estos campos son atributos de registro personalizados, no ids de traza ni de span de OpenTelemetry.

Con el contenido de las conversaciones habilitado, los registros cursor.conversation.user_message y cursor.conversation.assistant_message del Bot incluyen el mismo cursor.conversation.id. Une por ese campo para situar la instrucción y la respuesta junto a las solicitudes al modelo y las acciones registradas del Bot. Los registros de mensajes incluyen su propio cursor.conversation.turn.id opcional. No te bases en cursor.grok_bot.turn.id ni en cursor.request.id para estos registros.

Con E/S de herramientas MCP habilitada, cada llamada a MCP añade dos registros cursor.conversation.tool_io (direction=arguments y direction=result) que incluyen el cursor.grok_bot.tool_call.id de la llamada y, cuando están presentes, su turn.id y su event.sequence. Agrupa por tool_call.id para situar los argumentos y el resultado junto a las filas mcp_tool_call y tool_decision de la llamada.

Receta: clasificar sesiones por tokens y luego añadir skills y herramientas

1. Toma las filas de registro cursor.api.request. Suma cursor.api.request.input_tokens y output_tokens (y los campos de caché si los necesitas) agrupando por cursor.conversation.id. Así obtienes los totales de tokens por sesión, algo que las métricas no pueden proporcionar.
2. Clasifica las conversaciones por esa suma o por el coste estimado.
3. Haz un left join de otros registros por el mismo cursor.conversation.id:
   • cursor.skill.activated muestra qué skills se ejecutaron
   • cursor.hook.execution_complete muestra los hooks
   • cursor.cloud_agent.* muestra la configuración, las pull requests, los artefactos y los fallos de autenticación de MCP (solo agentes en la nube)
   • cursor.grok_bot.* muestra lo que hizo un Bot (solo Bot de Grok, con la grabación de acciones activada)
   • cursor.conversation.user_message y cursor.conversation.assistant_message muestran las instrucciones y las respuestas (agentes en la nube y Bot de Grok, solo si se ha activado conversation_content)
   • cursor.conversation.tool_io muestra lo que envió y recibió cada llamada a MCP de Bot de Grok (Bot de Grok, solo si se ha activado la E/S de herramientas)
4. cursor.tool.calls es solo una métrica, por lo que no tiene id de conversación. Obtén las tasas de uso de herramientas de toda la organización a partir de la métrica. En Bot de Grok, cursor.grok_bot.tool_result y cursor.grok_bot.mcp_tool_call ofrecen atribución de herramientas por Bot y por interacción; en otras superficies, estos datos aún no se envían.

cursor.cost.usage también es solo una métrica. Para clasificar sesiones por coste, haz una estimación a partir de los totales de tokens de api.request y tus propias tarifas, u obtén el gasto de las API de Admin y facturación y une por cursor.usage_event.id cuando esté disponible.

Receta: aplicar una corrección de facturación

1. Busca los registros cursor.api.correction.
2. Une por cursor.usage_event.id con los registros api.request y api.error que comparten ese id.
3. Trata todo el grupo como no facturado.

Advertencias

• Los subagentes tienen su propio id de conversación. En las acciones de Bot de Grok, agrúpalas con cursor.grok_bot.root_turn.id; en otras superficies, la agregación en el elemento padre aún no se exporta.
• Si necesitas vistas en las que cada evento se cuente una sola vez, deduplica las filas de registro por cursor.event.id antes de unir.
• Los registros de versiones anteriores de Bot de Grok omiten cursor.grok_bot.event.sequence y cursor.grok_bot.initiated_by. Trata ambos como opcionales.

Política de cambios

Pueden aparecer nuevas métricas y eventos a medida que se amplía la cobertura. auto_enable_new_families controla si se activan automáticamente. Los cambios de nombre y las eliminaciones se notifican explícitamente. La Referencia del formato de transmisión documenta toda la superficie de atributos.