Referência do protocolo de exportação do OpenTelemetry

Complemento da Exportação do OpenTelemetry. Toda a especificação do protocolo: todas as métricas, eventos de log, atributos, enums e regras de presença.

A especificação é aditiva. Aceite atributos, eventos e valores de enum desconhecidos. Renomeações e remoções são comunicadas explicitamente.

Transporte e escopo

• Protobuf binário via OTLP/HTTP (application/x-protobuf), POST
• Endpoints: <base>/v1/metrics e <base>/v1/logs
• Escopo: cursor.telemetry / 0.1.0

Atributos do recurso

Um recurso por agrupamento de (equipe, usuário, Surface, ponto de entrada, versão da Surface).

Famílias

Os IDs de família correspondem aos controles em Configurações da equipe. Todas vêm ativadas por padrão em um novo destino, exceto conversation_content, que permanece desativada até que a equipe faça a adesão e o destino ative o controle de cada tipo (consulte Conteúdo da conversa).

A família grok_bot_agent_actions, assim como o skill.activated quando emitido por um Bot, contém dados de Action Recording. Esses dados só são enviados depois que um admin da equipe ativa o Action Recording na página do Cherri Bot do dashboard. O Privacy Mode (legado) força a gravação a ficar desativada.

Métricas

Todas as métricas são somas monotônicas de delta. Os datapoints das métricas não carregam IDs de correlação; estes aparecem apenas nos logs.

Consuma as métricas como somas de deltas por série. Uma série é composta pelo recurso, pelo nome da métrica e pelo conjunto exato de atributos do datapoint. As janelas da mesma série podem se sobrepor entre flushes.

cursor.token.usage

Unidade {token}. Família model_usage.

cursor.tool.calls

Unidade {call}. Família tool_calls. Valor 1 por chamada de ferramenta concluída.

cursor.cost.usage

Unidade USD (double). Família model_usage. Custo estimado, na medida do possível, no momento do evento, não é uma fatura. Sujeito a cursor.api.correction. Para BYOK, esta é somente a Taxa de Tokens do Cherri Code, não os gastos do provedor.

Eventos de log

Níveis de severidade: INFO=9, WARN=13, ERROR=17.

Atributos comuns de logs

cursor.api.request

INFO, corpo api_request. Família model_usage.

cursor.api.error

ERROR, corpo api_error. Família model_usage. Não há mensagens de erro brutas. Atributos de tipo e status com baixa cardinalidade estão planejados; não dependa deles ainda.

cursor.api.correction

WARN, corpo api_correction_<kind>. Família model_usage. Finalização do faturamento: o evento de uso não foi cobrado retroativamente. Faça a associação por cursor.usage_event.id e descarte todo o grupo para fins de faturamento. Deliberadamente não inclui cursor.model.name.

cursor.skill.activated

INFO, corpo skill_activated. Família skills_hooks_plugins.

Um Bot que lê um SKILL.md exporta este mesmo evento com cursor.surface=grok_bot, e o registro inclui os atributos compartilhados grok_bot.* para que possa ser associado às demais ações do turno. cursor.skill.name é o slug da pasta da skill, cursor.skill.trigger é agent_read ou skill_name_in_prompt (skills invocadas com / ou @ ainda não são registradas), e cursor.skill.source é builtin para skills gerenciadas pelo Cherri Code, plugin para skills de plugins instalados, user para as skills do próprio Bot e, nos demais casos, segue a mesma classificação de qualquer outra surface. cursor.grok_bot.tool_call.id é o id da chamada Read que ativou a skill e permite associá-la à respectiva linha tool_result. As ativações do Bot incluem cursor.conversation.id, mas nunca cursor.request.id, e só são enviadas quando o Action Recording está ativado.

cursor.hook.execution_complete

INFO (ERROR para failed / timeout), corpo hook_execution_complete. Família skills_hooks_plugins.

cursor.plugin.installed

INFO, corpo plugin_installed. Família skills_hooks_plugins. Sem conversation.id (a instalação não está no escopo de uma conversa).

cursor.cloud_agent.pull_request

INFO (opened) / WARN (creation_failed), corpo cloud_agent_pull_request_<kind>. Família cloud_agents. conversation.id = bc-....

creation_failed é emitido em tempo real. opened pode ser esparso enquanto o produtor é lançado gradualmente.

