Rastreamento de aplicações e análises para solicitações de IA

Casos de uso

Atribuir custos de tokens e latência a funcionalidades ou serviços específicos.
Monitorar quais ferramentas internas ou produtos geram mais uso de LLMs.
Filtrar dashboards de observabilidade por aplicação para depuração ou faturamento.
Aplicar orçamentos separados por linha de produto ou equipe.

Para conhecer todas as formas de anexar contexto a uma solicitação, incluindo identidade, threads e metadados personalizados, consulte Metadados da solicitação. O App Tracking associa cada solicitação ao AI Gateway a uma aplicação por meio do parâmetro name, para que custos, latência, contagem de tokens e taxas de erro sejam segmentados por produto ou serviço. O nome aparece em cada trace e filtra os dashboards de Monitors por aplicação.

Início rápido

Dê nomes às suas solicitações para rastrear o uso por aplicação ou serviço.

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Write a professional email",
    "name": "EmailAssistant-Production"
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Write a professional email",
  name: "EmailAssistant-Production",
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Write a professional email",
    extra_body={"name": "EmailAssistant-Production"},
)

print(response.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [{ role: "user", content: "Write a professional email" }],
  name: "EmailAssistant-Production",
});

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[{"role": "user", "content": "Write a professional email"}],
    extra_body={"name": "EmailAssistant-Production"},
)

Configuração

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Não	O nome a ser exibido no trace. Se não for especificado, será usado o nome padrão do sistema.

Para fins de retrocompatibilidade, orq.name também é aceito, mas está obsoleto. Use name no nível superior em novas implementações.

Comportamento padrão: se nenhum nome for informado, o sistema usa o identificador padrão.

Convenções de nomenclatura

Padrões recomendados

// Service-Environment
"UserAPI-Production";
"ChatBot-Development";

// Team-Service-Feature
"Platform-Auth-OAuth";
"ML-Recommendations-v2";

// Application-Version
"MobileApp-v3-1";
"WebPortal-v2-0";

Boas práticas

Use padrões consistentes em toda a equipe.
Inclua o ambiente (dev/staging/prod).
Evite timestamps ou valores dinâmicos.
Mantenha os nomes com menos de 50 caracteres.
Use apenas caracteres alfanuméricos e hífens.

Casos de uso

Cenário	Estratégia de nomenclatura	Exemplo
Microsserviços	Nomenclatura por serviço	`user-service`, `payment-api`
Multi-tenant	Identificação do tenant	`tenant-123`, `enterprise-client`
Testes A/B	Rastreamento de variantes	`experiment-A`, `control-group`
Feature flags	Identificação de funcionalidades	`new-ui-beta`, `legacy-flow`

Exemplos de código

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Help me write a professional email to follow up on a job interview",
    "name": "ContentGenerator-BlogPosts"
  }'

curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": "Help me write a professional email to follow up on a job interview"
      }
    ],
    "name": "ContentGenerator-BlogPosts"
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Help me write a professional email to follow up on a job interview",
  name: "ContentGenerator-BlogPosts",
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Help me write a professional email to follow up on a job interview",
    extra_body={"name": "ContentGenerator-BlogPosts"},
)

print(response.output_text)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [
    {
      role: "user",
      content: "Help me write a professional email to follow up on a job interview",
    },
  ],
  name: "ContentGenerator-BlogPosts",
});

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[
        {
            "role": "user",
            "content": "Help me write a professional email to follow up on a job interview",
        }
    ],
    extra_body={"name": "ContentGenerator-BlogPosts"},
)

Gerenciamento de ambientes

Configuração por ambiente

const getTrackingName = (service, environment) => {
  return `${service}-${environment}`;
};

// Usage
const trackingConfig = {
  name: getTrackingName("ChatBot", process.env.NODE_ENV),
  // Results in: "ChatBot-development", "ChatBot-production"
};

Exemplos específicos por ambiente

// Development
name: "UserAPI-Dev"

// Staging
name: "UserAPI-Staging"

// Production
name: "UserAPI-Prod"

Uso

Filtragem por aplicação

Visualize solicitações por aplicação/serviço específico.
Compare o desempenho entre aplicações.
Acompanhe os custos por aplicação.
Monitore as taxas de erro por serviço.

Métricas disponíveis

As seguintes métricas estão disponíveis para o Rastreamento de Aplicações:

Volume de solicitações por aplicação.
Tempos de resposta por serviço.
Alocação de custos por projeto.
Padrões de erro por ambiente.

Padrões avançados

Nomenclatura dinâmica

const generateTrackingName = (userId, feature) => {
  // For multi-tenant scenarios
  return `tenant-${userId}-${feature}`;
};

// Usage
name: generateTrackingName(user.id, "chat-assistant")

Integração com feature flags

const getFeatureName = (featureFlags) => {
  const activeFeatures = Object.keys(featureFlags)
    .filter((key) => featureFlags[key])
    .join("-");

  return `app-${activeFeatures}`;
};

Rastreamento de versões

// Package.json version (replace dots with hyphens)
const packageVersion = require("./package.json").version.replace(/\./g, "-");

name: `MyApp-v${packageVersion}`

Solução de problemas

Nomes não aparecem no dashboard

