> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Marque as solicitações ao AI Gateway com um nome de aplicação para segmentar as análises do Toqan Router por aplicação, incluindo custos, latência, erros e contagem de tokens por produto ou serviço.

**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](/docs/pt-BR/ai-gateway/request-metadata.md).

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**](/docs/pt-BR/ai-studio/observability/monitors.md) por aplicação.

***

## Início rápido

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

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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",
});
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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. |

> [!NOTE]
>
> 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

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 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

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
  }'
```

```bash cURL (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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",
});
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 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

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const generateTrackingName = (userId, feature) => {
  // For multi-tenant scenarios
  return `tenant-${userId}-${feature}`;
};

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

### Integração com feature flags

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const getFeatureName = (featureFlags) => {
  const activeFeatures = Object.keys(featureFlags)
    .filter((key) => featureFlags[key])
    .join("-");

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

### Rastreamento de versões

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 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.

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 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

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
logger.info("AI request completed", {
  trackingName: "ChatBot-Prod",
  responseTime: 1250,
  model: "gpt-5.6-sol",
  success: true,
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.