cursor.cloud_agent.setup

INFO (started / completed) / ERROR (failed), corpo cloud_agent_setup_<kind>. Família cloud_agents. conversation.id = bc-....

cursor.cloud_agent.artifact

INFO, corpo cloud_agent_artifact_created. Família cloud_agents. conversation.id = bc-....

cursor.cloud_agent.mcp_auth_error

ERROR, corpo cloud_agent_mcp_auth_error. Família cloud_agents. conversation.id = bc-....

Um servidor MCP que você conectou rejeitou as credenciais da execução. As chamadas de ferramenta desse servidor falharam, mas a execução continuou. ERROR porque somente você pode corrigir a integração; crie um alerta para detectar Automações e agentes em nuvem que perdem silenciosamente um servidor MCP.

Atributos grok_bot.* compartilhados

O próprio bot é identificado por cursor.conversation.id em todo registro grok_bot.*, e esse valor é o conversation id do Bot; cursor.grok_bot.subagent.id identifica um subagente quando um deles atuou. Os eventos grok_bot.* transportam as ações do Bot registradas pelo Action Recording. Família grok_bot_agent_actions. Todo registro tem cursor.surface=grok_bot.

Cada evento contém metadados sobre uma ação, nunca o conteúdo dela. Argumentos e resultados de ferramentas, caminhos e nomes de arquivos, corpos e destinatários de mensagens, credenciais, dados de cartão e o raciocínio do classificador do Auto-review nunca são exportados nesses eventos; argumentos e resultados de MCP são enviados apenas no registro opcional cursor.conversation.tool_io. As exceções são indicadas em cada evento: o texto do comando de shell (com secrets removidos e limitado a 8 KiB), a URL normalizada e o título da página no navegador, e hostnames simples. Todo campo de texto livre passa por uma remoção de padrões de credenciais, números de cartão de pagamento e tokens OAuth antes de chegar ao seu coletor.

Cada evento também carrega estes atributos:

cursor.grok_bot.mcp_tool_call

INFO (ERROR para o status failure), corpo grok_bot_mcp_tool_call. família grok_bot_agent_actions. Uma chamada de ferramenta MCP feita por um Bot. Esta linha nunca contém os argumentos ou resultados da ferramenta. Para chamadas http, uma equipe com o tool I/O habilitado os recebe como dois registros cursor.conversation.tool_io, associados a esta linha por cursor.grok_bot.tool_call.id.

cursor.grok_bot.tool_call.id está presente em todas as chamadas MCP. As chamadas de conector, incluindo as ferramentas de navegador no computador do Bot, são registradas aqui e nunca como tool_result, de modo que cada chamada de ferramenta é registrada uma única vez.

cursor.grok_bot.shell_command

INFO (WARN quando bloqueado), corpo grok_bot_shell_command. Família grok_bot_agent_actions. Um shell command que um bot executou ou foi impedido de executar. O registro é gravado quando o comando é concluído e mantém o horário de emissão como timestamp; por isso, o registro de um comando longo chega bem depois do seu timestamp.

cursor.grok_bot.browser_navigation

INFO, corpo grok_bot_browser_navigation. Família grok_bot_agent_actions. conversation.id é o identificador do Bot.

cursor.grok_bot.computer_use_session

INFO, corpo grok_bot_computer_use_session. Family grok_bot_agent_actions. Resumo de uma sessão de subagent de computer-use: apenas contagens e tempo total. Sem coordenadas, texto digitado ou capturas de tela. cursor.grok_bot.turn.id é o turno pai que invocou o subagent, cursor.grok_bot.subagent.id é o próprio subagent, cursor.grok_bot.tool_call.id é a invocação e cursor.grok_bot.initiated_by é sempre subagent.

cursor.grok_bot.tool_result

INFO (success / cancelled), WARN (denied), ERROR (error), body grok_bot_tool_result. Família grok_bot_agent_actions. Uma chamada de ferramenta integrada já concluída, feita por um Bot (read, web_search, send_to_user, task, shell, ...). Toda ferramenta integrada produz esta linha, então nenhuma ferramenta que um Bot pode chamar fica sem registro. Chamadas de conector (MCP) geram linhas mcp_tool_call e nunca aparecem aqui.

