Traces de LLM para depuração

Consulte URLs e autenticação HTTP e a referência da API para os formatos completos de solicitação e resposta.

O que são Traces

Os Traces registram cada solicitação de IA processada pelo Toqan Router, desde uma única chamada de modelo até uma execução de Agent com várias etapas. Cada trace mostra o fluxo completo de uma solicitação como uma árvore de etapas (spans), com entradas, saídas, latência, uso de tokens e custo de cada etapa. Traces são criados para:

Chamadas de modelo enviadas pelo AI Gateway
Execuções de Agents, incluindo chamadas de sub-agents e tools
Invocações de Deployments
Sessões de programação de assistentes de código conectados ao Toqan Router
Código de aplicação instrumentado com frameworks OpenTelemetry

Um trace contém uma etapa para cada operação da solicitação, como:

Chamadas de LLM, incluindo Retries e Fallbacks
Chamadas de tools e sub-agents
Evaluators e Guardrails
Recuperação de uma Knowledge Base, incluindo Embeddings
Cache

Criar Traces

Instrumentação de frameworks

Para frameworks e bibliotecas de IA populares, use a instrumentação automática com OpenTelemetry:

Integrações com frameworks

Explore a instrumentação automática para OpenAI, LangChain, LlamaIndex, CrewAI, Autogen e mais de 15 outros frameworks com integração OpenTelemetry.

Spans personalizados da aplicação

Use a API padrão do OpenTelemetry para criar spans da aplicação. Configure o exportador com o endpoint regional do guia de observabilidade e envolva a operação em um span:

Python

from opentelemetry import trace

tracer = trace.get_tracer("document-pipeline")

with tracer.start_as_current_span("process_document") as span:
    span.set_attribute("document.id", "doc-123")
    # Execute o processamento do documento aqui.

Spans filhos criados nesse contexto mantêm a hierarquia. Evite registrar segredos ou dados pessoais nos atributos.

Como consultar Traces

Para encontrar traces, abra Traces na seção Observability da barra lateral. A página tem três partes:

Barra de consulta: pesquisa, filtros, intervalo de tempo e os botões Views, Fields, Review e Reload.
Gráfico de atividade: o número de traces Successful e Errors no intervalo de tempo selecionado. Clique em uma barra, ou arraste sobre várias, para ampliar esse intervalo; o botão voltar restaura o intervalo anterior.
Tabela de traces: uma linha por trace, do mais recente para o mais antigo. Role para baixo para carregar mais traces.

O cabeçalho da página mostra o Total cost dos traces que correspondem ao período, aos filtros, à pesquisa ou consulta OQL e ao projeto atuais. Ele soma todo o conjunto correspondente, incluindo o custo dos evaluators, e não apenas as linhas carregadas na tabela. Selecione uma linha para abrir o trace em um painel lateral, que mostra a hierarquia de eventos na ordem de execução e os detalhes da etapa selecionada. Com um trace aberto, pressione J e K para ir para o trace seguinte ou anterior. O painel lateral empilha seções recolhíveis para a etapa selecionada:

Painel	Mostra
Properties	Trace ID, Span ID, Created, Message count, Model, Input Tokens, Output Tokens, Total Tokens e Estimated Cost.
Input e Output	O payload da etapa, como uma árvore recolhível.
Annotations	As anotações associadas à etapa.
Metadata	Os metadados e atributos da etapa.
Economics	Input tokens, Output tokens, Total tokens, Total cost, Input cost e Output cost.

Uma etapa que parou antes de terminar exibe um aviso Stopped early com a causa: limite de tokens de saída atingido, resposta bloqueada por um filtro de conteúdo, limite de agent atingido ou término anormal. O valor bruto também aparece como Finish reason em Properties. As variáveis passadas a um agent no campo variables são registradas como o atributo de span orq.variables, portanto aparecem em Metadata no painel lateral. Consulte Span Attributes para ver a lista de campos. Add to dataset copia a etapa selecionada para um dataset, e Add to annotation queue a envia para uma fila de anotação. Quando a etapa tem anotações, Copy annotations adiciona cada uma como uma entrada nomeada; a caixa de seleção fica indisponível quando já existe uma entrada chamada annotations. Ative Live para atualizar a lista a cada 10 segundos. O Live é pausado enquanto um trace está aberto.

