Faça a gestão de incidentes para políticas de alertas baseadas em SQL

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

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

Para cada incidente, o Monitoring cria uma página de detalhes do incidente que lhe permite gerir o incidente e comunicar informações sobre o incidente que podem ajudar a resolver a falha. Por exemplo, a página Detalhes do incidente mostra listas de resumos dos resultados das consultas SQL e incidentes relacionados.

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

Esta funcionalidade só é suportada para Google Cloud projetos. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

Antes de começar

Para receber as autorizações de que precisa para ver e gerir incidentes, peça ao seu administrador que lhe conceda as seguintes funções de IAM no seu projeto:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Para mais informações sobre as funções do Cloud Monitoring, consulte o artigo Controle o acesso com a gestão de identidade e acesso.

Veja incidentes

Para ver incidentes no seu projeto, use a Google Cloud consola, a CLI gcloud (pré-visualização pública) ou a API Monitoring (pré-visualização pública).

Google Cloud consola

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

  1. Na Google Cloud consola, aceda à página  Alertas:

    Aceder a Alertas

    Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

  2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.

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

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

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

    É apresentada a página Detalhes do incidente. Para mais informações sobre a página Detalhes do incidente, consulte a secção Investigue um incidente deste documento.

Encontre incidentes mais antigos

A tabela Incidentes na página Alertas mostra os incidentes abertos mais recentes. Para ver incidentes mais antigos, faça uma das seguintes ações:

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

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

    • Mostrar todos os incidentes, incluindo os incidentes fechados. Para mostrar todos os incidentes, clique em Mostrar incidentes encerrados.
    • Filtre incidentes. Para obter informações sobre como adicionar filtros, consulte o artigo Filtre incidentes.
    • Confirmar ou fechar um incidente, ou suspender a respetiva política de alerta. Para aceder a estas opções, clique em  Mais opções na linha do incidente e faça uma seleção no menu. Para mais informações, consulte o artigo Faça a gestão de incidentes.

Filtre incidentes

Para restringir os incidentes apresentados na tabela, adicione filtros. Se adicionar vários filtros, a tabela apresenta apenas incidentes que satisfazem todos os filtros.

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

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

    • Estado do incidente
    • Nome da política de alerta
    • Quando o incidente foi aberto ou fechado

  2. Selecione um valor no menu secundário ou introduza um valor na barra de filtros.

    A tabela Incidentes apresenta o filtro.

gcloud

Pode usar o gcloud para obter incidentes e listar incidentes.

Obter incidente

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes 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 devolve uma resposta com detalhes do alerta, como o estado do alerta, as etiquetas anexadas e a política de alertas de origem. Tenha em atenção que as etiquetas na resposta estão sujeitas a alterações enquanto esta funcionalidade estiver em pré-visualização. A resposta é semelhante à seguinte: 
{
  "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."
}

Apresentar incidentes