cursor.grok_bot.tool_call.id associa a linha às linhas tool_decision da mesma chamada. Um mesmo id pode ter duas linhas tool_result quando uma chamada é executada novamente após uma falha transitória no stream do modelo, então conte ids distintos ao contabilizar chamadas.

Interprete outcome como "como a chamada retornou", e não como "se a ação ocorreu". Shells, ações de navegador e de computador e solicitações de ferramentas locais recusadas pela pessoa relatam a recusa como denied, com error_category user_rejected. E-mail, gravações de rotina, transferências de arquivos por conector, inicializações de subagentes e ações de agente em nuvem repassam a recusa ao modelo como texto; por isso, o tool_result delas indica success, enquanto a linha tool_decision registra a recusa.

cursor.grok_bot.tool_decision

INFO (allowed / held), WARN (denied / timed_out), corpo grok_bot_tool_decision. Família grok_bot_agent_actions. Uma decisão sobre se uma chamada de ferramenta de um Bot pode ser executada: quem a tomou, por qual modo de aprovação e qual foi. Uma chamada pode ter várias decisões (o Auto-review se recusa a permitir automaticamente e, em seguida, uma pessoa responde ao card), cada uma com seu próprio registro. Elas se vinculam à linha tool_result, mcp_tool_call ou computer_use_session da chamada por meio de cursor.grok_bot.tool_call.id. A justificativa do classificador, o texto do card e os argumentos nunca aparecem aqui.

O que cada origem significa:

• policy é toda classificação aplicada pelo Auto-review, allowed ou denied, em qualquer surface: os shells, chamadas de conector, e-mail, gravações de rotina e inicializações de agente em nuvem e de subagente. Um classificador que falha ou perde o prazo gera um policy denied, assim como uma regra de revisão que encaminha uma chamada a uma pessoa sem classificá-la.
• human é o desfecho de um card do Auto-review (approval_mode auto_review quando o classificador escalou, ask_human quando a surface sempre pergunta, como feedback do produto, reivindicação de uma caixa de entrada de e-mail, realização de uma ligação telefônica ou importação de cookies do Chrome), ou uma solicitação de permissão de ferramenta local respondida no próprio computador da pessoa (local_tool_permission). Respostas "Sempre" e "Nunca" são registradas como allowed e denied, assim como uma resposta pontual.
• hook é a recusa de um hook pré-ferramenta.
• automatic é uma chamada sobre a qual nenhuma barreira se pronunciou; assim, toda outra chamada nativa concluída tem pelo menos uma decisão. Três tipos de chamada não têm nenhuma: uma chamada que a própria ferramenta recusou antes de qualquer barreira ser executada (seu tool_result indica denied); um card que a pessoa responde depois que o turno terminou (uma solicitação de preenchimento de credencial, de secret ou de cartão virtual), porque a resposta chega em um turno posterior; e uma chamada cancelada antes que qualquer barreira se pronunciasse, já que uma chamada cancelled traz apenas as permissões e retenções registradas antes de ser interrompida. Uma solicitação de cartão virtual também encerra o turno de dentro da própria chamada, por isso seu tool_result indica cancelled.

Uma chamada recusada pelo Auto-review e depois respondida por uma pessoa tem as duas linhas, policy denied e depois human, na ordem de event.sequence. Não há atributo de aprovador: os cards de um Bot são respondidos apenas pelo seu proprietário, que é o cursor.user.id do registro.

cursor.grok_bot.file_transfer

INFO (success), WARN (denied), ERROR (error), corpo grok_bot_file_transfer. Família grok_bot_agent_actions. Uma transferência de arquivo que um Bot tentou fazer entre o computador dele e outro endpoint: a máquina do usuário, uma conta conectada do Google Drive, OneDrive ou Gmail, ou a leitura de um arquivo na máquina do usuário diretamente para o contexto do Bot. Apenas metadados: a direção, a outra ponta, quantos bytes foram transferidos e o resultado. O caminho, o nome do arquivo e o conteúdo nunca são exportados. A leitura de um arquivo no próprio computador do Bot gera uma linha tool_result, não este evento. cursor.grok_bot.tool_call.id associa a linha ao tool_result da chamada e, no caso de uma transferência recusada, ao respectivo tool_decision.

cursor.grok_bot.message_delivery

