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

# Grafana Alerting

> Conecte o Grafana Alerting ao aciona.me com um contact point do tipo webhook.

## Visão geral

O Grafana envia os alertas para o aciona.me por um **contact point do tipo webhook**. Cada item de `alerts[]` do payload vira um alerta no aciona.me, e itens resolvidos fecham automaticamente o acionamento correspondente.

|                    |                          |
| ------------------ | ------------------------ |
| **Tipo de fonte**  | `Grafana`                |
| **Mecanismo**      | Contact point webhook    |
| **Correlação**     | `fingerprint` do Grafana |
| **Auto-resolução** | ✅                        |

## Pré-requisitos

* Grafana com Grafana Alerting habilitado e permissão para criar contact points.
* Um serviço criado no aciona.me e vinculado a um time com escala ativa.

## 1. Crie a fonte de alerta no aciona.me

Em **Fontes de alerta**, crie uma fonte do tipo **Grafana** — por exemplo `Grafana - produção`.

## 2. Copie a URL e o token

```bash theme={null}
POST https://ingress.aciona.me/webhooks/<idDaFonte>
X-Aciona-Token: <tokenDaFonte>
```

<Warning>
  O token é exibido uma única vez. Copie agora.
</Warning>

## 3. Configure o contact point no Grafana

<Tabs>
  <Tab title="Pela interface">
    <Steps>
      <Step title="Alerting → Contact points → Add contact point">
        Nome: `aciona-me`. Integração: **Webhook**.
      </Step>

      <Step title="URL">
        `https://ingress.aciona.me/webhooks/<idDaFonte>`
      </Step>

      <Step title="HTTP Method">
        `POST`
      </Step>

      <Step title="Header de autenticação">
        Adicione o header `X-Aciona-Token` com o token da fonte. Em versões que expõem o campo como *Authorization Header*, use o nome `X-Aciona-Token` e o token como valor.
      </Step>

      <Step title="Disable resolved message">
        Deixe **desativado**. Este é o passo crítico da integração.
      </Step>

      <Step title="Salve e use o contact point">
        Aponte a notification policy (ou as regras de alerta) para o contact point `aciona-me`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Por provisioning (YAML)">
    ```yaml contact-points.yaml theme={null}
    contactPoints:
      - orgId: 1
        name: aciona-me
        receivers:
          - uid: aciona-me-webhook
            type: webhook
            settings:
              url: https://ingress.aciona.me/webhooks/<idDaFonte>
              httpMethod: POST
              disableResolveMessage: false
            secureSettings:
              authorizationHeaderValue: '<tokenDaFonte>'
    ```

    `disableResolveMessage: false` é o equivalente ao `send_resolved: true` do Alertmanager.
  </Tab>
</Tabs>

## 4. Envie um alerta de teste

Use **Test** no contact point do Grafana, ou force uma regra de alerta a disparar.

## 5. Confirme o acionamento

Em **Acionamentos**, o alerta deve aparecer em segundos, com título vindo do alerta do Grafana e severidade traduzida a partir da label `severity`.

## 6. Configure a resolução automática

<Warning>
  **"Disable resolved message" precisa permanecer desativado**, tanto no contact point quanto na notification policy. Com essa opção ativa, o Grafana não envia os itens `resolved` e o aciona.me não tem como fechar o acionamento — ele fica aberto indefinidamente.
</Warning>

Estados normalizados pelo aciona.me, item por item:

| `alerts[].status`              | Efeito no aciona.me                                  |
| ------------------------------ | ---------------------------------------------------- |
| `firing`                       | Cria ou agrega acionamento                           |
| `alerting`                     | Cria ou agrega acionamento                           |
| `resolved`                     | Resolve automaticamente o acionamento correlacionado |
| `normal`                       | Resolve automaticamente o acionamento correlacionado |
| `paused`, `pending`, `no_data` | Ignorado                                             |

A correlação usa o `fingerprint` do Grafana, com alternativas baseadas no identificador da regra. Esse identificador precisa permanecer estável entre o disparo e a recuperação.

## Roteamento para o serviço certo

Inclua uma label `service` nas suas regras de alerta com o nome exato do serviço no aciona.me:

```yaml theme={null}
labels:
  service: api-pagamentos
  severity: critical
```

## Solução de problemas

<AccordionGroup>
  <Accordion title="O acionamento abre, mas nunca fecha sozinho" icon="triangle-alert">
    "Disable resolved message" está ativo em algum ponto — contact point ou notification policy. Desative nos dois.
  </Accordion>

  <Accordion title="Resposta 401 no Grafana" icon="lock">
    O header `X-Aciona-Token` está ausente ou com valor errado. Se o token foi rotacionado, atualize o contact point.
  </Accordion>

  <Accordion title="O acionamento cai no serviço errado" icon="server">
    Adicione a label `service` na regra de alerta, com o nome exato do serviço no aciona.me. Sem ela, o roteamento usa outras pistas do payload.
  </Accordion>

  <Accordion title="Vários acionamentos para o mesmo problema" icon="copy">
    O `fingerprint` está mudando entre disparos — geralmente porque as labels da regra mudam. Estabilize as labels que compõem a identidade do alerta.
  </Accordion>
</AccordionGroup>

<Card title="Mais soluções" icon="life-buoy" href="/pt-br/solucao-de-problemas/visao-geral" horizontal />