Verifique se o nome segue o padrão alfanumérico + hífens.
Confirme se as solicitações estão sendo enviadas com sucesso.
Garanta que o nome esteja dentro do limite de caracteres (50 caracteres).

Dados de rastreamento fragmentados

Padronize as convenções de nomenclatura em toda a equipe.
Use variáveis de ambiente para manter a consistência.
Implemente uma função de nomenclatura centralizada.

Nomes únicos em excesso

Evite timestamps ou valores aleatórios.
Limite a cerca de 50 nomes únicos por conta.
Use nomenclatura hierárquica em vez de uma estrutura plana.

Monitoramento

As seguintes métricas estão disponíveis para monitoramento.

const appMetrics = {
  requestsByApp: {}, // Volume per application
  costsByApp: {}, // Spending per application
  latencyByApp: {}, // Performance per application
  errorsByApp: {}, // Error rates per application
  activeApps: new Set(), // Unique applications
};

Consultas analíticas

As seguintes perguntas podem ser respondidas com as métricas acima.

Quais aplicações mais usam IA?
Qual é o custo por aplicação?
Quais serviços têm as maiores taxas de erro?
Como o desempenho varia entre aplicações?

Boas práticas

Padrões de nomenclatura

Documente as convenções de nomenclatura para sua equipe.
Use separadores consistentes (hífens são recomendados).
Inclua o ambiente no nome para maior clareza.
Evite caracteres especiais ou espaços.

Exemplo de implementação

// Centralized tracking configuration
class ToqanConfig {
  static getName(service, environment = process.env.NODE_ENV) {
    return `${service}-${environment}`;
  }

  static getConfig(service) {
    return {
      name: this.getName(service),
    };
  }
}

// Usage
const toqanConfig = ToqanConfig.getConfig("ChatBot");

Para garantir que as equipes de uma organização de engenharia estejam alinhadas quanto aos princípios do Rastreamento de Aplicações:

Mantenha uma lista de nomes de aplicações aprovados.
Use revisões de código para garantir os padrões de nomenclatura.
Configure alertas de monitoramento para nomes novos/inesperados.
Faça limpezas regulares de nomes de rastreamento não utilizados.

Limitações

Restrições de nome: apenas caracteres alfanuméricos e hífens.
Limites de tamanho: máximo de 50 caracteres por nome.
Impacto no armazenamento: muitos nomes únicos aumentam o armazenamento de metadados.
Desempenho das consultas: um grande número de nomes únicos pode tornar a filtragem mais lenta.
Sem alterações retroativas: traces históricos mantêm os nomes originais.

Exemplos de integração

Com sistemas de monitoramento externos

const prometheus = {
  histogram: (name: string, value: number, labels: Record<string, string>) => {},
  counter: (name: string, value: number, labels: Record<string, string>) => {},
}; // replace with your Prometheus client, e.g. from prom-client

// Export metrics by application
const exportMetrics = (trackingName: string, responseTime: number, cost: number) => {
  prometheus.histogram("ai_request_duration", responseTime, {
    app: trackingName,
  });
  prometheus.counter("ai_request_cost", cost, { app: trackingName });
};

Com logging

logger.info("AI request completed", {
  trackingName: "ChatBot-Prod",
  responseTime: 1250,
  model: "gpt-5.6-sol",
  success: true,
});

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

Rastreamento de aplicações e análises para solicitações de IA

Início rápido

Configuração

Convenções de nomenclatura

Padrões recomendados

Boas práticas

Casos de uso

Exemplos de código

Gerenciamento de ambientes

Configuração por ambiente

Exemplos específicos por ambiente

Uso

Filtragem por aplicação

Métricas disponíveis

Padrões avançados

Nomenclatura dinâmica

Integração com feature flags

Rastreamento de versões

Solução de problemas

Monitoramento

Consultas analíticas

Boas práticas

Padrões de nomenclatura

Exemplo de implementação

Limitações

Exemplos de integração

Com sistemas de monitoramento externos

Com logging

​Início rápido

​Configuração

​Convenções de nomenclatura

​Padrões recomendados

​Boas práticas

​Casos de uso

​Exemplos de código

​Gerenciamento de ambientes

​Configuração por ambiente

​Exemplos específicos por ambiente

​Uso

​Filtragem por aplicação

​Métricas disponíveis

​Padrões avançados

​Nomenclatura dinâmica

​Integração com feature flags

​Rastreamento de versões

​Solução de problemas

​Monitoramento

​Consultas analíticas

​Boas práticas

​Padrões de nomenclatura

​Exemplo de implementação

​Limitações

​Exemplos de integração

​Com sistemas de monitoramento externos

​Com logging

Início rápido

Configuração

Convenções de nomenclatura

Padrões recomendados

Boas práticas

Casos de uso

Exemplos de código

Gerenciamento de ambientes

Configuração por ambiente

Exemplos específicos por ambiente

Uso

Filtragem por aplicação

Métricas disponíveis

Padrões avançados

Nomenclatura dinâmica

Integração com feature flags

Rastreamento de versões

Solução de problemas

Monitoramento

Consultas analíticas

Boas práticas

Padrões de nomenclatura

Exemplo de implementação

Limitações

Exemplos de integração

Com sistemas de monitoramento externos

Com logging