Logs e Eventos no Studio

Índice

1. Introdução
2. O que é Logs e Eventos e quando usar?
3. Como acessar e gerar logs
4. Conhecendo a tela de Logs e Eventos
5. Como localizar uma conversa específica
6. Como interpretar eventos e ações
7. Como visualizar erros
8. Como visualizar trackings
9. Como analisar execuções com IA
10. Como usar Logs e Eventos com Testes Unitários
11. Como consultar e limpar dados do contato
12. Boas práticas de debug
13. Problemas comuns
14. Perguntas frequentes (FAQ)
15. Limitações e pontos de atenção
16. Glossário rápido

Introdução

A tela de Logs e Eventos ajuda usuários do Studio a acompanhar e investigar execuções de fluxos conversacionais.

Com ela, é possível visualizar mensagens trafegadas, eventos gerados, ações executadas, erros, trackings, payloads técnicos e consumo de tokens em interações com agentes de IA.

A nova experiência organiza essas informações em uma jornada de investigação: primeiro você localiza a conversa, depois acompanha a timeline da interação, expande a árvore de execução e analisa os detalhes técnicos de cada evento.
 

O que é Logs e Eventos e quando usar?

Logs e Eventos são registros gerados durante a execução de um fluxo conversacional. Eles ajudam a entender o que aconteceu em uma conversa, qual caminho o fluxo percorreu e quais eventos técnicos foram gerados em cada etapa.

Use Logs e Eventos para:

• Testar fluxos em construção;

• Investigar conversas de bots publicados;

• Validar se o fluxo percorreu o caminho esperado;

• Identificar erros ou comportamentos inesperados;

• Consultar payloads, JSONs e variáveis;

• Verificar trackings;

• Analisar execuções de agentes de IA;

• Acompanhar consumo de tokens;

• Apoiar troubleshooting antes ou depois da publicação de um fluxo.

A tela ajuda a responder perguntas como:

• Qual mensagem iniciou a execução?

• Qual bloco ou agente foi acionado?

• O fluxo passou pelo caminho esperado?

• Houve erro?

• Algum tracking foi registrado?

• Houve chamada de ferramenta?

• Quantos tokens foram consumidos?

• Qual foi o output gerado?

Como acessar e gerar logs

Para usar Logs e Eventos, abra o bot ou fluxo que deseja investigar.

1. No Studio, acesse o fluxo desejado.

2. No canto superior direito da tela, clique no ícone de testes/laboratório.

3. Selecione Logs e Eventos.

A tela será aberta com a lista de conversas e eventos disponíveis.

Para gerar novos logs, inicie uma interação com o bot. Você pode fazer isso testando um fluxo em construção, um chatbot publicado ou uma conversa real em um canal integrado.

Em bots publicados, use um contato conhecido, filtre pelo canal e anote o horário aproximado da interação para encontrar a conversa com mais facilidade.

Conhecendo a tela de Logs e Eventos

A nova tela é organizada em quatro áreas principais.

• Lista de conversas: A lista de conversas mostra as interações disponíveis para investigação. Selecione uma conversa para visualizar sua timeline e os eventos associados.

• Timeline da conversa: A timeline apresenta a interação em formato conversacional, permitindo entender o contexto antes de analisar os detalhes técnicos. Ela pode exibir mensagens enviadas pelo usuário, respostas do bot, respostas de agentes de IA e outros elementos relacionados à execução.

• Árvore de execução: A árvore de execução mostra os eventos e ações técnicas geradas durante a conversa. Ao expandir os itens, você pode acompanhar o caminho percorrido pelo fluxo.

• Painel lateral: O painel lateral exibe os detalhes do evento selecionado. Dependendo do tipo de evento, você poderá consultar input, output, JSON, payloads, trackings, erros, Tool Calls, tempo de execução e consumo de tokens.

Como localizar uma conversa específica

Em ambientes de teste, geralmente é simples localizar a conversa recém-criada. Em bots publicados ou com alto volume de mensagens, pode ser necessário usar filtros.

