Exportação do OpenTelemetry

A Exportação do OpenTelemetry envia dados de uso do Cherri Code da sua equipe para um coletor operado por você. O Cherri Code envia métricas (tokens, chamadas de ferramenta, custos de melhor esforço) e logs (solicitações de API, erros, correções, skills, hooks, plugins, eventos do ciclo de vida de agentes em nuvem e ações registradas do Grok Bot) para um único destino gerenciado pela equipe. As equipes também podem optar por incluir o conteúdo da conversa: os prompts dos usuários e as respostas do assistente dos agentes na nuvem e do Grok Bot, além dos argumentos e resultados das chamadas de ferramentas MCP do Grok Bot. A exportação é executada no servidor.

A Exportação do OpenTelemetry está disponível no plano corporativo. Os Admins configuram o recurso em Configurações da equipe > Exportação do OpenTelemetry.

A Referência do protocolo de exportação do OpenTelemetry documenta cada métrica, evento de log e atributo.

Pré-requisitos

• Um endpoint HTTPS que aceite protobuf OTLP/HTTP em /v1/metrics e /v1/logs. A ingestão OTLP do agente Datadog, o Coletor do OpenTelemetry e o ClickHouse/ClickStack são compatíveis.
• Um token Bearer ou chave de API que o Cherri Code possa enviar no cabeçalho de uma solicitação.
• O endpoint deve ser acessível pela internet pública. O Cherri Code usa um conjunto fixo de IPs de origem para tráfego de saída.

IPs de origem

O Cherri Code envia OTLP pelo proxy de saída no servidor. O tráfego é originado destes endereços (todos /32):

Esses IPs não são rotacionados sem aviso prévio. Use TLS e autenticação como controles principais. Adicione uma lista de permissão de IPs caso sua rede exija.

Receitas para coletor

O Cherri Code envia dados ao seu coletor via protobuf binário OTLP/HTTP. gRPC e JSON não são compatíveis. Insira a URL HTTPS base em Configurações da equipe, sem o sufixo /v1; o Cherri Code adiciona /v1/metrics e /v1/logs.

Coletor do OpenTelemetry mínimo

receivers:  otlp:    protocols:      http:        endpoint: 0.0.0.0:4318processors:  batch:exporters:  # Substitua pelo seu destino (datadog, clickhouse, logging, etc.)  logging:    verbosity: basicservice:  pipelines:    metrics:      receivers: [otlp]      processors: [batch]      exporters: [logging]    logs:      receivers: [otlp]      processors: [batch]      exporters: [logging]

Encerre o TLS na frente do coletor com um balanceador de carga, ingress ou as configurações de TLS do otelcol. Insira https://otel.example.com no Cherri Code, não https://otel.example.com:4318/v1. Para autenticação, encerre-a no balanceador de carga ou configure um cabeçalho estático para o Cherri Code enviar, como Authorization: Bearer <token>.

Agente Datadog (ingestão via OTLP)

Habilite a ingestão HTTP via OTLP e os logs no agente e exponha o agente (ou um gateway na frente dele) via HTTPS:

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

Os equivalentes com variáveis de ambiente são DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT=0.0.0.0:4318, DD_LOGS_ENABLED=true e DD_OTLP_CONFIG_LOGS_ENABLED=true. Exponha a porta 4318 ou termine o TLS na porta 443 e use um proxy para a 4318.

No Cherri Code, a URL base é o endpoint público https:// na frente desse listener. Adicione os cabeçalhos DD-API-KEY ou de site somente se o gateway os exigir; o agente já tem a api_key configurada localmente.

Consulte a ingestão de OTLP no Datadog Agent para detalhes da configuração do agente.

Databricks e destinos do tipo data warehouse

Para destinos de data warehouse, como Databricks ou ClickHouse, execute um coletor com um receptor HTTP OTLP e o exportador do fornecedor ou encaminhe os dados por HTTP ao seu pipeline de ingestão. A configuração do Cherri Code é a mesma: uma URL base HTTPS que disponibiliza protobuf em /v1/metrics e /v1/logs. Consuma as métricas como somas de deltas e elimine logs duplicados com base em cursor.event.id.

Ativar

Em Configurações da equipe > Exportação do OpenTelemetry:

1. Criar destino com a URL base (sem /v1/...; o Cherri Code adiciona os caminhos) e os cabeçalhos de autenticação
2. Testar conexão para verificar a URL e a autenticação
3. Ativar. A exportação começa em cerca de um minuto.

Cada sinal e família de telemetria tem seu próprio controle. Novas famílias são ativadas por padrão, a menos que você desative auto_enable_new_families. O conteúdo da conversa é a exceção: permanece desativado até que você o ative.

Conteúdo da conversa

A família conversation_content transmite o texto dos prompts do usuário e das respostas do assistente para o seu coletor como logs cursor.conversation.user_message e cursor.conversation.assistant_message. Ela também transmite os argumentos e resultados das chamadas de ferramenta MCP do Grok Bot como logs cursor.conversation.tool_io. No momento, ela abrange apenas agentes na nuvem e Grok Bot. Conversas da IDE, da CLI e do desktop ainda não são cobertas por esta família. É a única família que transporta texto de mensagens ou payloads de ferramentas. A Referência do protocolo de exportação do OpenTelemetry documenta a estrutura dos registros.

O que é enviado depois que a adesão da equipe e Conversation content estiverem ativados:

• Dois eventos de log. cursor.conversation.user_message transporta um prompt do usuário e cursor.conversation.assistant_message transporta a resposta final do assistente. O nome do evento identifica o papel. O corpo é o texto da mensagem.
• Com secrets removidos e limitado. O Cherri Code higieniza o texto das mensagens antes da exportação e limita o corpo de cada mensagem a 32 KiB. cursor.conversation.content_truncated é true quando o corpo exportado é um prefixo do texto ocultado.
• A E/S de ferramentas é separada. Com o controle correspondente ativado, cursor.conversation.tool_io adiciona os argumentos e resultados das chamadas MCP do Grok Bot, limitados a 8 KiB por lado. Consulte E/S de ferramentas MCP.
• Mesma identidade dos demais logs. Os registros carregam os mesmos ids de todos os outros logs, incluindo os atributos do recurso opcionais cursor.user.*.
• Apenas agentes na nuvem e Grok Bot. Conversas de agente na nuvem chegam como cursor.surface=cloud_agent e conversas do Grok Bot, como cursor.surface=grok_bot. Conversas da IDE, da CLI e do desktop ainda não são exportadas por esta família. As mensagens do Grok Bot são separadas da família grok_bot_agent_actions, que exige Action Recording e transporta ações em vez de mensagens.

E/S de ferramentas MCP

O log cursor.grok_bot.mcp_tool_call comprova que um Bot fez uma chamada MCP: qual servidor, qual ferramenta, se ela teve sucesso e quanto tempo levou. Ele nunca inclui o que o Bot enviou nem o que foi retornado, então um revisor consegue ver que houve uma transição no Jira, mas não qual issue passou para qual estado. Esse conteúdo fica em cursor.conversation.tool_io, controlado pelo controle Tool I/O no destino.

Antes de você ativá-la, uma chamada do Bot ao Jira aparece no seu coletor como uma linha cursor.grok_bot.mcp_tool_call cujo cursor.tool.name identifica a ferramenta de transição e cujo cursor.tool.status é success. Depois de ativá-la, a mesma chamada também gera duas linhas cursor.conversation.tool_io. A linha direction=arguments contém o JSON que o Bot enviou, como a chave da issue e o status de destino. A linha direction=result contém o que o Jira retornou. Relacione as três linhas por cursor.grok_bot.tool_call.id.

Escopo e limites:

