Simple Log Service:Coleta de logs de observabilidade de AI Agents (AgentSight)

Pré-requisitos

• A versão do kernel do sistema operacional do servidor é Linux 5,10 ou posterior.

  O plug-in depende do eBPF para observação no nível do sistema. Kernels anteriores à versão 5,10 não oferecem suporte aos recursos necessários do eBPF e não permitem a coleta.

  Os ambientes compatíveis e validados incluem:

  • Alibaba Cloud Linux 3

  • Ubuntu 22.04

  • Ubuntu 24.04

  Execute o comando a seguir para verificar a versão atual do kernel:

  uname -r

• O LoongCollector v3.3.9 ou posterior está instalado no servidor.

  O recurso de coleta do AgentSight exige uma versão recente do LoongCollector. Atualize para a versão mais recente antes de configurar este plug-in.

• O AI Agent de destino (como OpenClaw ou Hermes) está implantado e em execução no servidor.

• Ambiente de contêiner do ACK: para coletar logs de LLM de Pods de Agent em um cluster do Container Service for Kubernetes (ACK), certifique-se de que os seguintes requisitos são atendidos:

  • O LoongCollector foi atualizado para a versão v3.3.10 ou posterior.

  • A opção enableEBPF está ativada na página Component Management do console do ACK.

  Após atender a esses requisitos, crie uma configuração de coleta do Logtail para o AgentSight no Simple Log Service para coletar os logs de LLM do Agent. A configuração se aplica ao mesmo grupo de máquinas usado pelas outras configurações do LoongCollector.

Funcionamento

A instrumentação tradicional de aplicações não acompanha a iteração rápida e o alto nível de personalização dos AI Agents, nem consegue rastrear cadeias de chamadas de ferramentas para identificar o comportamento real do Agent. O plug-in input_agentsight conecta sondas SSL/TLS e observadores de processos no nível do kernel por meio do eBPF, capturando solicitações e respostas criptografadas por TLS entre os processos do Agent e os serviços de LLM. Essa abordagem garante observabilidade de ponta a ponta sem exigir alterações no código do Agent.

Recursos

• Coleta dados completos de interação entre AI Agents e LLMs: mensagens de solicitação, mensagens de resposta, nome do modelo, consumo de tokens, latência, códigos de status, entre outros.

• Identifica processos que acessam APIs de LLM com base em uma lista de permissões de domínios, que já inclui os domínios de API de LLM mais comuns.

Procedimento

1. Faça login no console do Simple Log Service.

2. Na seção Data Import, selecione a entrada de configuração de coleta do LoongCollector e, em seguida, escolha o Project e o Logstore de destino.

3. Na página Machine Group Configuration, configure e aplique o grupo de máquinas de destino.

   Importante

   Se você aplicar o grupo de máquinas imediatamente após a criação, o status de heartbeat poderá aparecer como FAIL, pois a conexão ainda não foi estabelecida. Clique em Automatic Retry para resolver o problema.

