> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Traces de LLM para depuração > Explore os detalhes passo a passo de cada geração de LLM. Depure pipelines de RAG, evaluators, guardrails e cache com visibilidade completa do fluxo de trabalho e rastreamento de custos. Consulte [URLs e autenticação HTTP](/docs/pt-BR/reference/base-urls.md) 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](/docs/pt-BR/ai-gateway/using-the-router.md) * 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](/docs/pt-BR/ai-studio/integrations/frameworks/overview.md) 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: > [card] [Integrações com frameworks](/docs/pt-BR/ai-studio/integrations/frameworks/overview.md) > > 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](/docs/pt-BR/ai-studio/observability/quickstart.md) e envolva a operação em um span: ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/docs/pt-BR/ai-studio/observability/trace-evaluations.md), 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](/docs/pt-BR/ai-studio/observability/span-attributes.md) 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. > [!TIP] > > 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. > [tab] Trace > > 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](/docs/pt-BR/ai-studio/observability/agent-graphs.md) para saber como os grafos são produzidos e como depurar caminhos de delegação. > > > [!TIP] > > > > Traces com erro são exibidos com um ícone . > > > [!NOTE] > > > > 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](/docs/pt-BR/ai-studio/observability/annotations.md). > [tab] Thread > > A visualização **Thread** apresenta a execução como um thread de conversa, mostrando a sequência de mensagens trocadas entre o usuário, o agent e quaisquer tools. Use essa visualização para acompanhar o fluxo narrativo de uma tarefa e entender como o agent raciocinou sobre um problema. > [tab] Timeline > > A visualização **Timeline** mostra as etapas de execução distribuídas ao longo do tempo, facilitando identificar gargalos, medir a duração das etapas e entender quais operações foram executadas em sequência ou em paralelo. ### 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. > [!TIP] > > 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](/docs/pt-BR/ai-studio/observability/oql.md). ### 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](/docs/pt-BR/ai-studio/observability/telemetry-api.md#trace-status-values). O filtro **Status** pode ser combinado com qualquer outro filtro, por exemplo: * Filtre por **Status** `error` e por uma [**Identity**](/docs/pt-BR/ai-studio/observability/identities.md) 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](#creating-custom-views) para voltar a ele com um clique. ### Filtrar Traces 1. Clique em Filter na barra de consulta. 2. 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. 3. Selecione um operador, por exemplo `==`, `!=`, `contains`, `in`, `between` ou `is empty`. 4. 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. > [!NOTE] > > 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: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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](/docs/pt-BR/reference/traces/search-traces.md) para traces e a [referência de Search logs](/docs/pt-BR/reference/logs/search-logs.md) 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: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "from": "2026-10-01T00:00:00Z", "to": "2026-10-02T00:00:00Z", "filter_operator": "and", "filters": [ { "field": "identity_id", "op": "eq", "values": [""] }, { "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](/docs/pt-BR/ai-studio/observability/span-attributes.md#tenant-scope)). Filtre com o campo **API Key ID** na barra de consulta ou passe a condição para `Search traces`: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "field": "api_key_id", "op": "eq", "values": [""] } ``` Para ver o gasto por chave, detalhe a [Activity](/docs/pt-BR/ai-studio/observability/activity.md#spend) 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: 1. Defina os filtros e as colunas. 2. Abra Views e selecione **Create new view**. 3. Insira um **Name**. 4. Opcionalmente, marque **Make this view private for myself**. Por padrão, as views são compartilhadas com os membros do workspace. 5. 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. > [!NOTE] > > 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](/docs/pt-BR/ai-studio/observability/views-api.md). ## 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](#filtering-traces) 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](/docs/pt-BR/ai-studio/observability/annotation-queues.md#use-annotation-queues): * **Esquerda**: entradas e métricas do span selecionado. * **Centro**: conversa completa do trace. * **Direita**: controles de [Annotation](/docs/pt-BR/ai-studio/observability/annotations.md) para revisão manual. Selecione no cabeçalho do painel Annotations para [criar uma nova anotação](/docs/pt-BR/ai-studio/observability/annotations.md#create-annotations) 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 \**, 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. > [!NOTE] > > 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**](/docs/pt-BR/ai-studio/observability/annotations.md#use-annotations) de Logs. > [!NOTE] > > Consulte [Corrigir um resultado de Evaluator](/docs/pt-BR/ai-studio/observability/annotations.md#use-annotations) na aba API & SDK para ver o equivalente em API/SDK. ## Threads > [card] [Threads](/docs/pt-BR/ai-studio/observability/threads.md) > > Visualize o histórico de conversas como Threads para acompanhar toda a sequência de mensagens de uma sessão de agent. ## Referência > [card] [Rastreamento de tokens e custos](/docs/pt-BR/ai-studio/observability/token-cost-tracking.md) > > Como o uso de tokens é capturado e o custo é calculado por solicitação de LLM. > [card] [Span Attributes](/docs/pt-BR/ai-studio/observability/span-attributes.md) > > Referência completa de todos os atributos de span `orq.*` emitidos em traces, payloads de webhook e exportações de traces. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.