Incidentes para políticas de alertas baseadas em SQL

Um incidente é um registro de quando a condição de uma política de alertas é atendida. Normalmente, o Cloud Monitoring abre um incidente e envia uma notificação quando a condição da política de alertas é atendida. No entanto, os incidentes não são criados nas seguintes circunstâncias:

  • A política está adiada ou desativada.
  • O número de políticas de alertas ou incidentes excede os limites de alertas.

Para cada incidente, o Monitoring cria uma página de Detalhes do incidente que permite gerenciar o incidente e informa dados que podem ajudar a resolver a falha. Por exemplo, a página Detalhes do incidente mostra listas de resumos de resultados de consulta SQL e incidentes relacionados.

Este documento descreve como encontrar seus incidentes. Também descreve como usar a página Detalhes do incidente para gerenciar incidentes de políticas de alerta baseadas em SQL, que avaliam os resultados de uma consulta SQL executada em dados de grupos de entradas de registro.

Esse recurso só é compatível com projetos Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.

Antes de começar

Para receber as permissões necessárias para visualizar e gerenciar incidentes, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para mais informações sobre os papéis do Cloud Monitoring, consulte Controlar o acesso com o Identity and Access Management.

Visualizar incidentes

Para ver os incidentes no seu projeto, use o console do Google Cloud , a CLI gcloud (prévia pública) ou a API Monitoring (prévia pública).

Console do Google Cloud

Para listar os incidentes no seu projeto Google Cloud , faça o seguinte:

  1. No console do Google Cloud , acesse a página  Alertas:

    Acessar Alertas

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

  2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.

    A página Alertas mostra informações sobre suas políticas de alertas, adiamentos e incidentes:

    • O painel Resumo lista o número de incidentes abertos.
    • A tabela Incidentes mostra os incidentes abertos mais recentes. Para listar os incidentes mais recentes na tabela, incluindo aqueles que foram fechados, clique em Mostrar incidentes fechados.

  3. Para conferir os detalhes de um incidente específico, selecione-o na lista.

    A página Detalhes do incidente é aberta. Para mais informações sobre a página Detalhes do incidente, consulte a seção Investigar um incidente deste documento.

Encontrar incidentes mais antigos

A tabela Incidentes na página Alertas mostra os incidentes abertos mais recentes. Para ver incidentes mais antigos, faça o seguinte:

  • Para percorrer as entradas na tabela Incidentes, clique em  Mais recentes ou em  Mais antigos.

  • Para abrir uma página que permite listar e filtrar seus incidentes, clique em Ver todos os incidentes. A página Incidentes é aberta. Nessa página, faça o seguinte:

    • Mostrar todos os incidentes, incluindo os encerrados. Para mostrar todos os incidentes, clique em Mostrar incidentes fechados.
    • Filtre incidentes. Para mais informações sobre como adicionar filtros, consulte Filtrar incidentes.
    • Confirme ou feche um incidente ou adie a política de alertas dele. Para acessar essas opções, clique em  Mais opções na linha do incidente e faça uma seleção no menu. Para mais informações, consulte Gerenciar incidentes.

Filtrar incidentes

Para restringir os incidentes mostrados na tabela, adicione filtros. Se você adicionar vários filtros, a tabela vai mostrar apenas os incidentes que atendem a todos eles.

Para filtrar a tabela de incidentes, faça o seguinte:

  1. Na página Incidentes, clique em  Filtrar tabela e selecione uma propriedade de filtro. As propriedades do filtro incluem:

    • Estado do incidente
    • Nome da política de alertas
    • quando o incidente foi aberto ou fechado;

  2. Selecione um valor no menu secundário ou digite um valor na barra de filtro.

    A tabela Incidentes lista o filtro.

gcloud

Use a gcloud para receber e listar incidentes.

Receber incidente

Antes de usar os dados do comando abaixo, faça estas substituições:

  • ALERT_NAME: o nome do recurso do alerta. Por exemplo, projects/my-project/alerts/my-alert-id.