• Usando filtro por canal: Use o filtro por canal para visualizar apenas conversas originadas de um canal específico, como Blip Chat, WhatsApp ou outro canal integrado.

• Usando busca por contato: Quando disponível, use a busca por contato para localizar uma conversa associada a um usuário específico. A busca pode ser feita por id ou nome do usuário.

Recomendações para bots com muitas conversas

Ao testar bots em produção:

• Utilize um contato conhecido;

• Envie uma mensagem fácil de identificar;

• Anote o horário aproximado do teste;

• Filtre pelo canal usado;

• Procure pelo contato;

• Aguarde alguns segundos caso a conversa ainda não apareça.

O que verificar se a conversa não aparecer

Verifique se:

• a mensagem foi realmente enviada;

• o canal correto está selecionado;

• o bot está publicado ou em teste corretamente;

• você está no bot ou fluxo correto;

• há filtros ativos escondendo a conversa;

• a tela precisa ser atualizada;

• existe delay na chegada dos logs.

Como interpretar eventos e ações

A árvore de execução mostra os eventos técnicos associados à conversa selecionada. Ao expandir os itens da árvore, você pode acompanhar o caminho percorrido pelo fluxo e consultar os detalhes de cada etapa.

Lista de alguns dos eventos que poderão ser encontrados:

Para inspecionar um evento:

1. Selecione uma conversa.

2. Expanda a árvore de execução.

3. Clique no evento que deseja analisar.

4. Consulte as informações exibidas no painel lateral.

Use o JSON ou payload técnico quando precisar confirmar campos enviados ou recebidos, validar valores de variáveis, analisar retornos de integrações ou compartilhar evidências com times de suporte e engenharia.

Como visualizar erros

Quando um erro é registrado, ele pode aparecer associado a um evento ou ação da execução.

Para investigar erros:

1. Localize a conversa;

2. Expanda a árvore de execução;

3. Procure eventos marcados como erro ou falha;

4. Clique no evento;

5. Consulte o painel lateral;

6. Verifique mensagem de erro, payload, ação relacionada e contexto anterior.

Ao analisar um erro, procure responder:

• Qual mensagem iniciou a execução?

• Qual bloco estava sendo executado?

• Qual ação falhou?

• O erro ocorreu antes ou depois de uma chamada externa?

• O erro ocorreu em bloco determinístico, agente de IA ou Tool Call?

• Existe payload de retorno?

• Existe mensagem de erro clara?

• O erro se repete em novos testes?

Como visualizar trackings

Trackings ajudam a acompanhar eventos importantes do fluxo, como conversões, etapas concluídas, ações do usuário ou eventos de negócio.

Na nova experiência, os trackings aparecem integrados à inspeção do evento, permitindo analisá-los dentro do contexto da execução.

Para visualizar trackings:

1. Selecione uma conversa;

2. Expanda a árvore de execução;

3. Clique em um evento ou bloco;

4. Acesse a área de trackings no painel lateral, quando disponível.

Um tracking pode conter informações como:

• categoria;

• ação;

• nome do evento;

• propriedades adicionais;

• valores enviados;

• contexto da execução.

Use trackings para validar se eventos importantes estão sendo registrados corretamente, como início de jornada, conclusão de etapa, clique ou escolha do usuário, conversão, erro de negócio ou passagem por determinado bloco.

Como analisar execuções com IA

Em fluxos com agentes de IA, Logs e Eventos ajuda a entender não apenas o caminho do fluxo, mas também o comportamento do agente.

Você pode analisar:

• qual agente foi acionado;

• qual input chegou para o agente;

• quais instruções ou prompt foram consideradas;

• quais ferramentas estavam disponíveis;

• se alguma Tool Call foi executada;

• qual resposta foi gerada;

• se houve erro;

• quanto tempo a execução levou;

• quantos tokens foram consumidos.

Agent Run

O Agent Run representa a execução de um agente de IA. Ele indica que o fluxo acionou um agente para interpretar o contexto, executar uma tarefa, gerar uma resposta ou acionar ferramentas.

Use esse evento para entender quando um agente foi acionado e qual parte da conversa está relacionada à sua execução.

LLM Invoke