Pesquisa, filtros, colunas e intervalo de tempo são armazenados na URL da página. Copie a URL para compartilhar exatamente a mesma lista com um colega.

Visualizações de trace

Cada trace pode ser inspecionado em três visualizações, de acordo com diferentes necessidades de depuração e análise.

Trace
Thread
Timeline

A visualização Trace mostra a árvore de execução completa de uma única execução. Cada etapa é exibida hierarquicamente, incluindo chamadas de LLM, invocações de tools, recuperações de conhecimento e interações com memória. Use essa visualização para inspecionar entradas, saídas, uso de tokens e latência em cada etapa.Em execuções com vários agents, a hierarquia é renderizada como um grafo de agents: os agents pais e suas chamadas a sub-agents são exibidos como uma árvore aninhada, facilitando acompanhar como o trabalho foi delegado entre os agents e onde o tempo foi gasto. Consulte Agent Graphs para saber como os grafos são produzidos e como depurar caminhos de delegação.

Traces com erro são exibidos com um ícone .

Avalie respostas manualmente usando Annotations diretamente em spans individuais. As anotações definidas no projeto ficam disponíveis automaticamente em todos os spans. Saiba mais em Annotations.

Pesquisa e intervalo de tempo

A caixa de pesquisa corresponde a parte de um ID de trace, ID de thread ou ID de sessão, e ao nome, ID de span, modelo, provedor, nome do agent ou nome da tool de qualquer span do trace. A correspondência não diferencia maiúsculas de minúsculas. Selecione o seletor de intervalo de tempo para escolher uma predefinição de 5 mins a 90 days, ou defina uma Start date e uma End date para um intervalo personalizado. Predefinições mais longas que a retenção de dados do workspace ficam desativadas. A última predefinição usada é lembrada na próxima visita.

Alterne a barra de consulta de Builder para OQL para escrever a consulta como um pipeline, por exemplo fetch traces | filter status == "error" | sort end_time desc | limit 100. Consulte Seleção de traces e logs com OQL.

Visualizar erros

Traces que encontraram um erro exibem um selo vermelho de status error na lista e são contados como Errors no gráfico de atividade. Adicione um filtro Status com o valor error para restringir a lista apenas aos erros. O selo success abrange os traces que a Telemetry API informa como ok ou unset; consulte Valores de status de trace. O filtro Status pode ser combinado com qualquer outro filtro, por exemplo:

Filtre por Status error e por uma Identity para ver todos os erros de um usuário específico.
Combine com Project ou com um campo de metadados para restringir as falhas a um ambiente ou deployment específico.

Salve o filtro como uma view para voltar a ele com um clique.

Filtrar Traces

Clique em Filter na barra de consulta.
Selecione um campo. Pesquise na lista para encontrá-lo mais rápido. Campos comuns, como Status, Model e Trace name, aparecem primeiro, seguidos dos campos de atributos e metadados encontrados nos traces do workspace.
Selecione um operador, por exemplo ==, !=, contains, in, between ou is empty.
Escolha um valor sugerido ou digite um e clique em Filter.

O primeiro filtro é aplicado imediatamente. Cada filtro aparece então como um chip abaixo da barra de consulta:

Clique em um chip para alterar o operador ou o valor, ou clique em para removê-lo.
Clique em para adicionar outro filtro.
Com dois ou mais filtros, escolha and para corresponder a todos ou or para corresponder a qualquer um.
As alterações nos filtros aguardam até que Run seja clicado. Clear remove todos os filtros de uma vez.

Ao trabalhar com Agents, acesse os traces diretamente na página do Agent, com filtragem automática para aquele agent específico.

Gramática de filtros

As APIs Search traces e Search logs recebem um array filters junto com a query de texto livre. Cada entrada é uma condição:

{
  "field": "status",
  "op": "in",
  "values": ["error"]
}

Chave	Valor
`field`	Nome do campo, com até 128 caracteres entre letras, dígitos e `_ . : -`
`op`	Operador de comparação, do conjunto abaixo
`values`	Array de strings, com até 100 entradas de até 4096 caracteres cada. Valores numéricos e de timestamp são enviados como strings