Execute o comando gcloud alpha monitoring alerts describe:

Linux, macOS ou Cloud Shell

gcloud alpha monitoring alerts describe ALERT_NAME

Windows (PowerShell)

gcloud alpha monitoring alerts describe ALERT_NAME

Windows (cmd.exe)

gcloud alpha monitoring alerts describe ALERT_NAME
 O comando retorna uma resposta com detalhes do alerta, como estado do alerta, rótulos anexados e a política de alertas de origem. Os rótulos na resposta estão sujeitos a mudanças enquanto esse recurso estiver em pré-lançamento. A resposta será semelhante a esta: 
{
  "name": "projects/my-project/alerts/my-alert-id",
  "state": "OPEN",
  "open_time": "2025-06-11T09:53:46Z",
  "resource": {
    "type": "sql_alert"
  },
  "policy": {
    "name": "projects/my-project/alertPolicies/POLICY_1",
    "displayName": "test-policy"
  },
  "summaryText": "The row count SQL Condition for \"test-policy\" is above the threshold of 1."
}

Listar incidentes

É possível listar incidentes no seu projeto e filtrar os resultados usando a CLI gcloud.

Antes de usar os dados do comando abaixo, faça estas substituições:

  • PROJECT_ID: o identificador do projeto.

Execute o comando gcloud alpha monitoring alerts list:

Linux, macOS ou Cloud Shell

gcloud alpha monitoring alerts list

Windows (PowerShell)

gcloud alpha monitoring alerts list

Windows (cmd.exe)

gcloud alpha monitoring alerts list
 O comando retorna uma resposta com detalhes do alerta, como estado do alerta, rótulos anexados e a política de alertas de origem. Os rótulos na resposta estão sujeitos a mudanças enquanto esse recurso estiver em pré-lançamento. A resposta será semelhante a esta: 
{
  "alerts": [
    {
      "name": "projects/my-project/alerts/my-alert-id",
      "state": "OPEN",
      "open_time": "2025-06-11T09:53:46Z",
      "resource": {
        "type": "sql_alert"
      },
      "policy": {
        "name": "projects/my-project/alertPolicies/POLICY_1",
        "displayName": "test-policy"
      },
      "summaryText": "The row count SQL Condition for \"test-policy\" is above the threshold of 1."
    }
  ]
}
Também é possível usar as seguintes flags opcionais para filtrar, classificar ou modificar a saída:

  • --filter: forneça uma expressão de filtro para filtrar alertas por tempo ou rótulo. Por exemplo, filtre por tempo com --filter='close_time>="2025-09-10T00:00:00Z"' ou por rótulo com --filter='resource.labels.key="value"'.

  • --sort-by: uma lista separada por vírgulas de campos para classificar a saída. Por exemplo, --sort-by=open_time.

  • --uri: o comando gera uma lista de URIs de recursos em vez da saída padrão.

  • --limit: defina essa flag como 2 ou um valor maior para limitar o número de alertas retornados. Não use essa flag com a flag --filter.

API Monitoring

Use a API Monitoring para receber e listar incidentes.

Receber incidente

Para receber detalhes sobre um único incidente com a API Monitoring, use o método alerts.get.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o identificador do projeto.
  • ALERT_ID: o ID do alerta.

Método HTTP e URL: 

GET https://monitoring.googleapis.com/v3/projects/PROJECT_ID/alerts/ALERT_ID

Para enviar a solicitação, expanda uma destas opções:

O comando retorna uma resposta com detalhes do alerta, como estado do alerta, rótulos anexados e a política de alertas de origem. Os rótulos na resposta estão sujeitos a mudanças enquanto esse recurso estiver em pré-lançamento. A resposta será semelhante a esta: 
{
  "name": "projects/my-project/alerts/my-alert-id",
  "state": "OPEN",
  "open_time": "2025-06-11T09:53:46Z",
  "resource": {
    "type": "sql_alert"
  },
  "policy": {
    "name": "projects/my-project/alertPolicies/POLICY_1",
    "displayName": "test-policy"
  },
  "summaryText": "The row count SQL Condition for \"test-policy\" is above the threshold of 1."
}