• Trechos, não payloads completos. Cada lado é limitado a 8 KiB. Um corpo cortado é um prefixo do texto ocultado, sinalizado com cursor.conversation.content_truncated, e não pode ser interpretado como JSON. O início de uma chamada de escrita (chave do objeto, destino, novo valor) cabe no limite; resultados longos de leitura são cortados.
• Conteúdo do resultado. Em caso de sucesso, o registro de resultado contém o texto e o conteúdo estruturado da ferramenta. Em caso de falha, contém a mensagem de erro, rejeição ou negação. O Cherri Code substitui os bytes de imagens pelo tipo MIME correspondente.
• Segredos ocultados, em regime de melhor esforço. O Cherri Code aplica o mesmo filtro baseado em padrões usado em comandos de shell e texto de mensagens: formatos conhecidos de credenciais, blocos PEM e endereços de email são substituídos por marcadores [REDACTED: ...], então um endereço em assignee é exportado como [REDACTED: Email]. Ele também oculta o valor de qualquer membro JSON cuja chave indique uma credencial (password, token, api_key e semelhantes; a lista completa está na Referência do protocolo de exportação do OpenTelemetry), seja qual for a aparência do valor. A correspondência de padrões não consegue reconhecer todos os segredos nem todos os dados pessoais. Uma credencial sob uma chave fora da lista, dividida entre campos ou em uma linha de cabeçalho com um nome de membro incomum ({"k":"Authorization","v":"Basic ..."}) é exportada sem alterações, assim como um argumento que cita a mensagem de um colega ou um resultado que contém o corpo da resposta de um conector. Sua equipe assume esse risco residual, assim como acontece com prompts e respostas.
• Somente chamadas a conectores hospedados. Chamadas MCP do Grok Bot executadas pelo Cherri Code (Jira, Slack, Linear e outros servidores hospedados; suas linhas mcp_tool_call mostram cursor.grok_bot.mcp.transport=http) geram E/S de ferramentas. Servidores stdio no computador do Bot, ferramentas nativas e chamadas de ferramenta do Cloud Agent, da IDE e da CLI ainda não reportam payloads.

O que o Cherri Code exporta

Escopo: cursor.telemetry 0.1.0.

Tudo abaixo vem ativado por padrão para um novo destino, exceto conversation_content. Desative famílias individuais nas Configurações da equipe.

Métricas (temporalidade delta)

• cursor.token.usage: por cursor.token.type (input / output / cache_read / cache_creation)
• cursor.tool.calls: ferramentas nativas e MCP (cursor.tool.kind)
• cursor.cost.usage: estimativa em USD de melhor esforço; não é uma fatura

Logs

• cursor.api.request: resumo da chamada ao modelo
• cursor.api.error: evento de erro (sem mensagens brutas)
• cursor.api.correction: finalização do faturamento; vincule por 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: um servidor MCP rejeitou as credenciais da execução
• cursor.grok_bot.tool_result: cada chamada de ferramenta nativa feita por um Bot, com o resultado e a duração
• cursor.grok_bot.tool_decision: quem permitiu ou recusou uma chamada de ferramenta de um Bot (uma pessoa, o Auto-review, um hook ou nenhuma verificação)
• cursor.grok_bot.mcp_tool_call: uma chamada de ferramenta de conector (MCP) de um Bot
• cursor.grok_bot.shell_command: um comando de shell de um Bot, com secrets removidos, código de saída e duração
• cursor.grok_bot.browser_navigation: uma página acessada pelo navegador do Bot
• cursor.grok_bot.computer_use_session: um resumo de sessão de uso de computador de um Bot
• cursor.grok_bot.file_transfer: um arquivo transferido entre o computador do Bot e a máquina de um usuário ou uma conta na nuvem
• cursor.grok_bot.message_delivery: uma mensagem enviada por um Bot, para onde foi e se foi entregue
• cursor.grok_bot.routine_run: uma execução de rotina concluída
• cursor.grok_bot.guardrail: um loop detectado, um site bloqueando o Bot ou um pedido de aprovação e o tempo de espera
• cursor.grok_bot.delegation: trabalho que um Bot repassou a um subagente ou agente na nuvem, e o resultado retornado
• cursor.conversation.user_message: um prompt do usuário, com secrets removidos; requer adesão
• cursor.conversation.assistant_message: uma resposta do assistente, com secrets removidos; requer adesão
• cursor.conversation.tool_io: um dos lados (argumentos ou resultado) de uma chamada de ferramenta MCP do Grok Bot, com secrets removidos; requer adesão