INFO (sent / held), ERROR (failed), corpo grok_bot_message_delivery. Família grok_bot_agent_actions. Uma mensagem de saída de um Bot: para o usuário dele no chat do Cherri Bot, para outro Bot do usuário, para uma conversa do Slack ou Discord pela qual o Bot foi acionado, para destinatários de email externos, para o app Mensagens do Mac do usuário ou para um cartão de rascunho que o próprio usuário envia ou descarta. A linha indica para onde a mensagem foi e se ela chegou, nunca o que ela dizia nem o nome do destinatário: sem corpo, assunto, destinatário, nome de anexo ou tamanho. cursor.grok_bot.tool_call.id associa a linha ao tool_result da mesma chamada de envio.

cursor.grok_bot.routine_run

INFO (success / cancelled), ERROR (error), corpo grok_bot_routine_run. Família grok_bot_agent_actions. Uma execução de rotina concluída por um Bot: qual rotina foi disparada, por quê, como terminou e quanto tempo levou. O Cherri Code registra a linha ao encerrar a execução (proveniência server), então a execução é registrada mesmo que o computador do Bot não esteja observando, e a linha não contém box.id, event.sequence nem tool_call.id. Ela sempre contém cursor.grok_bot.initiated_by=routine e cursor.entrypoint=automation. Nunca inclui o prompt da rotina, o nome dela nem o texto do turno.

cursor.grok_bot.turn.id é o turno em que a execução ocorreu, então as linhas tool_result, shell_command e mcp_tool_call da própria execução fazem join por ele. Uma execução que ocorreu como subagente de rotina, ou que falhou antes de um turno ser planejado, não contém turn.id.

Não são registradas uma execução que pausa aguardando aprovação e é concluída pelo turno retomado, nem uma execução que falhou antes de qualquer turno começar. O Action Recording é uma funcionalidade de equipe, então execuções de um proprietário pessoal (sem equipe) são ignoradas, assim como qualquer outra ação do Bot.

cursor.grok_bot.guardrail

INFO (continued), WARN (warned / stopped), corpo grok_bot_guardrail. Família grok_bot_agent_actions. Um guardrail intervindo em um turno do Bot: o detector de loop disparando por saída ou chamadas de ferramenta repetidas, a defesa contra bots de um site recusando o navegador do Bot, ou o Auto-review interrompendo uma chamada de ferramenta para consultar uma pessoa, junto com a espera que se seguiu. Somente campos codificados; a justificativa do classifier e o texto do card nunca são exportados. A decisão em si (a recusa do Auto-review, a resposta da pessoa) é uma linha tool_decision e nunca é repetida aqui; uma linha de escalonamento se associa a ela por cursor.grok_bot.decision.id.

As linhas usam WARN quando o guardrail alterou o turno (um alerta, uma parada, uma espera que terminou em recusa ou sem resposta) e INFO quando ele apenas observou ou o turno seguiu adiante. Uma linha por disparo: um bloqueio conta uma vez por episódio, então uma página que continua no mesmo bloqueio mesmo após recarregamentos gera uma única linha.

Um escalonamento gera duas linhas para um mesmo card, na ordem em que ocorreram. A linha tool_escalation é a solicitação: um card foi exibido porque uma chamada em revisão não podia ser executada sem uma pessoa. A linha pause é o fim da espera: a pessoa permitiu (resumed) ou recusou (denied) a ação, ou ninguém respondeu antes de o card expirar ou ser retirado (abandoned). Quando a espera terminou porque uma pessoa parou ou redirecionou o turno em vez de responder, a segunda linha é interrupted. Ambas as linhas incluem o cursor.tool.name da ferramenta escalonada, o cursor.grok_bot.tool_call.id da chamada e o id do card como cursor.grok_bot.decision.id — o mesmo valor presente na linha tool_decision human dessa chamada —, de modo que a solicitação, a espera e a resposta se associam por uma única chave.

cursor.grok_bot.tool_call.id está presente nos tipos de escalonamento e ausente nas detecções, que não são atribuídas a uma única chamada de ferramenta. Uma chamada recusada pelo Auto-review sem ninguém a quem consultar não abre cartão e contém apenas o seu tool_decision.

cursor.grok_bot.delegation