Listar incidentes

Para listar incidentes no seu projeto e filtrar os resultados com a API Monitoring, use o método alerts.list.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o identificador do projeto.

Método HTTP e URL: 

GET https://monitoring.googleapis.com/v3/projects/PROJECT_ID/alerts

Para enviar a solicitação, expanda uma destas opções:

O comando retorna uma resposta com detalhes do alerta, como estado do alerta, rótulos anexados e a política de alertas de origem. Os rótulos na resposta estão sujeitos a mudanças enquanto esse recurso estiver em pré-lançamento. A resposta será semelhante a esta: 
{
  "alerts": [
    {
      "name": "projects/my-project/alerts/my-alert-id",
      "state": "OPEN",
      "open_time": "2025-06-11T09:53:46Z",
      "resource": {
        "type": "sql_alert"
      },
      "policy": {
        "name": "projects/my-project/alertPolicies/POLICY_1",
        "displayName": "test-policy"
      },
      "summaryText": "The row count SQL Condition for \"test-policy\" is above the threshold of 1."
    }
  ]
}
Os usuários do Curl podem adicionar a flag --data-urlencode seguida de uma expressão de filtro para filtrar alertas por tempo ou rótulo. Veja os exemplos a seguir:

Listar alertas abertos na última hora:

--data-urlencode "filter=(open_time>=\"`date -u -d "1 hour ago" +"%Y-%m-%dT%H:%M:%SZ"`\")"

Listar e filtrar alertas abertos no último dia:

--data-urlencode "filter=(open_time>=\"`date -u -d "1 DAY ago" +"%Y-%m-%dT%H:%M:%SZ"`\" AND state=open)"

Listar e filtrar alertas abertos entre dois períodos:

--data-urlencode "filter=(open_time>=\"`date -u -d "2 DAY ago" +"%Y-%m-%dT%H:%M:%SZ"`\" AND open_time<=\"`date -u -d "1 DAY ago" +"%Y-%m-%dT%H:%M:%SZ"`\")"

Liste e filtre alertas por rótulo do usuário. Neste exemplo, filtre por um rótulo do usuário com o nome app e o valor my-gke-app:

--data-urlencode "filter=(policy.user_labels.app=\"my-gke-app\")"
Os usuários do PowerShell podem usar o exemplo a seguir para adicionar um filtro com base no tempo ao URL da solicitação: 
$baseUrl = "https://monitoring.googleapis.com/v3/projects/my-project/alerts"
$filterValue = (Get-Date).AddHours(-1).ToString("yyyy-MM-ddTHH:mm:ssZ")
$filter = 'open_time >= "' + $filterValue + '"'
$encodedFilter = [System.Uri]::EscapeDataString($filter)
$url = $baseUrl + "?filter=" + $encodedFilter

Investigar um incidente

A página Detalhes do incidente contém informações que podem ajudar você a identificar a causa de um incidente.

Explorar resultados da consulta

O painel Tempo total de slot consumido por dia mostra a quantidade de tempo que seus slots reservados do BigQuery gastaram executando as consultas SQL da política de alertas nas últimas 24 horas.

O painel Resultados da consulta SQL mostra uma lista de resumos de resultados de consultas de cada vez que a Análise de dados de registros executou a consulta SQL da condição da política de alertas. Por padrão, a lista é filtrada para mostrar apenas as consultas que corresponderam à condição da política de alertas.

  • Para ver a consulta e a tabela de resultados de um horário específico em que o Log Analytics executou a consulta, clique em um valor na coluna Tempo de execução da consulta.
  • Para alternar entre mostrar apenas os resultados da consulta que corresponderam à condição da política de alertas e todas as consultas executadas pelo Log Analytics na política de alertas, clique em Mostrar apenas consultas que correspondem às condições de alerta.

