Incidentes para políticas de alertas baseadas em SQL

Os alertas do Cloud Monitoring permitem rastrear e investigar problemas quando os resultados da consulta SQL em entradas de registro agrupadas atendem à condição de uma política de alertas baseada em SQL. Para cada alerta, o Monitoring envia uma notificação e cria uma página Detalhes do alerta para ajudar você a resolver problemas na falha e gerenciar o ciclo de vida do alerta.

Na página Detalhes do alerta, é possível ver resumos de resultados de consulta SQL e links para alertas relacionados. O Monitoring não cria um alerta se a política estiver suspensa ou desativada ou se o número de políticas de alertas ou alertas exceder os limites de alertas.

Esse recurso é compatível apenas com projetos do 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 alertas, 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.

Ver alertas

Para ver os alertas no seu projeto, use o Google Cloud console, a CLI gcloud ou a API Monitoring.

Console do Google Cloud

Para listar os alertas no projeto do 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 do Google Cloud , selecione seu projeto do Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.

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

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

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

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

Encontrar alertas mais antigos

A tabela Alertas na página Alertas mostra os alertas abertos mais recentes. Para ver alertas mais antigos, siga um destes procedimentos:

  • Para navegar pelas entradas na tabela Alertas, clique em  Mais recentes ou  Mais antigas.

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

    • Mostra todos os alertas, incluindo os fechados. Para mostrar todos os alertas, clique em Mostrar alertas fechados.
    • Filtrar alertas. Para saber como adicionar filtros, consulte Filtrar alertas.
    • Confirmar ou fechar um alerta ou adiar a política de alertas. Para acessar essas opções, clique em  Mais opções na linha do alerta e faça uma seleção no menu. Para mais informações, consulte Gerenciar alertas.

Filtrar alertas

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

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

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

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

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

    A tabela Alertas vai listar o filtro.

gcloud

Use a gcloud para receber e listar alertas.

Receber alerta

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. A resposta será semelhante a: 
{
  "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 alertas

É possível listar alertas no 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. A resposta será semelhante a: 
{
  "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 por rótulo. Por exemplo, filtre por horário 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 ordenar a saída. Por exemplo, --sort-by=open_time.

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

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

API Monitoring

É possível usar a API Monitoring para receber e listar alertas.

Receber alerta

Para ver detalhes de um único alerta 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. A resposta será semelhante a: 
{
  "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 alertas

Para listar alertas 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. A resposta será semelhante a: 
{
  "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 por uma expressão de filtro para filtrar os alertas por horário ou rótulo. Veja os exemplos a seguir:

Listar alertas que foram 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 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"`\")"

Listar e filtrar alertas por rótulo de usuário. Neste exemplo, filtre por um rótulo de 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 baseado em 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 alerta

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

Explorar resultados da consulta

O painel Informações da consulta mostra se as consultas da política de alertas são executadas em slots on demand do BigQuery ou em uma reserva. Esse painel também mostra a estimativa de bytes verificados e o tempo de slot consumido por dia, com base nas consultas executadas nos últimos sete dias.

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

  • Para ver a consulta e a tabela de resultados de um momento específico em que a Análise de Observabilidade executou a consulta, clique em um valor na coluna Horário de execução da consulta.
  • Para alternar entre mostrar apenas os resultados da consulta que correspondem à condição da política de alertas e todas as consultas que a Análise de Observabilidade executou com base 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, bem como dicas de 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 vai mostrar "Nenhuma documentação foi configurada".

Para ajudar você a descobrir problemas subjacentes no aplicativo, é possível explorar alertas relacionados a outras condições da política de alertas.

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

Gerenciar alertas

Os alertas estão em um dos seguintes estados:

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

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

  •  Fechado: você fechou o alerta manualmente ou ele foi fechado automaticamente após o período de encerramento automático.

Confirmar alertas

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

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

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

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

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

Suspender uma política de alertas

Para impedir que o Monitoring crie alertas 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 alertas relacionados a ela permanecem abertos, mas não causam mais notificações. Os alertas são fechados com base na duração de fechamento automático da política de alertas.

Para criar uma soneca para um alerta que você está visualizando, faça o seguinte:

  1. Na página Detalhes do alerta, clique em Política de adiamento.

  2. Selecione a duração do adiamento. Depois que você selecionar a duração, o adiamento vai começar imediatamente.

Também é possível adiar uma política de alertas na página Alertas. Para isso, encontre o alerta 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 outras notificações durante o processo de solução de problemas.

Fechar alertas

Você pode deixar o Monitoring encerrar um alerta para você ou pode encerrar o alerta.

O Monitoring fecha automaticamente um alerta 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 alerta, antes que ele seja fechado. Por esse motivo, quando um alerta está aberto e a causa dele se repete, o alerta pode permanecer aberto por mais tempo do que a duração do fechamento automático.

Para fechar um alerta, faça o seguinte:

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

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

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

Se a mensagem Unable to close alert aparecer, tente novamente em alguns minutos. Não é possível fechar um novo alerta imediatamente porque as condições que o causaram 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 alertas, consulte Limites para alertas.

A seguir