INFO (dispatched, completed com success ou stopped), ERROR (completed com error), corpo grok_bot_delegation. Família grok_bot_agent_actions. Trabalho que um Bot repassou a outro agente e o resultado que voltou: um subagente em segundo plano que ele despachou ou um agente em nuvem do Cherri Code que ele iniciou ou ao qual respondeu. Apenas IDs e resultado; nunca o prompt, o texto do resultado ou as ações do próprio delegado. As chamadas de ferramenta de um subagente geram suas próprias linhas grok_bot.* com initiated_by=subagent; a execução de um agente em nuvem fica na família cloud_agents.

Cada delegação gera dois registros com o mesmo target_id: dispatched, quando o trabalho é repassado, e completed, quando o resultado volta ao Bot. Registros completed usam como turn.id o turno que recebeu o resultado, e não o turno que fez o despacho. cursor.grok_bot.tool_call.id é a chamada que fez o despacho (ou a chamada de parada, em um registro subagent_stop); ele aparece no registro dispatched e no registro completed de um subagente, mas fica ausente na conclusão de um agente em nuvem.

Limitações conhecidas:

• Não são registrados: uma orientação injetada no turno em andamento de um agente em nuvem (sem nova execução), um início ou resposta rejeitado pelo Cherri Code, o cancelamento de um agente em nuvem, uma execução iniciada por outra pessoa que o Bot apenas acompanha e o subagente de uma rotina despertando seu agente pai.
• Um subagente parado ainda pode entregar depois uma conclusão error, então um mesmo target_id pode ter tanto um registro stopped quanto um error.
• O registro completed de um agente em nuvem é de melhor esforço: quando o Bot volta a acompanhar um agente que iniciou em um turno anterior, a conclusão pode vir com kind cloud_agent_launch, e um início que volta a ser acompanhado no meio da execução pode ficar com o dispatched sem o completed correspondente. Associe os dois registros pelo target_id e trate a possível ausência da conclusão.
• A entrega é do tipo pelo menos uma vez (at-least-once), como em todas as linhas grok_bot.*: um início, resposta ou conclusão reenviado após uma falha pode ser registrado duas vezes para o mesmo target_id. Deduplique primeiro por cursor.event.id.

Conteúdo da conversa

Família conversation_content. Os eventos conversation.* são os únicos registros de log cujo corpo é um payload (texto da mensagem ou um dos lados de uma chamada de ferramenta MCP), e não um nome de evento constante. Roteie pelo nome do evento de log, como em todas as outras famílias. cursor.conversation.user_message é um prompt, cursor.conversation.assistant_message é uma resposta e cursor.conversation.tool_io são os argumentos ou o resultado de uma chamada de ferramenta MCP; não analise o corpo para diferenciá-los.

Corpo. Texto com secrets removidos. As mensagens são limitadas a 32 KiB, e cada lado de uma chamada de ferramenta, a 8 KiB. cursor.conversation.content_truncated é definido sempre que o corpo exportado é um prefixo do texto ocultado, seja porque a origem ultrapassou o limite, seja porque a ocultação a fez ultrapassá-lo, e, em tool_io, também quando a remoção de secrets tornou impossível analisar um corpo que estava dentro do limite.

Identidade. Os registros incluem os atributos comuns de log. cursor.conversation.id os associa aos logs api.request, skill.activated, hook.execution_complete, cloud_agent.* e grok_bot.* da conversa. Os únicos identificadores de usuário são os atributos do recurso opcionais cursor.user.*; os atributos de log não incluem nenhum. Não dependa de cursor.request.id, cursor.usage_event.id ou, nos registros de mensagem, cursor.grok_bot.turn.id; tool_io inclui turn.id como um atributo compartilhado grok_bot.*.

Superfícies. Apenas agentes na nuvem e Cherri Bot. Conversas de Cloud Agent chegam com cursor.surface=cloud_agent no recurso. Conversas do Cherri Bot chegam com cursor.surface=grok_bot, junto com os logs de ação grok_bot.* do Bot quando o Action Recording está ativado. tool_io é exclusivo do Cherri Bot. Conversas do IDE, da CLI e do desktop ainda não fazem parte desta família. Filtre ou roteie por cursor.surface.

Controles. Cada evento só é enviado com a adesão da equipe e o respectivo controle do destino ativados: user_message requer Prompts, assistant_message requer Responses e tool_io requer Tool I/O. A página de configuração explica os controles.