Os eventos cursor.grok_bot.*, e cursor.skill.activated quando um Bot lê uma skill, carregam dados de Action Recording. Eles só são enviados depois que um admin da equipe ativa o Action Recording na página Grok Bot do dashboard; trata-se de uma configuração da equipe, desativada por padrão, e o Privacy Mode (Legacy) força sua desativação.

Os eventos registrados são metadados sobre o que o Bot fez, nunca o conteúdo com que ele trabalhou. Argumentos e resultados de ferramentas, caminhos e nomes de arquivos, corpos e destinatários de mensagens, credenciais e dados de cartão nunca são exportados nesses eventos; argumentos e resultados de MCP são enviados apenas no registro cursor.conversation.tool_io, que requer adesão. O texto dos comandos de shell é exportado após a remoção de secrets e limitado a 8 KiB; as URLs do navegador têm as query strings, os fragmentos e as credenciais retirados; e, quando uma ferramenta atua em um site, apenas o hostname é informado. A Referência do protocolo de exportação do OpenTelemetry lista todos os atributos de cada evento.

Os eventos cursor.conversation.* carregam o texto das mensagens ou payloads de ferramentas e só são enviados depois que a equipe faz a adesão e o destino ativa o controle correspondente a esse tipo. Veja Conteúdo da conversa e E/S de ferramentas MCP.

Famílias (controles de admin; todas ativadas por padrão, exceto conversation_content)

• model_usage: métricas de token e custo; api.request / api.error / api.correction
• tool_calls: métrica tool.calls
• skills_hooks_plugins: logs de skill / hook / plugin, incluindo ativações de skills por um Bot
• cloud_agents: logs de cloud_agent.*
• grok_bot_agent_actions: logs de ações grok_bot.*; requer Action Recording (corporativo)
• conversation_content: logs de mensagens e de E/S de ferramentas conversation.*; desativada por padrão

Atributos úteis

• Recurso: service.name=cursor, cursor.team.id, superfície/ponto de entrada e os atributos opcionais cursor.user.id, cursor.user.account_id e cursor.user.email; veja Associação de sessões para atribuir registros a uma pessoa. O tráfego do Grok Bot é exportado como cursor.surface=grok_bot em todas as famílias; desktop não o inclui mais. Um turno iniciado por uma rotina é exportado como cursor.entrypoint=automation.
• Logs: cursor.event.id (para deduplicar), e cursor.request.id / cursor.conversation.id / cursor.usage_event.id, quando presentes
• Logs do Grok Bot: cursor.grok_bot.turn.id, cursor.grok_bot.event.sequence, cursor.grok_bot.tool_call.id e cursor.grok_bot.decision.id; veja Associação de sessões

Entrega

• As métricas são entregues no máximo uma vez. As somas delta podem apresentar breves lacunas após uma falha.
• Os logs são entregues pelo menos uma vez. Deduplicate por cursor.event.id para visualizações de exatamente uma vez.
• Não há backfill de dados anteriores à criação do destino.
• Editar o endpoint ou as credenciais mantém o destino. Desativá-lo ou excluí-lo descarta os dados em trânsito.

Autenticação

O Cherri Code armazena os cabeçalhos de forma criptografada. Para rotacionar as credenciais, edite o destino e salve. As alterações entram em vigor em cerca de 30 segundos.

Limitações