filter_operator combina as entradas com and (padrão) ou or. Uma solicitação aceita até 20 filtros. from e to são obrigatórios e delimitam a janela de pesquisa; sort, limit e page_token seguem a referência de Search traces para traces e a referência de Search logs para logs. Os valores de op são eq, neq, in, not_in, gt, gte, lt, lte, between, contains, exists e not_exists. A tabela lista os operadores que cada tipo costuma aceitar; um campo específico pode aceitar menos ou mais:

Tipo de campo	Operadores	Exemplo
String	`eq`, `neq`, `in`, `not_in`, `contains`, `exists`, `not_exists`	`{"field": "name", "op": "contains", "values": ["checkout"]}`
Number	`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `between`, `exists`	`{"field": "tokens.total", "op": "gt", "values": ["1000"]}`
Timestamp	`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `between`, `exists`, `not_exists`	`{"field": "start_time", "op": "gte", "values": ["2026-10-01T00:00:00Z"]}`
Boolean	`eq`, `neq`, `exists`, `not_exists`	`{"field": "eval_passed", "op": "eq", "values": ["true"]}`
Enum	`eq`, `neq`, `in`, `not_in`	`{"field": "status", "op": "in", "values": ["error"]}`

between recebe exatamente dois valores, com o limite inferior primeiro. exists e not_exists não recebem valores. O suporte varia de acordo com o campo, portanto chame GET /v3/traces/fields para obter os campos de filtro, seus tipos e os operadores aceitos por cada um. A pesquisa de logs usa o mesmo objeto de filtro e o mesmo vocabulário de operadores. Filtrar os erros de uma identidade. Defina filter_operator como and e combine as condições em uma única solicitação:

{
  "from": "2026-10-01T00:00:00Z",
  "to": "2026-10-02T00:00:00Z",
  "filter_operator": "and",
  "filters": [
    { "field": "identity_id", "op": "eq", "values": ["<external_id>"] },
    { "field": "status", "op": "in", "values": ["error"] }
  ]
}

identity_id contém a identidade à qual uma solicitação foi atribuída: o valor passado como identity.id em uma resposta de Agent ou invocação de Deployment, ou no cabeçalho X-TOQAN-IDENTITY-ID. Ele corresponde ao filtro Identity no AI Studio. Filtrar por API key. Cada span registra a chave que fez a solicitação, pelo identificador e não pelo segredo, em orq.api_key_id (consulte Atributos de span). Filtre com o campo API Key ID na barra de consulta ou passe a condição para Search traces:

{ "field": "api_key_id", "op": "eq", "values": ["<api_key_id>"] }

Para ver o gasto por chave, detalhe a Activity por API keys.

Configurar colunas

Clique em Fields para abrir o painel Fields e escolher quais colunas a tabela exibe. Todos os campos de atributos e metadados encontrados nos traces do workspace podem ser exibidos como colunas, ao lado das colunas integradas: Start time, Status, Name, Duration, Total tokens, Input tokens, Output tokens, Cached input tokens, Total cost, Project, Metadata, Signals e Trace ID.

Mostrar ou ocultar: marque ou desmarque um campo. Pesquise no painel para encontrar um campo pelo nome.
Reordenar: alterne para Selected e arraste um campo por para mover sua coluna. A reordenação só funciona enquanto todos os campos selecionados estão visíveis, portanto limpe a caixa de pesquisa antes.
Redimensionar: arraste a borda direita do cabeçalho de uma coluna.
Renomear: abra no cabeçalho de uma coluna de atributo ou metadados e selecione Edit name para definir um nome de exibição.
Remover: abra no cabeçalho de uma coluna e selecione Remove para ocultá-la.

As larguras e a ordem das colunas são lembradas no navegador. Para manter um layout de colunas e compartilhá-lo com o workspace, salve-o em uma view.

Criar views personalizadas

Uma view salva os filtros, as colunas e os nomes de colunas atuais com um nome, para que você possa reabri-los depois no menu suspenso Views. Para criar uma view:

Defina os filtros e as colunas.
Abra Views e selecione Create new view.
Insira um Name.
Opcionalmente, marque Make this view private for myself. Por padrão, as views são compartilhadas com os membros do workspace.
Clique em Create View.