Os três eventos são INFO e incluem estes atributos:

cursor.conversation.user_message

INFO. Corpo: o texto com secrets removidos de um prompt do usuário.

cursor.conversation.assistant_message

INFO. Corpo: o texto final do assistente com secrets removidos para a resposta.

cursor.conversation.tool_io

INFO. Corpo: o JSON compacto, com secrets removidos, de um dos lados de uma chamada de ferramenta MCP, com no máximo 8 KiB. São dois registros por chamada de ferramenta MCP do Cherri Bot executada via transporte http: o registro arguments contém o JSON object enviado pelo Bot, e o registro result contém a resposta do conector. Em caso de sucesso, isso corresponde ao texto e ao conteúdo estruturado da ferramenta; em caso de falha, à mensagem de erro, rejeição ou negação. Os bytes de imagens são substituídos pelo respectivo tipo MIME. Chamadas stdio no Bot's computer informam apenas metadados e não geram registro tool_io. Requer o controle Tool I/O do destino, além da adesão da equipe.

Ambos os registros contêm os atributos de correlação grok_bot.* compartilhados (provenance, turn.id, tool_call.id, event.sequence). Por isso, cursor.grok_bot.tool_call.id está sempre presente e os associa às linhas cursor.grok_bot.mcp_tool_call e cursor.grok_bot.tool_decision da chamada. cursor.tool.name, cursor.tool.status e cursor.mcp.server.name repetem os valores da linha de metadados, para que cada registro possa ser lido de forma independente.

Quando cursor.conversation.content_truncated é true, o corpo não pode ser analisado como JSON: ou ele é um prefixo do texto ocultado, ou a remoção de secrets o tornou impossível de analisar e o Cherri Code o exportou sinalizado, em vez de exportar um corpo com menos secrets removidos. Verifique a flag antes de fazer a análise. Os dois lados passam pelo mesmo removedor de secrets aplicado ao texto das mensagens, além de uma etapa baseada em chaves que oculta o valor de qualquer membro ou atribuição JSON cuja chave indique uma credencial (password, passphrase, token, api_key, secret, secret_key, access_key, authorization, cookie, private_key, credentials e compostos como client_secret ou x-api-key), seja qual for a aparência do valor. Pares de cabeçalho também contam: em [{"name":"Authorization","value":"Basic ..."}], o value irmão de um membro name, key ou header que esteja na lista é ocultado, assim como o segundo item de uma matriz de dois itens cujo primeiro item esteja na lista (["password","..."]). Campos de cartão armazenados como números ("cvc": 123) passam a ser [REDACTED: Card], e escapes ASCII \uXXXX são decodificados antes da remoção de secrets. Um bloco de chave privada dividido entre os itens de uma mesma matriz (linhas de um arquivo, blocos de texto de um resultado) é ocultado da linha BEGIN até a linha END; já um bloco dividido entre campos não relacionados não é. A etapa baseada em chaves alcança um nível de JSON aninhado dentro de um valor string; em documentos recodificados em níveis mais profundos, os secrets são removidos apenas com base no formato do valor. Consulte MCP tool I/O para saber o que o removedor de secrets não detecta.

Identidade e associações

Os logs exportados não incluem os campos trace_id nem span_id do OpenTelemetry. Use cursor.conversation.id e cursor.grok_bot.turn.id para correlacionar Bot e turno. As métricas não incluem ids de correlação; use os logs api.request para obter os totais de tokens por conversa.

Veja Associação de sessões na página de configuração para exemplos práticos.

Semântica de entrega

• Logs são entregues pelo menos uma vez. Falhas transitórias são resolvidas automaticamente por cerca de 7 dias; elimine duplicatas com base em event.id. Rejeições definitivas (4xx persistente, payloads inválidos) não são reenviadas.
• Métricas são entregues no máximo uma vez. Solicitações de métricas com falha não são repetidas nem reenviadas.

• Sem garantia de ordenação. As correções podem chegar após as solicitações que corrigem; ordene pelo timestamp do registro.

• Sucesso parcial do OTLP é respeitado. Itens rejeitados não são reenviados.
• Não há preenchimento retroativo de dados anteriores à ativação do destino. A retenção na fonte antes da exportação também é de cerca de 7 dias (separada da janela de novas tentativas de entrega).