• Custo não é faturamento. cursor.cost.usage é uma estimativa de melhor esforço. Uma série abrange tanto o consumo da cota incluída quanto o uso sob demanda. Para BYOK, ela reflete apenas a Taxa de Tokens do Cherri Code, não os gastos do provedor. Use as APIs de Admin e faturamento para consultar faturas.
• Desabilitar ou excluir um destino descarta dados em trânsito. Rotacione as credenciais editando o destino em vez de excluí-lo e adicioná-lo novamente.
• Os logs podem chegar mais de uma vez. A entrega é de pelo menos uma vez. Deduplicar com base em cursor.event.id.
• Sem conteúdo de prompt ou payloads de ferramentas, a menos que você faça a adesão. O texto das mensagens e os argumentos e resultados de ferramentas MCP são enviados somente pela família conversation_content, que requer adesão. Todos os demais eventos de log carregam ids, contagens e atributos de baixa cardinalidade. Consulte Conteúdo da conversa e E/S de ferramentas MCP.
• Sem contexto de trace ou preenchimento retroativo histórico. Os logs exportados não carregam os campos trace_id ou span_id do OpenTelemetry, e o Cherri Code não envia traces. A exportação começa quando você habilita o destino.
• Os pontos de dados de métricas não têm IDs de correlação. Use atributos de log para associar dados por conversa. Consulte Associação de sessões.
• As métricas são apenas deltas. Some os deltas por série. Um processador estrito de delta para cumulativo pode descartar pontos com horário de término invertido.

Associação de sessões

As métricas (cursor.token.usage, cursor.tool.calls, cursor.cost.usage) são agregadas. Os pontos de dados não incluem conversation.id, request.id nem usage_event.id. Isso mantém a cardinalidade das métricas limitada. Para análises no escopo de sessões ou solicitações, use os logs.

O que cada ID significa

• cursor.conversation.id é a chave da sessão. No IDE e na CLI, é o UUID do chat do composer. Para agentes na nuvem, é o ID de agente bc-... visível ao cliente. Para o Grok Bot (grok_bot.* e qualquer log com cursor.surface=grok_bot), é o identificador do Bot, e esse valor é o ID da conversa do Bot. Quando presentes, os logs api.request, api.error, skill.activated, hook.execution_complete, cloud_agent.*, grok_bot.* e (quando a equipe opta por ativar) conversation.* dessa execução exibem o mesmo valor.
• cursor.usage_event.id é a chave no nível da solicitação em api.request, api.error e api.correction. Use-o para reconciliar com as exportações de uso e faturamento do Cherri Code e aplicar correções.
• cursor.request.id é um ID opcional por chamada na maioria dos logs. Ele nunca aparece em api.correction, cloud_agent.* nem grok_bot.*.
• cursor.event.id é apenas uma chave de deduplicação, não uma chave de associação entre tipos de evento.

Atribua registros a uma pessoa

cursor.user.account_id é o ID do membro na API de administração. Associe-o ao id na resposta de GET /teams/members para identificar a pessoa por trás de um registro. cursor.user.email identifica o membro diretamente. Ambos são opcionais e aparecem apenas junto com cursor.user.id, portanto não exija sua presença em todos os registros. A tabela de atributos do recurso contém as regras de presença.

Agrupe a atividade do Grok Bot

Quatro atributos conectam os registros de um Bot. cursor.grok_bot.turn.id identifica o turno: ele aparece em todos os logs de Action Recording do turno e, para cursor.surface=grok_bot, também nos logs api.request e api.error do turno, de modo que as chamadas ao modelo são associadas às ações por turno. Dentro de um turno, cursor.grok_bot.event.sequence ordena as ações sem depender dos relógios dos clientes; ordene por ele, não pelo timestamp, e não espere que a sequência seja contínua. cursor.grok_bot.tool_call.id agrupa as linhas de uma chamada de ferramenta, e cursor.grok_bot.decision.id associa um pedido de aprovação, a espera por ele e a resposta da pessoa.

As ações de subagentes carregam seu próprio cursor.grok_bot.turn.id e cursor.grok_bot.subagent.id, além de cursor.grok_bot.root_turn.id, o turno voltado ao usuário que elas atendem. Agrupe por root_turn.id para consolidar as ações de um subagente no turno que o criou.

Por exemplo, um turno em que o Bot executou um comando que o Auto-review escalou para o usuário pode produzir estes registros:

Todas as linhas compartilham o cursor.conversation.id do Bot. Agrupe por turn-1 para reconstruir o turno, incluindo as chamadas ao modelo. Agrupe por call-7 para acompanhar a única chamada de shell: o Auto-review a recusou, um card consultou o usuário, o usuário a permitiu, e a ferramenta foi executada e retornou success. card-2 vincula a pergunta e a espera à resposta. O texto do comando em si fica na linha cursor.grok_bot.shell_command do turno, que não contém tool_call.id. Esses campos são atributos de log personalizados, não ids de trace ou span do OpenTelemetry.

Com o conteúdo da conversa ativado, os logs cursor.conversation.user_message e cursor.conversation.assistant_message do Bot contêm o mesmo cursor.conversation.id. Associe por esse campo para colocar o prompt e a resposta ao lado das solicitações ao modelo e das ações registradas do Bot. Os logs de mensagem têm seu próprio cursor.conversation.turn.id opcional. Não conte com cursor.grok_bot.turn.id ou cursor.request.id neles.

Com a E/S de ferramentas MCP ativada, uma chamada MCP adiciona dois logs cursor.conversation.tool_io (direction=arguments e direction=result) que contêm o cursor.grok_bot.tool_call.id da chamada e, quando presentes, o turn.id e o event.sequence. Agrupe por tool_call.id para colocar os argumentos e o resultado ao lado das linhas mcp_tool_call e tool_decision da chamada.

Receita: classificar sessões por tokens e depois anexar skills e ferramentas

1. Pegue as linhas de log cursor.api.request. Some cursor.api.request.input_tokens e output_tokens (e os campos de cache, se precisar), agrupando por cursor.conversation.id. Isso fornece totais de tokens por sessão, algo que as métricas não oferecem.
2. Classifique as conversas por essa soma ou pelo custo estimado.
3. Faça um left join de outros logs pelo mesmo cursor.conversation.id:
   • cursor.skill.activated mostra quais skills foram executadas
   • cursor.hook.execution_complete mostra os hooks
   • cursor.cloud_agent.* mostra configuração, pull requests, artefatos e falhas de autenticação do MCP (somente agentes na nuvem)
   • cursor.grok_bot.* mostra o que um Bot fez (somente Grok Bot, com Action Recording ativado)
   • cursor.conversation.user_message e cursor.conversation.assistant_message mostram os prompts e as respostas (agentes na nuvem e Grok Bot, somente com a adesão conversation_content)
   • cursor.conversation.tool_io mostra o que cada chamada MCP do Grok Bot enviou e recebeu (Grok Bot, somente com a adesão de E/S de ferramentas)
4. cursor.tool.calls existe apenas como métrica, portanto não tem id de conversa. Use a métrica para reportar as taxas de ferramentas de toda a organização. Para o Grok Bot, cursor.grok_bot.tool_result e cursor.grok_bot.mcp_tool_call fornecem a atribuição de ferramentas por Bot e por turno; para outras Surfaces, esses dados ainda não são transmitidos.

cursor.cost.usage também existe apenas como métrica. Para classificar sessões por custo, faça uma estimativa a partir dos totais de tokens de api.request e das suas próprias tarifas, ou obtenha os gastos pelas APIs de Admin e faturamento e associe por cursor.usage_event.id quando disponível.

Receita: aplicar uma correção de faturamento

1. Encontre os logs cursor.api.correction.
2. Associe por cursor.usage_event.id aos logs api.request e api.error que compartilham esse id.
3. Trate todo o grupo como não faturado.

Ressalvas

• Subagentes recebem seu próprio id de conversa. Para ações do Grok Bot, consolide-as com cursor.grok_bot.root_turn.id; para outras Surfaces, a consolidação pelo pai ainda não é exportada.
• Deduplique as linhas de log por cursor.event.id antes de associar, se precisar de visualizações com contagem única.
• Registros de versões mais antigas do Grok Bot omitem cursor.grok_bot.event.sequence e cursor.grok_bot.initiated_by. Trate ambos como opcionais.

Política de alterações

Novas métricas e eventos podem aparecer à medida que a cobertura é expandida. auto_enable_new_families controla se eles são ativados automaticamente. Renomeações e remoções são comunicadas explicitamente. A Referência do protocolo de exportação do OpenTelemetry documenta toda a superfície de atributos.