Para atualizar uma view, selecione-a, altere os filtros ou as colunas, abra Save ao lado dos chips de filtro e selecione Save to this view. Quando apenas as colunas tiverem mudado, clique em Update view na barra de consulta. Passe o cursor sobre uma view no menu suspenso para gerenciá-la:

: define ou remove a view como padrão. A view padrão abre automaticamente na página Traces.
> Edit: altera o nome ou a privacidade.
> Share: copia um link que abre a view com seus filtros.
> Delete: exclui a view.

Selecione Default view para voltar às colunas padrão sem filtros salvos.

As views salvas na página Traces anterior foram movidas para a nova página. Os filtros que a nova página não consegue expressar foram ajustados ou removidos.

Gerencie as Views salvas de forma programática pela Views API.

Revisar Traces

Clique em Review na barra de ferramentas para abrir a tela de revisão e percorrer os traces um a um. Aplicar um ou mais filtros antes restringe a fila de revisão aos traces correspondentes; sem nenhum filtro ativo, o Review percorre a lista atual. A tela segue o mesmo layout de três painéis das Annotation Queues:

Esquerda: entradas e métricas do span selecionado.
Centro: conversa completa do trace.
Direita: controles de Annotation para revisão manual. Selecione no cabeçalho do painel Annotations para criar uma nova anotação sem sair da tela.

As anotações aplicadas aqui são gravadas de volta no span e podem ser consultadas pelo Toqan Router MCP.

Corrigir um resultado de Evaluator

Passe o cursor sobre um resultado de Evaluator para exibir um e selecione-o para abrir um popover com:

Value: o resultado corrigido, no mesmo tipo de saída do Evaluator (um botão de alternância para Evaluators booleanos; caso contrário, um campo de texto ou número).
Explanation: um comentário opcional.

Selecione Correct para enviar ou Update para substituir uma correção existente. A correção aparece abaixo do resultado original como Corrected to <value>, junto com a explicação e o nome do revisor. As correções são gravadas de volta no Trace como qualquer outra anotação. Isso fornece uma base para comparar, ao longo do tempo, os resultados do próprio Evaluator com as correções dos revisores, usando esse sinal (por exemplo, pelo Toqan Router MCP) para identificar onde a configuração de um Evaluator pode precisar de ajustes.

Isso corrige o resultado do Evaluator, e não o texto da resposta da IA. Para reescrever a própria resposta, use o fluxo Add a Text Correction de Logs.

Consulte Corrigir um resultado de Evaluator na aba API & SDK para ver o equivalente em API/SDK.

Threads

Visualize o histórico de conversas como Threads para acompanhar toda a sequência de mensagens de uma sessão de agent.

Referência

Rastreamento de tokens e custos

Como o uso de tokens é capturado e o custo é calculado por solicitação de LLM.

Span Attributes

Referência completa de todos os atributos de span orq.* emitidos em traces, payloads de webhook e exportações de traces.

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

O que são Traces

Criar Traces

Instrumentação de frameworks

Integrações com frameworks

Spans personalizados da aplicação

Como consultar Traces

Visualizações de trace

Pesquisa e intervalo de tempo

Visualizar erros

Filtrar Traces

Gramática de filtros

Configurar colunas

Criar views personalizadas

Revisar Traces

Corrigir um resultado de Evaluator

Threads

Threads

Referência

Rastreamento de tokens e custos

Span Attributes

​O que são Traces

​Criar Traces

​Instrumentação de frameworks

Integrações com frameworks

​Spans personalizados da aplicação

​Como consultar Traces

​Visualizações de trace

​Pesquisa e intervalo de tempo

​Visualizar erros

​Filtrar Traces

​Gramática de filtros

​Configurar colunas

​Criar views personalizadas

​Revisar Traces

​Corrigir um resultado de Evaluator

​Threads

Threads

​Referência

Rastreamento de tokens e custos

Span Attributes

O que são Traces

Criar Traces

Instrumentação de frameworks

Spans personalizados da aplicação

Como consultar Traces

Visualizações de trace

Pesquisa e intervalo de tempo

Visualizar erros

Filtrar Traces

Gramática de filtros

Configurar colunas

Criar views personalizadas

Revisar Traces

Corrigir um resultado de Evaluator

Threads

Referência