### 1. Alertas de busca
Os alertas de busca permitem acionar notificações com base nos resultados de uma busca salva. Eles ajudam você a detectar quando eventos ou padrões específicos ocorrem com mais (ou menos) frequência do que o esperado.
Um alerta é acionado quando a contagem de resultados correspondentes dentro de uma janela de tempo definida excede ou fica abaixo de um limiar especificado.
Para criar um alerta de busca:
Para que um alerta seja criado para uma busca, ela precisa estar salva. Você pode criar o alerta para uma busca salva existente ou salvá-la durante o processo de criação do alerta. No exemplo abaixo, assumimos que a busca não está salva.
### 2. Alertas de gráficos no dashboard
Os alertas no dashboard também podem ser aplicados a gráficos.
Você pode criar um alerta baseado em gráfico diretamente em um dashboard salvo, com suporte a agregações SQL completas e funções do ClickHouse para cálculos avançados.
Quando uma métrica ultrapassa um limiar definido, um alerta é disparado automaticamente, permitindo monitorar KPIs, latências ou outras métricas importantes ao longo do tempo.
`. Consulte a [documentação do Slack](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/) para mais detalhes.
**Slack (API)**
* Token do bot do Slack. Consulte a [documentação do Slack](https://docs.slack.dev/authentication/tokens/#bot/) para mais detalhes.
**API do PagerDuty**
* Chave de integração do PagerDuty. Consulte a [documentação do PagerDuty](https://support.pagerduty.com/main/docs/api-access-keys) para mais detalhes.
**Genérico**
* URL do webhook
* cabeçalhos do webhook (opcional)
* corpo do webhook (opcional). No momento, o corpo oferece suporte às variáveis de modelo `{{title}}`, `{{body}}` e `{{link}}`.
## Gerenciando alertas
Os alertas podem ser gerenciados centralmente pelo painel de alertas no lado esquerdo do HyperDX.
Nesta visualização, você pode ver todos os alertas que foram criados e que estão ativos no momento no ClickStack.
Esta visualização também exibe o histórico de avaliação dos alertas. Os alertas são avaliados em um intervalo recorrente (definido pelo período/duração configurado durante a criação do alerta). Durante cada avaliação, o HyperDX consulta seus dados para verificar se a condição do alerta foi atendida:
* **Barra vermelha**: A condição de limiar foi atendida durante esta avaliação, e o alerta foi disparado (notificação enviada)
* **Barra verde**: O alerta foi avaliado, mas a condição de limiar não foi atendida (nenhuma notificação enviada)
Cada avaliação é independente — o alerta verifica os dados daquela janela de tempo e só é disparado se a condição for true naquele momento.
No exemplo acima, o primeiro alerta foi disparado em todas as avaliações, indicando um problema persistente. O segundo alerta mostra um problema resolvido: ele foi disparado duas vezes no início (barras vermelhas) e, nas avaliações seguintes, a condição de limiar deixou de ser atendida (barras verdes).
Clicar em um alerta leva você ao gráfico ou à Busca ao qual ele está associado.
### Excluindo um alerta
Para remover um alerta, abra a caixa de diálogo de edição da busca ou do gráfico associado e selecione **Remove Alert**.
No exemplo abaixo, o botão `Remove Alert` removerá o alerta do gráfico.
## Alertas de gráfico baseados em SQL
Os alertas de gráfico baseados em SQL permitem escrever ClickHouse SQL para definir condições de alerta. Isso dá a você controle total sobre filtragem, agregação e cálculos — qualquer coisa que possa ser expressa em SQL pode se tornar um alerta.
### Tipos de gráfico compatíveis
Alertas baseados em SQL são compatíveis com três tipos de exibição de gráfico:
| Tipo de gráfico | Comportamento |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Linha** | Alerta de série temporal. A consulta deve produzir linhas agregadas por intervalos de tempo. Cada bucket é avaliado de forma independente em relação ao limite. |
| **Barra empilhada** | Alerta de série temporal. Mesmo comportamento do gráfico de Linha. |
| **Número** | Alerta de valor único. A consulta retorna um único resultado numérico, que é comparado ao limite uma vez por avaliação. |
Outros tipos de gráfico baseados em SQL (Tabela, Pizza, Mapa de calor etc.) não oferecem suporte a alertas.
### Criando um alerta SQL
Para criar um alerta em um gráfico baseado em SQL:
#### Crie ou abra um gráfico baseado em SQL em um dashboard
Em um dashboard salvo, [crie um novo gráfico no modo de gráfico **SQL**](/pt-BR/clickstack/features/dashboards/sql-visualizations) ou abra para edição um gráfico baseado em SQL existente.
Escolha **linha**, **barra empilhada** ou **número** como tipo de visualização.
#### Adicione o alerta
Selecione **Add Alert** na seção de alerta do editor de gráfico. Configure:
* **Tipo de limiar**: `>=` (maior ou igual a), `>` (maior que), `<=` (menor ou igual a), `<` (menor que), `=` (igual a), `!=` (diferente de), `<= x >=` (entre) ou `> or <` (fora do intervalo)
* **Valor do limiar**: o valor numérico a ser comparado
* **Intervalo**: com que frequência o alerta é avaliado (1m, 5m, 15m, 30m, 1h, 6h, 12h ou 1d). Isso também define a janela de tempo de cada avaliação.
* **Webhook**: o canal de notificação usado quando o alerta é disparado. Consulte [Como adicionar um webhook](#add-webhook).
**Intervalo de tempo do alerta**
Normalmente, as consultas do alerta são executadas uma vez por intervalo. No entanto, se um ou mais intervalos forem ignorados devido a erros ou consultas lentas, a execução seguinte usará um intervalo de tempo que inclui os intervalos perdidos. Nesse caso, os parâmetros de intervalo da consulta ainda seriam definidos com o período configurado do alerta, mas os parâmetros de intervalo de tempo refletiriam o período mais longo.
#### Salve o dashboard
Salve o dashboard para ativar o alerta. O alerta começará a ser avaliado no intervalo configurado.
### Como os resultados da consulta são interpretados
O sistema de alertas inspeciona as colunas retornadas pela sua consulta SQL para determinar o que deve ser comparado ao limiar.
* **Coluna de valor**: a **última coluna numérica** na sua cláusula `SELECT` é usada como valor do alerta. Se a sua consulta retornar várias colunas numéricas (por exemplo, `count, avg_latency, p99_latency`), apenas a última (`p99_latency`) será comparada ao limiar.
* **Coluna de timestamp**: para gráficos de séries temporais (linha e barra empilhada), o sistema identifica a coluna Date/DateTime nos resultados como o bucket de tempo (ou seja, o eixo x em um gráfico de séries temporais). A coluna de valor de cada bucket de tempo é avaliada em relação ao limiar de forma independente e, se o valor de qualquer bucket de tempo ultrapassar o limiar configurado, o alerta será disparado.
* **Colunas de agrupamento**: quaisquer colunas que não sejam numéricas nem de timestamp (por exemplo, `ServiceName`, `Environment`) são tratadas como dimensões de agrupamento. Quando há grupos, cada combinação única de valores de grupo é monitorada e gera alertas separadamente. O ClickStack enviará um alerta para cada grupo cujo valor ultrapassar o limiar configurado. Os grupos estão disponíveis apenas para gráficos de séries temporais.
### Parâmetros de consulta e macros
As consultas SQL de alerta oferecem suporte a parâmetros de template e macros que são substituídos automaticamente durante a avaliação. Esses são os mesmos parâmetros e macros disponíveis ao [criar um gráfico com base em SQL](/pt-BR/clickstack/features/dashboards/sql-visualizations).
#### Parâmetros obrigatórios e recomendados
Consultas usadas em alertas de gráficos de linha ou de barras empilhadas **devem** incluir um parâmetro ou macro de intervalo (`{intervalSeconds:Int64}`, `{intervalMilliseconds:Int64}`, `$__timeInterval(col)` ou `$__timeInterval_ms(col)`). Durante a execução do alerta, ele será substituído pelo período configurado do alerta.
Consultas usadas para alertas **devem** incluir um filtro de intervalo de tempo (`{startDateMilliseconds:Int64}` e `{endDateMilliseconds:Int64}`, ou `$__timeFilter(col)`, etc.). Independentemente de a consulta ter ou não um filtro de intervalo de tempo, a consulta do alerta será executada com base no período configurado do alerta. Se não houver filtro de intervalo de tempo, a consulta lerá todo o intervalo de tempo disponível na tabela de origem em cada execução.
**Intervalo de tempo do alerta**
Normalmente, as consultas de alerta são executadas uma vez por intervalo. No entanto, se um ou mais intervalos forem ignorados devido a erros ou a consultas lentas, a execução seguinte usará um intervalo de tempo que inclui os intervalos perdidos. Nesse caso, os parâmetros de intervalo da consulta ainda seriam definidos como o período configurado do alerta, mas os parâmetros de intervalo de tempo refletiriam esse intervalo mais longo.
### Exemplos de consultas para alertas
#### Taxa de erro por serviço (série temporal)
Gere um alerta quando qualquer serviço tiver uma taxa de erro acima de 5%, com pelo menos 10 requisições no período do alerta, para evitar alertas ruidosos em serviços com baixo tráfego.
```sql theme={null}
WITH error_rates AS (
SELECT
$__timeInterval(Timestamp) as ts,
ServiceName,
countIf (SpanKind = 'Server') as request_count,
countIf (
SpanKind = 'Server'
and StatusCode = 'Error'
) as error_count,
error_count / request_count * 100 AS error_percent
FROM $__sourceTable
WHERE $__timeFilter(Timestamp)
GROUP BY ts, ServiceName
)
SELECT ts, ServiceName, error_percent
FROM error_rates
WHERE request_count > 10
```
**Tipo de exibição**: Linha ou barras empilhadas
**Limiar**: `>= 5` (dispara quando a taxa de erro atinge 5%)
Nesta consulta, `ServiceName` é uma coluna não numérica e que não é de timestamp, então cada serviço é tratado como um grupo de alerta separado. O alerta é disparado de forma independente para cada serviço.
#### Detecção de anomalias com média defasada (séries temporais)
Alerta para contagens excessivas de erros que ultrapassam uma média móvel em mais de dois desvios padrão. Isso detecta picos em relação ao comportamento de referência recente, em vez de um limite fixo.
```sql theme={null}
WITH buckets AS (
SELECT
$__timeInterval(Timestamp) AS ts,
count() AS bucket_count
FROM $__sourceTable
WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
- toIntervalSecond($__interval_s * 30) -- Buscar 30 intervalos anteriores
AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
AND SeverityText = 'error'
GROUP BY ts
ORDER BY ts
WITH FILL
FROM toDateTime(fromUnixTimestamp64Milli({startDateMilliseconds:Int64}))
TO toDateTime(fromUnixTimestamp64Milli({endDateMilliseconds:Int64}))
STEP toIntervalSecond($__interval_s)
),
anomaly_detection AS (
SELECT
ts,
bucket_count,
avg(bucket_count) OVER (
ORDER BY ts ROWS BETWEEN 30 PRECEDING AND 1 PRECEDING
) AS previous_30_avg,
stddevPop(bucket_count) OVER (
ORDER BY ts ROWS BETWEEN 30 PRECEDING AND 1 PRECEDING
) AS previous_30_stddev,
greatest(
bucket_count - (previous_30_avg + 2 * previous_30_stddev), 0
) AS excess_error_count
FROM buckets
)
SELECT ts, excess_error_count
FROM anomaly_detection
WHERE ts >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
AND ts < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
```
**Tipo de exibição**: Linha
**Limiar**: `> 0` (dispara quando são detectados erros em excesso acima da linha de base móvel)
Observe que a consulta recupera 30 intervalos *antes* do início do intervalo de datas para alimentar os cálculos da janela móvel e, em seguida, filtra a saída final para manter apenas a janela de avaliação.
## Cenários comuns de alertas
Aqui estão alguns cenários comuns de alertas para os quais você pode usar o HyperDX:
**Erros:** Recomendamos configurar alertas para as buscas salvas padrão
`All Error Events` e `HTTP Status >= 400` para ser notificado quando
houver um excesso de erros.
**Operações lentas:** Você pode configurar uma busca para operações lentas (por exemplo,
`duration:>5000`) e depois criar um alerta quando houver operações lentas
demais.
**Eventos de usuário:** Você também pode configurar alertas para que equipes que lidam com clientes sejam
notificadas quando novos usuários se cadastrarem ou quando uma ação crítica do usuário for realizada.