Pode listar incidentes no seu projeto e filtrar os resultados através da CLI gcloud.

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes 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 devolve uma resposta com detalhes do alerta, como o estado do alerta, as etiquetas anexadas e a política de alertas de origem. Tenha em atenção que as etiquetas na resposta estão sujeitas a alterações enquanto esta funcionalidade estiver em pré-visualização. A resposta é semelhante à seguinte: 
{
  "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 pode usar as seguintes flags opcionais para filtrar, ordenar ou modificar o resultado:

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

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

  • --uri: O comando produz uma lista de URIs de recursos em vez do resultado predefinido.

  • --limit: defina esta flag como 2 ou superior para limitar o número de alertas devolvidos. Não use esta flag em conjunto com a flag --filter.

API Monitoring

Pode usar a API Monitoring para obter incidentes e listar incidentes.

Obter incidente

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

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • 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 o seu pedido, expanda uma destas opções:

O comando devolve uma resposta com detalhes do alerta, como o estado do alerta, as etiquetas anexadas e a política de alertas de origem. Tenha em atenção que as etiquetas na resposta estão sujeitas a alterações enquanto esta funcionalidade estiver em pré-visualização. A resposta é semelhante à seguinte: 
{
  "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."
}

Apresentar incidentes

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

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o identificador do projeto.

Método HTTP e URL: 

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

Para enviar o seu pedido, expanda uma destas opções:

O comando devolve uma resposta com detalhes do alerta, como o estado do alerta, as etiquetas anexadas e a política de alertas de origem. Tenha em atenção que as etiquetas na resposta estão sujeitas a alterações enquanto esta funcionalidade estiver em pré-visualização. A resposta é semelhante à seguinte: 
{
  "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 utilizadores do Curl podem adicionar a flag --data-urlencode seguida de uma expressão de filtro para filtrar os alertas por hora ou etiqueta. Veja os exemplos seguintes:

Apresentar alertas que foram abertos na última hora:

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

Liste e filtre os alertas que estão abertos desde o último dia:

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

Liste e filtre os alertas que foram 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 etiqueta de utilizador. Neste exemplo, filtre por uma etiqueta do utilizador com o nome app e o valor my-gke-app:

--data-urlencode "filter=(policy.user_labels.app=\"my-gke-app\")"
Os utilizadores do Powershell podem usar o seguinte exemplo para adicionar um filtro baseado no tempo ao URL do pedido: 
$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

Investigue um incidente

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

Explore os resultados da consulta

O painel Tempo total de intervalo consumido por dia mostra a quantidade de tempo que os intervalos do BigQuery reservados gastaram a executar as consultas SQL para a política de alertas nas últimas 24 horas.

O painel Resultados da consulta SQL mostra uma lista de resumos dos resultados da consulta de cada vez que o Log Analytics executou a consulta SQL a partir da condição da política de alerta. Por predefiniçã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 da consulta de um momento específico em que o Log Analytics executou a consulta, clique num valor da coluna Tempo de execução da consulta.
  • Para alternar entre mostrar apenas os resultados da consulta que corresponderam à condição da política de alerta e todas as consultas que o Log Analytics executou a partir da política de alerta, clique em Mostrar apenas consultas que correspondem às condições de alerta.

Veja informações suplementares

A secção Documentação mostra o modelo de documentação para as notificações que forneceu quando criou a política de alertas. Estas informações podem incluir uma descrição do que a política de alerta monitoriza, bem como sugestões de mitigação. Para mais informações, consulte o artigo Anote as notificações com documentação definida pelo utilizador.

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

Para ajudar a descobrir problemas subjacentes na sua aplicação, pode explorar incidentes relacionados com outras condições da política de alertas.

A secção Incidentes relacionados mostra uma lista de outros incidentes que foram criados quando a condição da política de alertas foi cumprida.

Faça a gestão de incidentes

Os incidentes encontram-se num dos seguintes estados:

  •  Abrir: A condição da política de alertas baseada em SQL foi cumprida e o incidente ainda está aberto. Se a mesma condição for cumprida novamente e já existir um incidente aberto, não é aberto um novo incidente.

  •  Confirmado: o incidente está aberto e foi marcado manualmente como confirmado. Normalmente, este estado indica que o incidente está a ser investigado.

  •  Fechado: Fechou o incidente manualmente ou este foi fechado automaticamente após o período de fecho automático expirar.

Confirme incidentes

Recomendamos que marque um incidente como reconhecido quando começar a investigar a causa do incidente.

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 quer confirmar e, de seguida, faça uma das seguintes ações:

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

Suspenda uma política de alerta

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

Para criar uma suspensão temporária para um incidente que está a ver, faça o seguinte:

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

  2. Selecione a duração da suspensão. Depois de selecionar a duração da repetição, a repetição começa imediatamente.

Também pode suspender uma política de alerta na página Incidentes. Para tal, procure o incidente que quer suspender, clique em  Mais opções e, de seguida, selecione Suspender. Pode suspender as políticas de alerta durante interrupções para evitar mais notificações durante o processo de resolução de problemas.

Feche incidentes

Pode permitir que a monitorização feche um incidente por si ou pode fechar o incidente.

A monitorização fecha automaticamente um incidente quando a duração de fecho automático da política de alerta expira. Por predefinição, a duração do fecho automático é de 7 dias. A duração mínima do encerramento automático é de 30 minutos.

A duração do fecho automático especifica o tempo que tem de decorrer, sem repetição da causa do incidente, antes de o incidente ser fechado. Por este motivo, quando um incidente está aberto e a respetiva causa volta a ocorrer, o incidente pode permanecer aberto durante mais tempo do que a duração do fecho 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 quer fechar e, de seguida, faça uma das seguintes ações:

    • Clique em  Ver mais e, de seguida, selecione Fechar incidente
    • Abra a página Detalhes do incidente para esse incidente e, de seguida, clique em Fechar incidente.

Se vir a mensagem Unable to close incident, tente novamente dentro de alguns minutos. Não pode encerrar 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 os limites e o período de retenção de incidentes, consulte o artigo Limites para alertas.

O que se segue?