O LLM Invoke representa a chamada ao modelo de linguagem. É nesse evento que normalmente aparecem informações relacionadas ao input enviado ao modelo, output gerado, tempo de execução e consumo de tokens.

Use esse evento para analisar:

• o que foi enviado para o modelo;

• qual resposta foi gerada;

• quanto tempo a execução levou;

• quantos tokens foram consumidos;

• se o comportamento do agente está coerente com o esperado.

Tool Calls

Tool Calls são chamadas de ferramentas realizadas por agentes de IA.

Elas podem representar, por exemplo:

• consulta a uma API;

• busca em base de conhecimento;

• definição de contato;

• registro de informações;

• execução de uma ação externa;

• acionamento de uma ferramenta configurada no agente.

Quando um agente usa uma ferramenta, a Tool Call aparece associada à execução do agente. Ao analisar uma Tool Call, verifique:

• qual ferramenta foi chamada;

• quais parâmetros foram enviados;

• qual retorno foi recebido;

• se houve erro;

• quanto tempo a chamada levou;

• se a chamada impactou o output final do agente.

Tool Calls e trackings

Quando um tracking é registrado diretamente como Track Event, ele aparece na área de trackings.

Quando o tracking acontece por meio de uma Tool Call, pode ser necessário verificar a própria Tool Call na árvore de execução e, se necessário, validar o evento em relatórios complementares.

Consumo de tokens

Tokens são unidades de texto processadas pelo modelo de linguagem. Tudo o que o agente lê e escreve é convertido em tokens.

O consumo de tokens pode ajudar a entender:

• custo da execução;

• tamanho do contexto enviado para o agente;

• tamanho da resposta gerada;

• impacto do histórico de conversa;

• impacto de ferramentas e instruções;

• possíveis oportunidades de otimização.

Você pode visualizar tokens em eventos relacionados à execução de agentes de IA, especialmente em eventos como LLM Invoke.

O consumo pode aumentar quando:

• o prompt é muito longo;

• há muitas instruções no agente;

• o histórico de conversa está grande;

• muitas ferramentas estão disponíveis;

• a base de contexto enviada ao agente é extensa;

• a resposta gerada é longa;

• há múltiplas chamadas de LLM na mesma execução.

Como investigar uma resposta inesperada de IA

Quando um agente responder de forma inesperada:

1. Abra a conversa em Logs e Eventos;

2. Localize a execução do agente;

3. Abra o evento de LLM Invoke;

4. Verifique o input enviado;

5. Verifique o output gerado;

6. Analise o prompt ou instruções, quando disponível;

7. Veja se o histórico influenciou a resposta;

8. Verifique se alguma Tool Call foi acionada;

9. Consulte tokens e tempo de execução;

10. Ajuste o fluxo, prompt, ferramentas ou base de conhecimento conforme necessário.

Como usar Logs e Eventos com Testes Unitários

Logs e Eventos e Testes Unitários têm objetivos diferentes, mas podem ser usados em conjunto.

Use os dois juntos quando um teste unitário falhar e você precisar entender o motivo.

Fluxo recomendado:

1. Execute o teste unitário;

2. Se o teste falhar, abra Logs e Evento;

3. Localize a conversa ou execução gerada pelo teste;

4. Expanda a árvore de execução;

5. Verifique onde o comportamento divergiu do esperado;

6. Analise input, output, erros, trackings, Tool Calls e tokens.

Alguns fluxos dependem de palavras-chave, gatilhos ou condições iniciais para direcionar a conversa corretamente. Se o teste unitário não incluir o input necessário para acionar esse caminho, o fluxo pode não chegar ao agente ou bloco esperado.

Como consultar e limpar dados do contato

Durante testes, pode ser necessário limpar os dados de um contato para reiniciar a jornada e validar o fluxo desde o início.

Na tela de Logs e Eventos, ao selecionar uma conversa ou contato, você pode acessar detalhes relacionados ao contato, como variáveis e informações de contexto.

Para limpar ou restaurar dados do contato:

1. Selecione a conversa desejada.

2. Clique no cabeçalho ou área de detalhes do contato.

3. Abra o painel lateral de informações do contato.

4. Localize a opção de restaurar ou limpar dados.

5. Confirme a ação, se aplicável.

6. Execute o teste novamente.

Boas práticas de debug

Antes de publicar ou alterar um fluxo, use Logs e Eventos para validar se a execução está acontecendo conforme esperado.

Verifique se:

• a conversa aparece na lista de Logs e Eventos;

• a timeline representa corretamente a interação;

• a árvore de execução segue o caminho esperado;

• os blocos corretos foram executados;

• os direcionamentos aconteceram corretamente;

• não há erros inesperados;

• os trackings esperados foram registrados;

• chamadas HTTP retornaram sucesso;

• scripts foram executados corretamente;

• agentes de IA receberam o input correto;

• Tool Calls foram acionadas quando esperado;

• respostas da IA estão coerentes;

• consumo de tokens está dentro do esperado;

• tempo de execução está aceitável.

Para reportar um problema, inclua:

• nome do bot;

• ambiente;

• canal utilizado;

• horário aproximado do teste;

• contato usado;

• mensagem enviada pelo usuário;

• print ou vídeo da tela;

• evento ou erro observado;

• JSON ou payload relevante, quando possível;

• comportamento esperado;

• comportamento ocorrido.

Problemas comuns

1. Não aparece nenhum log

Possíveis causas:

• nenhuma conversa foi iniciada;

• o bot não recebeu mensagem;

• o canal selecionado não é o correto;

• há filtro ativo;

• existe delay na renderização;

• o bot ou fluxo aberto não é o mesmo usado no teste.

O que fazer:

1. Envie uma nova mensagem pelo chat de teste;

2. Verifique se está no bot correto;

3. Remova filtros ativos;

4. Aguarde alguns segundos;

5. Atualize a tela;

6. Tente novamente.

2. Não encontro minha conversa em produção

Possíveis causas:

• há muitas conversas acontecendo ao mesmo tempo;

• o contato não foi identificado corretamente;

• o canal filtrado está incorreto;

• a conversa ainda não foi renderizada.

O que fazer:

1. Filtre pelo canal usado;

2. Use a busca por contato;

3. Procure pelo horário aproximado da interação;

4. Envie uma nova mensagem de teste fácil de identificar;

5. Aguarde atualização da lista.

3. O filtro não abre ou não responde

Possíveis causas:

• comportamento intermitente da interface;

• conflito local na sessão;

• delay de carregamento;

• problema no navegador.

O que fazer:

1. Aguarde alguns segundos;

2. Feche e reabra o chat de teste;

3. Atualize a página;

4. Tente novamente;

5. Registre um vídeo se o problema persistir;

6. Reporte para o time responsável;

4. A ordem dos eventos parece incorreta

Possíveis causas:

• Eventos podem chegar de fontes diferentes;

• Pode haver delay na renderização;

• A ordenação pode depender do timestamp disponível;

• Alguns eventos de IA e eventos determinísticos podem ser registrados em momentos diferentes.

O que fazer:

1. Verifique os detalhes de cada evento;

2. Consulte horário e tipo da ação;

3. Compare com a timeline da conversa;

4. Reexecute o teste, se necessário;

5. Reporte caso a ordem prejudique a análise;

5. O tracking esperado não apareceu

Possíveis causas:

• O fluxo não passou pelo bloco que registra o tracking;

• O tracking não foi configurado corretamente;

• O tracking foi feito via Tool Call;

• O evento não aparece na aba de Trackings, mas aparece na árvore de execução;

• Há delay na renderização.

O que fazer:

1. Confirme se o fluxo passou pelo bloco esperado.

2. Verifique a árvore de execução.

3. Consulte a área de trackings.

4. Procure Tool Calls relacionadas.

5. Valide em relatórios externos, se necessário.

6. O consumo de tokens parece alto

Possíveis causas:

• prompt longo;

• histórico de conversa extenso;

• muitas instruções;

• muitas ferramentas disponíveis;

• resposta longa;

• múltiplas chamadas de LLM;

• contexto grande enviado para o agente.

O que fazer:

1. Abra o evento de LLM Invoke;

2. Verifique input tokens;

3. Verifique output tokens;

4. Veja se há histórico muito extenso;

5. Revise prompt e instruções;

6. Avalie se há ferramentas desnecessárias disponíveis;

7. Compare execuções diferentes.

7. O teste unitário falhou, mas não sei por quê

O Teste Unitário mostra o resultado da validação, mas pode não mostrar todos os detalhes investigativos da execução.

O que fazer:

1. Abra Logs e Eventos em paralelo;

2. Localize a execução gerada pelo teste;

3. Expanda a árvore;

4. Verifique em qual etapa houve divergência;

5. Analise input, output, erros, Tool Calls e tokens;

6. Confirme se o teste incluiu gatilhos ou palavras-chave necessárias.

Perguntas frequentes (FAQ)

Logs e Eventos funciona em bots publicados?

Sim. Em bots publicados, a tela pode exibir conversas de múltiplos usuários. Use filtros, busca por contato, canal e horário aproximado para localizar a conversa desejada.

Logs e Eventos substitui o Beholder?

A nova experiência centraliza a investigação de logs diretamente no Studio e foi criada para tornar o processo de debug mais claro, acessível e integrado à construção do fluxo.

Logs e Eventos salva histórico?

Logs e Eventos foi desenhado principalmente para apoiar debug e inspeção de execuções. A disponibilidade histórica dos dados pode variar conforme o tipo de informação, ambiente, canal e implementação da funcionalidade.

Para auditoria ou análises históricas consolidadas, utilize os relatórios e dashboards recomendados pelo time responsável.

Qual a diferença entre Logs e Eventos e Testes Unitários?

Testes Unitários validam se uma entrada gera a saída esperada. Logs e Eventos ajudam a investigar tecnicamente o caminho percorrido e os eventos gerados durante a execução.

Onde vejo consumo de tokens?

Em eventos relacionados à execução de IA, especialmente em LLM Invoke.

O que são input tokens?

São os tokens enviados para o modelo processar, incluindo instruções, contexto, histórico, ferramentas disponíveis e mensagem do usuário.

O que são output tokens?

São os tokens gerados pelo modelo na resposta.

O que é input cached?

É a parte do input que pode ter sido reaproveitada em cache pelo modelo, quando aplicável.

Por que o consumo de tokens aumenta ao longo da conversa?

Porque o agente pode receber mais histórico e contexto conforme a conversa avança. Quanto mais informações forem enviadas ao modelo, maior tende a ser o consumo de tokens.

Tool Calls aparecem na tela?

Sim. Quando houver Tool Calls registradas, elas podem aparecer na árvore de execução, associadas à execução do agente.

Tool Calls aparecem na aba Trackings?

Quando o tracking é registrado diretamente como Track Event, ele aparece na área de trackings. Quando ocorre via Tool Call, pode ser necessário consultar a própria Tool Call na árvore de execução.

O que significa “inatividade” na timeline?

A indicação de inatividade representa um comportamento ou evento do fluxo, não uma mensagem digitada pelo usuário.

Como limpar os dados de um contato para testar de novo?

Acesse os detalhes do contato pela conversa selecionada e use a opção de restaurar, limpar ou resetar dados do contato.

O que fazer quando encontrar um bug?

Registre bot, ambiente, canal, horário, contato, mensagem enviada, prints ou vídeo, evento com erro, payload relevante, comportamento esperado e comportamento observado. Depois, envie o material para o canal de suporte ou time responsável pela funcionalidade.

Limitações e pontos de atenção

Antes de usar Logs e Eventos, considere os seguintes pontos:

A proposta da nova experiência é centralizar o processo de debug técnico no Studio, reduzindo gradualmente a dependência de ferramentas paralelas como Beholder e a aba de debug do Blip Chat.

Glossário rápido

Precisa de mais ajuda? Explore nossos conteúdos na Blip Academy ou Blip Community, assista a tutoriais no nosso canal do YouTube ou tire suas dúvidas em nosso canal de atendimento 😃