Pular para o conteúdo principal

Visão geral

Exporte traces do Toqan Router para um backend de observabilidade via OTLP/HTTP. Administradores da organização configuram destinos, escolhem os Projects a incluir e controlam se cada destino recebe metadados ou o conteúdo completo. A exportação contínua e a exportação histórica usam a mesma configuração de destino.
Pela API, os destinos são gerenciados com uma Management Key que tenha a permissão de destinos OpenTelemetry; chaves de API comuns e com escopo de projeto não podem gerenciar destinos. Uma atualização substitui o destino inteiro: envie todos os cabeçalhos de solicitação que deseja manter, com valor vazio para preservar o segredo armazenado, pois os cabeçalhos omitidos são removidos.

Adicionar um destino

  1. Abra Settings > Organization > OpenTelemetry.
  2. Selecione Destination.
  3. Informe a URL do endpoint OTLP e os cabeçalhos de solicitação necessários.
  4. Escolha um Content mode e os Projects de origem e, em seguida, selecione Connect destination.
Obtenha o endpoint OTLP/HTTP e os cabeçalhos de autenticação no backend receptor. Os valores dos cabeçalhos ficam ocultos depois de salvos. Ao editar, deixe vazio o valor de um cabeçalho existente para manter o valor salvo.

Configuração

Metadata only é o padrão. A exportação com conteúdo completo usa os dados disponíveis no Toqan Router; conteúdo removido por mascaramento ou retenção não pode ser recuperado pela exportação. A filtragem de metadados segue os nomes e tipos de atributos das convenções GenAI do OpenTelemetry. Ela inclui booleanos e listas padrão e mantém os campos operacionais de eventos GenAI reconhecidos, quando disponíveis. Os identificadores de correlação existentes do Toqan Router também são mantidos. Esse modo é mais restritivo do que a configuração NO_CONTENT upstream: descrições livres, explicações de avaliações, esquemas de tools, documentos recuperados e referências a conteúdo armazenado exigem Full content. Atributos desconhecidos são excluídos de Metadata only.

Endpoints personalizados

Informe a URL base OTLP e os cabeçalhos de solicitação necessários. Use a configuração avançada de endpoint de traces quando o receptor esperar um caminho diferente de /v1/traces. Use um endpoint HTTPS acessível publicamente. Os destinos não podem usar o host da plataforma Toqan Router. Os spans exportados carregam o atributo telemetry_export.exported, de modo que spans que retornam ao Toqan Router são armazenados, mas não são enviados novamente pela exportação contínua.

Exportar traces existentes

Abra a ação de exportação de um destino, defina From e To no horário local e inicie a exportação. As exportações históricas são executadas em lotes e informam o progresso separadamente da entrega contínua. Cada exportação aceita um intervalo de até 31 dias. No modo Metadata only, as exportações históricas incluem os campos principais: identificadores, tempos, status, operação, provedor, modelo e contagens de tokens. Motivos de término e parâmetros da solicitação estão disponíveis na exportação contínua e nas exportações históricas com Full content. Somente dados retidos podem ser exportados. Se o horário de início for anterior à retenção de traces da organização, a exportação começa pelos dados retidos mais antigos. Os provedores de destino podem restringir a idade dos spans aceitos ou exigir configuração adicional para ingestão histórica. Exportar traces não exclui dados do Toqan Router nem altera as configurações de retenção. Os jobs históricos usam a configuração de conexão capturada no momento em que entraram na fila. Desativar ou remover um destino interrompe as exportações pendentes dele. Depois de corrigir as configurações de conexão, inicie uma nova exportação para o intervalo necessário.

Status de entrega

As exportações podem ser concluídas com sucesso, falhar ou informar aceitação parcial. Aceitação parcial significa que o receptor rejeitou alguns spans. Uma resposta de sucesso do receptor confirma a aceitação naquele endpoint; ela não confirma que todos os spans podem ser pesquisados na interface do provedor. Um destino mostra Failing enquanto suas entregas mais recentes falham. Passe o cursor sobre o status para ver o motivo. O status é limpo após a próxima entrega bem-sucedida ou depois que o destino é salvo. Um destino é desativado automaticamente após 10 lotes de spans com falha em um minuto. Um lote conta como falho quando o receptor o rejeita ou quando as novas tentativas se esgotam, portanto uma interrupção curta não desativa um destino. Ele mostra Disabled, com o motivo ao passar o cursor. Novos spans não são exportados e os spans na fila são descartados até que a conexão seja corrigida e o destino seja ativado novamente. As entregas contínuas na fila usam as configurações de conexão atuais do destino; assim, corrigir um endpoint ou cabeçalho também se aplica aos spans que aguardam nova tentativa. As novas tentativas de entrega podem enviar um span mais de uma vez. Os identificadores de trace e span permanecem estáveis para que os receptores possam reconhecer duplicatas. Corrija erros de conexão ou de permissão antes de iniciar outra exportação.