> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Alerts > Configure alertas no Toqan Router para ser notificado quando o custo, a latência, os erros ou os resultados de guardrails de LLM ultrapassarem um limite, sem precisar acompanhar um dashboard. 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 Alerts** Os **Traces** registram o que aconteceu. Os **Alerts** avisam quando aconteceu, sem que ninguém precise olhar. Um **Alert** monitora uma métrica em um **Project**, em uma programação escolhida, e envia uma notificação no momento em que essa métrica ultrapassa um limite definido. Uma segunda notificação é enviada quando a métrica se recupera. A coluna **Recent runs** exibe o histórico de avaliações de cada alerta como uma faixa de barras, mostrando rapidamente se ele vem sendo avaliado sem problemas ou se está violando o limite. ## **O que os Alerts podem monitorar** Cada **Alert** monitora uma única métrica. Em geral, os alertas se enquadram em quatro categorias: > [card] Custo suspeito > > Identifique picos de gastos antes da fatura. Um loop de novas tentativas > descontrolado, um prompt que cresceu ou a troca por um modelo mais caro > aparecem em poucos minutos. > [card] Latência incomum > > Monitore a latência média ou p95. A degradação de provedores e chamadas > lentas de ferramentas aparecem aqui muito antes de serem registradas como erros. > [card] Resultados de guardrails > > Monitore a taxa de aprovação ou a pontuação média dos guardrails. Uma queda > significa que o modelo começou a produzir saídas rejeitadas pelas > verificações, o primeiro sinal disponível de que a qualidade piorou. > [card] Erros > > Monitore a contagem de solicitações com falha ou a taxa de erros, com > escopo em um provedor, modelo ou **Deployment**. > [!NOTE] > > As execuções de **Experiment** são excluídas dos cálculos de alertas, portanto > os dados de experimentos não contribuem para os limites dos alertas. O menu suspenso **Metric** agrupa todas as métricas em **Usage** ou **Guardrails**: | Grupo de métricas | Métricas | | - | - | | **Usage** | `LLM cost`, `Error rate`, `Errors`, `Latency (avg)`, `Latency p50`, `Latency p95`, `Latency p99`, `Requests`, `Tokens`, `Time to first token (avg)`, `Time to first token p50`, `Time to first token p95`, `Time to first token runs` | | **Guardrails** | `Guardrail error rate`, `Guardrail errors`, `Guardrail failure rate`, `Guardrail pass rate`, `Guardrail runs`, `Guardrail score (avg)`, `Guardrail block rate`, `Guardrail runs (rules)`, `Guardrails triggered` | ## **Criar um Alert** > [tab] AI Studio > > **1. Abra Alerts** > > Abra **Alerts** na seção **Observability** da barra lateral e escolha **+ Alert**. > > **2. Dê um nome ao alerta** > > Insira um **Name** que descreva o problema, e não a métrica. `High spend on production` é mais claro do que `cost alert`. Os nomes devem ser únicos dentro do workspace. > > Adicione uma **Description** opcional e confirme o **Project**. Um **Alert** pertence a exatamente um **Project**, e o **Project** não pode ser alterado após a criação. > > **3. Escolha uma métrica** > > Escolha uma **Metric** no menu suspenso, agrupada em **Usage** e **Guardrails**. O padrão é `LLM cost`, e o `signal` armazenado é derivado da métrica. > > Uma métrica de **Guardrails** adiciona um seletor de guardrails abaixo do menu suspenso. Deixá-lo vazio abrange todos os guardrails do **Project**. Selecionar **Guardrails** específicos limita o alerta a eles. > > **4. Defina a condição** > > A condição é lida como uma única frase: acionar quando o valor estiver **\[comparador]** **\[limite]** nos últimos **\[janela]**, verificado **\[frequência]**. > > Consulte [Opções de condição](#condition-options) para ver o conjunto completo de valores e observe que os limites são inseridos na unidade de cada métrica. > > **5. Restrinja o escopo com filtros** > > Sem filtros, o **Alert** avalia a métrica em todo o **Project**. Os filtros o restringem a um recorte específico. Esta etapa é opcional. Consulte [Filtros](#filters). > > **6. Escolha para onde notificar** > > Em **Notify via**, selecione um ou mais **Notifiers**, até 10 por **Alert**. **Notifiers** são destinos reutilizáveis para e-mail, Slack ou webhooks genéricos, gerenciados em **Settings** > **Notifiers**. Consulte [Notifiers](/docs/pt-BR/ai-studio/observability/notifiers.md) para ver os canais e seus campos, ou crie um diretamente no formulário. > > Os **Notifiers** são opcionais. Um **Alert** sem nenhum continua avaliando e registrando seus acionamentos, mas não notifica ninguém. > > **7. Confira a pré-visualização e salve** > > O painel à direita plota a métrica em 1h, 4h, 1d ou 7d junto com a consulta resolvida e a configuração armazenada. **Results** se divide em **Overview**, **Query** e **Config**: **Overview** mostra **Status**, **Next run** e **Type**, e **Config** repete **Threshold**, **Range**, **Frequency**, **Delay** e **Notifiers**. **Delay** aparece como **30 seconds** na pré-visualização. Use-a para conferir o limite com tráfego real antes de confirmar. Um limite que nunca foi ultrapassado é tão inútil quanto um que dispara o tempo todo. > > Escolha **Create Alert**. Novos **Alerts** são habilitados imediatamente. > [tab] API / SDK > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > curl --location 'https://router.toqan.ai/eu/v2/alerts' \ > --header "Authorization: Bearer $TOQAN_API_KEY" \ > --header 'Content-Type: application/json' \ > --data-raw '{ > "display_name": "High spend on production", > "description": "LLM cost above $30 in any 15 minute window", > "project_id": "01JQ8Z0MB5W1YTVN3GCK7B0EXA", > "signal": "cost", > "query": { > "metric": "genai.cost", > "filters": [] > }, > "condition": { > "comparator": "gt", > "threshold": 30, > "window": "15m", > "interval": "5m" > }, > "notifier_ids": ["01JQ8Z1TF7QK9D2RH4NMV6PY3C"] > }' > ``` > > > [!NOTE] > > > > O formulário deriva o `signal` da **Metric** escolhida, e o campo é opcional na criação. Ao defini-lo pela API, use estes valores: > > > > | Predefinição | Valor de `signal` na API | > > | - | - | > > | Cost | `cost` | > > | Latency | `latency` | > > | Errors | `errors` | > > | Guardrails | `evals` | > > | Métrica que não corresponde a nenhuma predefinição | `custom` | > > As rotas de alertas têm escopo de **Project**, portanto uma chave de API de **Project** é suficiente. > > A API aceita dois campos opcionais de `condition` que o formulário não expõe: > > * `degraded_threshold`: abre um acionamento com severidade `degraded` antes que o limite crítico seja atingido. Ele deve ficar do lado de recuperação de `threshold`. > * `resolve_threshold`: histerese. O padrão é o nível configurado mais baixo, e ele deve ficar nesse nível ou além dele, do lado de recuperação. Use-o para evitar que um alerta fique oscilando quando uma métrica gira em torno do limite. > > Nenhum dos dois campos é aceito quando `comparator` é `eq`. > > > [!NOTE] > > > > Consulte a [Referência da API](/docs/pt-BR/reference/alerts/create-an-alert.md) para ver a especificação completa dos parâmetros. ## **Opções de condição** | Configuração | Valores | | - | - | | **Trigger when value is** | `above` (`gt`), `at or above` (`gte`), `below` (`lt`), `at or below` (`lte`), `exactly` (`eq`) | | **Over the last** | `5 minutes`, `15 minutes`, `30 minutes`, `1 hour`, `4 hours`, `1 day` | | **Check frequency** | `Every 5 minutes`, `Every 15 minutes`, `Every hour`, `Every day` | Os limites são inseridos na unidade de cada métrica: | Tipo de métrica | Unidade | Exemplo | | - | - | - | | Custo | Dólares americanos | `30` significa US\$ 30 | | Latência | Milissegundos | `2000` significa 2 segundos | | Taxa de aprovação, taxa de erros | Porcentagem | `95` significa 95% | > [!TIP] > > **Guardrail pass rate** e **Guardrail score (avg)** são os casos que pedem um comparador **below**: o problema é a queda. A taxa de erros pede **above**. ## **Filtros** No **AI Studio**, os filtros usam os operadores `is` e `is not` nos seguintes campos: **provider**, **model**, **identity**, **agent**, **deployment**, **evaluator**, **evaluator name** A API aceita os operadores `eq`, `neq`, `in` e `not_in` nos filtros de alertas; consulte a [referência de criação de alertas](/docs/pt-BR/reference/alerts/create-an-alert.md). Cada grupo de filtros usa um único campo e um único operador. Um **Alert** pode ter até 18 filtros, ou 16 em `genai.evaluator.score.avg`. ## **Ciclo de vida do Alert** Um **Alert** é executado na frequência de verificação definida e assume um de três status: | Status | Significado | | - | - | | `ok` | A última avaliação não ultrapassou o limite | | `degraded` | O valor ultrapassou o nível de aviso definido por `degraded_threshold` (somente API) | | `triggered` | O valor ultrapassou o limite | Uma violação abre um **trigger**, um registro de incidente que permanece aberto até a métrica se recuperar e então é fechado como `resolved`. Se a métrica parar de ser reportada por completo, o trigger é resolvido automaticamente depois que uma janela de avaliação completa mais o atraso de ingestão passam sem dados, e a próxima violação abre um novo incidente. Isso é importante para métricas que só são reportadas enquanto algo está em execução, como os **Evaluators**. As notificações são enviadas duas vezes por incidente: uma quando o trigger é aberto e outra quando ele é resolvido. Não há intervalo de notificação repetida, portanto um incidente prolongado não vai lotar uma caixa de entrada. Cada trigger mantém suas evidências, incluindo o valor avaliado, o limite ultrapassado e as execuções que levaram até ali, o que permite ir de uma notificação até os **Traces** que a causaram. ## **Gerenciar Alerts** > [tab] AI Studio > > Na lista de **Alerts**: > > * **Habilite ou desabilite** um **Alert**. Um **Alert** desabilitado deixa de ser avaliado, mas mantém seu histórico de triggers. > * **Duplique** um **Alert** como ponto de partida para uma variante. As cópias são criadas desabilitadas, o que permite ajustar o limite antes que ele dispare. > * **Edite** qualquer campo, exceto o **Project**. > * **Exclua** um **Alert** junto com seu histórico. > > Filtre a lista por status, estado de habilitação e tipo. Atualmente, alertas de limite são o único tipo. > [tab] API / SDK > > | Operação | Endpoint | Método do SDK | > | - | - | - | > | Criar um alerta | `POST /v2/alerts` | `alerts.create` | > | Listar alertas | `GET /v2/alerts` | `alerts.list` | > | Obter um alerta | `GET /v2/alerts/{alert_id}` | `alerts.get` | > | Atualizar um alerta | `PATCH /v2/alerts/{alert_id}` | `alerts.update` | > | Excluir um alerta | `DELETE /v2/alerts/{alert_id}` | `alerts.delete` | > | Listar triggers | `GET /v2/alerts/{alert_id}/triggers` | `alerts.listTriggers` | > | Listar eventos de triggers | `GET /v2/alerts/{alert_id}/triggers/{trigger_id}/events` | `alerts.listTriggerEvents` | > > Os endpoints de listagem são paginados com `limit` (de 1 a 200, padrão 25) e os cursores `starting_after` e `ending_before`. `GET /v2/alerts` também aceita `project_id`. > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > curl --location 'https://router.toqan.ai/eu/v2/alerts/01JQ8Z2K4M6P8R0T2V4X6Z8B0D' \ > --request PATCH \ > --header "Authorization: Bearer $TOQAN_API_KEY" \ > --header 'Content-Type: application/json' \ > --data-raw '{"enabled": false}' > ``` ## **Limites do plano** O número de **Alerts** e a frequência mínima de verificação dependem do plano ativo: | Plano | Máximo de alertas | Frequência de verificação mais rápida | | - | - | - | | Free (Pay as you go sem forma de pagamento cadastrada) | 2 | A cada hora | | Pay as you go | 10 | A cada 5 minutos | | Enterprise | 20 | A cada 5 minutos | Salvar um **Alert** com uma frequência abaixo do mínimo do plano retorna `evaluation interval 5m is below your plan's minimum of 1h0m0s`. ## **Próximos passos** > [card] [Traces](/docs/pt-BR/ai-studio/observability/traces.md) > > Investigue as solicitações por trás de um trigger. > [card] [Automations](/docs/pt-BR/ai-studio/observability/automations.md) > > Aja automaticamente sobre os traces correspondentes em vez de apenas notificar. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.