4. Na guia Data Source Settings, especifique um Configuration Name e insira a configuração do plug-in. O tipo de plug-in é fixo como input_agentsight.

   Escolha um padrão de configuração de acordo com o seu cenário:

   • Use a configuração mínima quando o seu Agent e o provedor de LLM forem cobertos pelos padrões internos.

   • Use a lista de permissões de domínios personalizada quando o Agent se conectar a um endpoint de LLM fora do padrão.

   • Use a lista de permissões de linha de comando personalizada quando o processo do Agent não corresponder às regras internas.

   • Use o reporte de tráfego HTTP bruto quando precisar inspecionar tráfego que o AgentSight não consegue analisar semanticamente como GenAI.

   Configuração mínima

   Configuração mínima: especifique apenas o tipo de plug-in. Todas as configurações utilizam valores padrão (o sistema injeta automaticamente a lista interna de permissões de linha de comando e a lista de domínios).

   {
       "inputs": [
           {
               "type": "input_agentsight"
           }
       ]
   }

   Lista de permissões de domínios personalizada: especifique os domínios HTTPS personalizados para monitoramento.

   {
       "inputs": [
           {
               "detail": {
                   "ProbeConfig": {
                       "Https": [
                           "api.openai.com",
                           "api.anthropic.com",
                           "dashscope-intl.aliyuncs.com",
                           "dashscope.aliyuncs.com"
                       ]
                   }
               },
               "type": "input_agentsight"
           }
       ]
   }

   Lista de permissões de linha de comando personalizada: filtre os Agents de destino pela linha de comando do processo e marque o tipo correspondente.

   {
       "inputs": [
           {
               "detail": {
                   "ProbeConfig": {
                       "CmdlineWhitelist": [
                           {
                               "AgentType": "openclaw",
                               "Args": ["node*", "*openclaw*"]
                           },
                           {
                               "AgentType": "claude-code",
                               "Args": ["node*", "*claude*"]
                           }
                       ]
                   }
               },
               "type": "input_agentsight"
           }
       ]
   }

   Reporte de protocolos desconhecidos como tráfego HTTP bruto: quando a opção ProbeConfig.RawHttpsFallback está ativada, o tráfego que o AgentSight não consegue converter em semântica GenAI (caminhos de API desconhecidos ou corpos fora do padrão) deixa de ser descartado. Em vez disso, ele é registrado como tráfego HTTP bruto. Crie um índice de campo para os eventos HTTP brutos e utilize o recurso de consulta e análise do Logstore para inspecioná-los.

   {
       "inputs": [
           {
               "detail": {
                   "ProbeConfig": {
                       "RawHttpsFallback": true
                   }
               },
               "type": "input_agentsight"
           }
       ]
   }

   Nota

   Observe o comportamento a seguir:

   • Os logs HTTP brutos gerados por RawHttpsFallback: true são criados apenas quando o AgentSight não consegue resolver o tráfego em semântica GenAI. Eles são mutuamente exclusivos com os logs gen_ai.*: uma única solicitação gera, no máximo, um dos dois tipos.

   • O tráfego HTTP bruto é registrado com os nomes de evento event.name=http.request e event.name=http.response.

   • Este recurso tem suporte apenas no LoongCollector v3.3.10 e posterior.

5. Crie os índices e visualize uma prévia dos dados. Você pode criar índices de campo manualmente com base nos campos coletados ou clicar em Auto Generate Index.

6. Após concluir a configuração, aguarde cerca de 1 minuto para que o índice entre em vigor. Em seguida, visualize os logs coletados na página de consulta e análise do Logstore.

   Você deverá ver entradas de log contendo campos como gen_ai.agent.type, gen_ai.model.request e gen_ai.model.response. A presença desses campos confirma que a coleta está funcionando corretamente.

Parâmetros de configuração

Limites e solução de problemas

• Nenhum dado na página de prévia ou consulta: verifique se a versão do kernel do servidor é 5,10 ou posterior (uname -r) e se o LoongCollector foi atualizado para v3.3.9 ou posterior. Em seguida, confirme se a linha de comando do processo de destino corresponde a uma regra CmdlineWhitelist ou se os domínios acessados estão na lista Https. Execute o comando a seguir no servidor para visualizar a linha de comando real de um processo antes de criar regras glob:

  tr '\0' ' ' < /proc/<PID>/cmdline; echo

  Consulte o Apêndice técnico para limitações de compatibilidade de hook do eBPF que podem impedir a coleta de determinados binários de Agent.

• Para obter mais orientações sobre solução de problemas, consulte Solucionar falhas na coleta de logs do Logtail.

• Este recurso está atualmente em versão canary e disponível nas seguintes regiões: US (Virginia), US (Silicon Valley), Malaysia (Kuala Lumpur), Indonesia (Jakarta), South Korea (Seoul), entre outras.

Apêndice técnico

O plug-in input_agentsight utiliza eBPF para coleta. A capacidade de capturar tráfego criptografado HTTPS de um Agent específico depende se o eBPF consegue localizar as funções de envio/recebimento SSL no executável do Agent. Utilize a tabela a seguir para verificar a compatibilidade: