Pular para o conteúdo principal
A observabilidade do Toqan Router captura cada chamada de LLM, etapa de agente e uso de ferramenta como traces pesquisáveis, com latência, contagem de tokens e custo. O OpenTelemetry é a forma padrão e independente de framework de instrumentá-la.
  • Defina o endpoint OTLP do Toqan Router e autentique-se com uma chave de API
  • Configure o SDK do OpenTelemetry em uma aplicação existente
  • Veja cada chamada de LLM, etapa de agente e uso de ferramenta em Traces
  • Para a configuração específica de cada framework, consulte Frameworks em Integrations
1

Crie uma conta no Toqan Router

Cadastre-se para obter uma conta gratuita do Toqan Router e configure um workspace.
2

Configure o Toqan Router

Abra Settings > API Keys no AI Studio. Clique em Create API Key, dê um nome a ela e copie-a.Em seguida, abra um terminal e execute o comando abaixo, substituindo your-api-key-here pela chave copiada. Os exemplos de código das próximas etapas a leem dessa variável de ambiente.
3

Instrumente com OpenTelemetry

Instale o SDK do OpenTelemetry e o exportador OTLP HTTP:
Defina as variáveis de ambiente que apontam o SDK do OpenTelemetry para o coletor do Toqan Router:
Inicialize o tracer provider uma única vez na inicialização da aplicação. O exportador lê o endpoint, os cabeçalhos e o recurso das variáveis de ambiente acima:
O exportador aceita tanto https://router.toqan.ai/eu/v2/otel quanto o caminho completo https://router.toqan.ai/eu/v2/otel/v1/traces. Os spans de qualquer código instrumentado com OpenTelemetry são exportados automaticamente.O OTLP é servido por HTTP, com http/protobuf ou http/json. Os traces são recebidos em /v2/otel/v1/traces, os logs em /v2/otel/v1/logs e as métricas em /v2/otel/v1/metrics.Implantações auto-hospedadas e on-premise servem /v2/otel no próprio hostname. Consulte Base URLs.
4

Conecte um framework

Usa um framework? Instrumente o framework com a configuração própria dele em vez de criar spans manualmente. Cada página em Integrations mostra a instalação exata, as variáveis de ambiente e a chamada de instrumentação:

LangGraph

Uma única chamada setup() instrumenta o grafo, as ferramentas e cada etapa de LLM.

Vercel AI SDK

SDKs para Python e TypeScript com telemetria experimental do OpenTelemetry.

Pydantic AI

Instrumentação baseada em Logfire para agentes, ferramentas e streaming.

OpenAI Agents

Tracing automático via OpenAIAgentsInstrumentor.

Agno

Instrumentação OpenInference para agentes e ferramentas.

Google ADK

Rastreie workflows de agentes, chamadas de ferramentas e interações com modelos Gemini.

Mastra

Agentes e workflows em TypeScript com tracing do OpenTelemetry.

Claude Agent SDK

Instrumentação baseada em hooks para turnos do agente e uso de ferramentas.

Ver todos os frameworks

Lista completa de frameworks compatíveis e guias de configuração.
5

Visualize os traces

Execute o agente e abra Traces no AI Studio. Cada solicitação aparece com modelo, latência, contagem de tokens e custo. Em frameworks de agentes, as chamadas de ferramentas e as etapas individuais aparecem como spans filhos.
6

Analise os traces com MCP

Se o servidor Toqan Router MCP ainda não estiver conectado, instale-o no editor ou no assistente de IA e peça ao assistente de programação:
O assistente consulta o Toqan Router MCP e retorna uma análise como esta:
Para uma análise estruturada de falhas, a Toqan Router Skill analyze-traces lê os traces de produção, monta uma taxonomia de falhas e categoriza os problemas.

Solução de problemas

  1. Confirme que a variável está definida: echo $TOQAN_API_KEY
  2. Verifique se a chave está ativa em Settings > API Keys
  3. Confirme que a chave é passada no cabeçalho Authorization: Bearer do exportador OTLP, e não como parâmetro de consulta
  1. Confirme que o endpoint OTLP está definido como https://router.toqan.ai/eu/v2/otel (ou /v2/otel/v1/traces para exportadores que exigem o caminho completo)
  2. Verifique se o workspace da chave de API corresponde ao workspace do AI Studio que está sendo visualizado
  3. Os traces podem levar alguns segundos para aparecer; aguarde 10 segundos e atualize
  4. Faça o flush do tracer provider antes que um script curto termine. O processador em lote retém os spans por até 5 segundos, e um processo que termina antes disso os perde:
  5. Confirme que o sampler não está descartando tudo, por exemplo OTEL_TRACES_SAMPLER=always_off ou uma proporção de 0
  6. Um 415 com unsupported content type: expected application/x-protobuf or application/json significa que o cabeçalho Content-Type não é application/x-protobuf nem application/json. Use um exportador OTLP HTTP, que define o cabeçalho de acordo com a codificação do corpo

Anotar traces

Rotule e revise spans para criar datasets de avaliação de alta qualidade a partir do tráfego real de produção.

Configurar análises

Acompanhe custo, latência, taxas de erro e uso de tokens entre modelos e deployments ao longo do tempo.