Ver informações complementares

A seção Documentação mostra o modelo de documentação para notificações que você forneceu ao criar a política de alertas. Essas informações podem incluir uma descrição do que a política de alertas monitora e dicas para mitigação. Para mais informações, consulte Anotar notificações com documentação definida pelo usuário.

Se você não configurou a documentação para sua política de alertas, o painel Documentação mostra "Nenhuma documentação está configurada".

Para ajudar você a descobrir problemas subjacentes no aplicativo, analise incidentes relacionados a outras condições política de alertas.

A seção Incidentes relacionados mostra uma lista de outros incidentes criados quando a condição da política de alertas foi atendida.

Gerenciar incidentes

Os incidentes estão em um dos seguintes estados:

  •  Aberto: a condição da política de alertas baseada em SQL foi atendida, e o incidente ainda está aberto. Se a mesma condição for atendida novamente e já houver um incidente aberto, um novo incidente não será aberto.

  •  Reconhecido: o incidente está aberto e foi marcado manualmente como confirmado. Normalmente, esse status indica que o incidente está sendo investigado.

  •  Fechado: você encerrou manualmente o incidente, ou ele foi fechado automaticamente após o período de fechamento automático expirar.

Confirmar incidentes

Recomendamos que você marque um incidente como confirmado quando começar a investigar a causa dele.

Para marcar um incidente como confirmado, faça o seguinte:

  1. Na tabela Incidentes da página Alertas, clique em Ver todos os incidentes.

  2. Na página Incidentes, encontre o incidente que você quer confirmar e siga um destes procedimentos:

    • Clique em  Mais opções e selecione Confirmar.
    • Abra a página de detalhes do incidente e clique em Confirmar incidente.

Suspender uma política de alertas

Para impedir que o Monitoring crie incidentes e envie notificações durante um período específico, adie a política de alertas relacionada. Quando você adia uma política de alertas, os incidentes relacionados a ela permanecem abertos, mas não causam mais notificações. Os incidentes são fechados com base na duração do fechamento automático da política de alertas.

Para criar uma suspensão de um incidente que você está visualizando, faça o seguinte:

  1. Na página Detalhes do incidente, clique em Adiar política.

  2. Selecione a duração do adiamento. Depois de selecionar a duração, o adiamento começa imediatamente.

Você também pode adiar uma política de alertas na página Incidentes. Para isso, encontre o incidente que você quer adiar, clique em  Mais opções e selecione Adiar. É possível adiar as políticas de alertas durante interrupções para evitar mais notificações durante o processo de solução de problemas.

Fechar incidentes

É possível permitir que o Monitoring feche um incidente ou encerrar o incidente.

O Monitoring fecha automaticamente um incidente quando a duração do fechamento automático da política de alertas expira. Por padrão, a duração do fechamento automático é de 7 dias. A duração mínima de fechamento automático é de 30 minutos.

A duração do fechamento automático especifica o tempo que precisa decorrer, sem uma repetição da causa do incidente, antes que ele seja fechado. Por isso, quando um incidente é aberto e a causa dele ocorre novamente, ele pode ficar aberto por mais tempo do que a duração do fechamento automático.

Para fechar um incidente, faça o seguinte:

  1. Na tabela Incidentes da página Alertas, clique em Ver todos os incidentes.

  2. Na página Incidentes, encontre o incidente que você quer fechar e siga um destes procedimentos:

    • Clique em  Ver mais e selecione Fechar incidente
    • Abra a página Detalhes do incidente e clique em Fechar incidente.

Se você vir a mensagem Unable to close incident, tente novamente depois de alguns minutos. Não é possível fechar um novo incidente imediatamente porque as condições que causaram o incidente ainda são consideradas ativas pelo sistema de alertas.

Retenção e limites de dados

Para informações sobre limites e o período de armazenamento de incidentes, consulte Limites para alertas.

A seguir