Incidentes para políticas de alerta baseadas em métricas

Um incidente é um registo de quando a condição ou as condições de uma política de alerta são cumpridas. Se uma política de alerta contiver várias condições, a política de alerta especifica se o cumprimento de uma condição é suficiente para criar um incidente. Normalmente, quando as condições são cumpridas, o Cloud Monitoring abre um incidente e envia uma notificação. 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 a cronologia do incidente e um gráfico que apresenta os dados das métricas que estão a ser monitorizadas. Também pode encontrar links para incidentes relacionados e entradas de registo.

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 métricas, que avaliam dados de séries cronológicas armazenados pelo Cloud Monitoring.

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
    • Tipo de métrica
    • Tipo do recurso

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

    Por exemplo, se selecionar Tipo de métrica e introduzir usage_time, pode ver apenas as seguintes opções no menu secundário:

    agent.googleapis.com/cpu/usage_time
compute.googleapis.com/guest/container/cpu/usage_time
container.googleapis.com/container/cpu/usage_time

    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-id1",
  "state": "OPEN",
  "open_time": "2025-06-11T09:53:46Z",
  "close_time": "2025-06-13T10:11:36Z",
  "resource": {
    "type": "gce_instance",
    "labels": {
      "zone": "us-west1",
      "instance_id": "123456789",
      "project_id": "my-project"
    }
  },
  "metric": {
    "labels": {
      "instance_name": "my-instance1"
    },
    "type": "compute.googleapis.com/instance/cpu/usage_time"
  },
  "policy": {
    "name": "projects/my-project/alertPolicies/POLICY_1",
    "displayName": "my-policy"
  },
  "summaryText": "[ALERT] VM Instance - CPU usage on my-project my-instance1"
}

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-id1",
      "state": "OPEN",
      "open_time": "2025-06-11T09:53:46Z",
      "close_time": "2025-06-13T10:11:36Z",
      "resource": {
        "type": "gce_instance",
        "labels": {
          "zone": "us-west1",
          "instance_id": "123456789",
          "project_id": "my-project"
        }
      },
      "metric": {
        "labels": {
          "instance_name": "my-instance1"
        },
        "type": "compute.googleapis.com/instance/cpu/usage_time"
      },
      "policy": {
        "name": "projects/my-project/alertPolicies/POLICY_1",
        "displayName": "my-policy"
      },
      "summaryText": "[ALERT] VM Instance - CPU usage on my-project my-instance1"
    }
  ]
}
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-id1",
  "state": "OPEN",
  "open_time": "2025-06-11T09:53:46Z",
  "close_time": "2025-06-13T10:11:36Z",
  "resource": {
    "type": "gce_instance",
    "labels": {
      "zone": "us-west1",
      "instance_id": "123456789",
      "project_id": "my-project"
    }
  },
  "metric": {
    "labels": {
      "instance_name": "my-instance1"
    },
    "type": "compute.googleapis.com/instance/cpu/usage_time"
  },
  "policy": {
    "name": "projects/my-project/alertPolicies/POLICY_1",
    "displayName": "my-policy"
  },
  "summaryText": "[ALERT] VM Instance - CPU usage on my-project my-instance1"
}

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-id1",
      "state": "OPEN",
      "open_time": "2025-06-11T09:53:46Z",
      "close_time": "2025-06-13T10:11:36Z",
      "resource": {
        "type": "gce_instance",
        "labels": {
          "zone": "us-west1",
          "instance_id": "123456789",
          "project_id": "my-project"
        }
      },
      "metric": {
        "labels": {
          "instance_name": "my-instance1"
        },
        "type": "compute.googleapis.com/instance/cpu/usage_time"
      },
      "policy": {
        "name": "projects/my-project/alertPolicies/POLICY_1",
        "displayName": "my-policy"
      },
      "summaryText": "[ALERT] VM Instance - CPU usage on my-project my-instance1"
    }
  ]
}
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 dados de métricas

Para analisar o estado da sua métrica antes e depois da ocorrência do incidente, use o gráfico Métricas de alerta. Este gráfico mostra uma cronologia e os intervalos temporais que fizeram com que a condição da sua política de alertas fosse cumprida.

Pode ajustar o intervalo da cronologia para procurar tendências e padrões nos dados de métricas relativos ao incidente:

  • Para alternar entre mostrar apenas as séries cronológicas que fizeram com que a condição fosse cumprida e mostrar todas as séries cronológicas que a condição avalia, clique em Mostrar todas as séries cronológicas.

  • Para alterar o intervalo de tempo apresentado pelo gráfico, pode usar o selecionador de intervalo de tempo na barra de ferramentas ou realçar intervalos de tempo no gráfico com o ponteiro.

Também pode analisar os dados das métricas com maior detalhe, visualizando-os no Explorador de métricas. Para tal, aceda ao gráfico Métricas de alerta e, de seguida, clique em Explorar dados. Por predefinição, o explorador de métricas agrega e filtra os dados de métricas para que o gráfico de métricas se alinhe com a série cronológica apresentada na cronologia de métricas de alerta.

Explore as entradas do registo

O painel Registos na página Detalhes do incidente mostra entradas de registo que correspondem ao tipo de recurso e às etiquetas do recurso monitorizado para a sua métrica. Pode analisar estas entradas do registo para encontrar informações adicionais que podem ajudar a resolver o seu incidente.

  • Para ver as entradas de registo no Explorador de registos, clique em Ver no Explorador de registos e, de seguida, selecione um projeto de âmbito. O Explorador de registos oferece ferramentas adicionais para analisar dados de entradas de registo, como uma cronologia de quando foram criadas as entradas de registo relacionadas.
  • Para ver e editar a consulta usada para filtrar as entradas do registo no Explorador de métricas, clique em Explorar dados.

Veja as informações da aplicação

Para políticas de alerta associadas a uma aplicação do App Hub, aceda à secção Associado à aplicação. Uma entrada nesta secção apresenta o ID da aplicação e links para um painel de controlo que apresenta informações sobre a aplicação. A segunda entrada apresenta uma carga de trabalho ou um serviço e inclui um link para um painel de controlo.

Veja informações suplementares

A secção Etiquetas mostra as etiquetas e os valores do recurso monitorizado e a métrica da série cronológica que causou o incidente, bem como as etiquetas do utilizador definidas na política de alertas. Estas informações podem ajudar a identificar o recurso monitorizado específico que causou o incidente. Para mais informações, consulte o artigo Anote incidentes com etiquetas.

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 incidentes que correspondem a uma das seguintes opções:

  • O incidente foi criado quando uma condição da mesma política de alertas foi cumprida.
  • O incidente partilha uma etiqueta com o incidente apresentado na página Detalhes do incidente.

Faça a gestão de incidentes

Os incidentes encontram-se num dos seguintes estados:

  •  Aberto: O conjunto de condições da política de alerta está a ser cumprido ou não existem dados que indiquem que a condição já não é cumprida. Se uma política de alerta contiver várias condições, os incidentes são abertos consoante a forma como essas condições são combinadas. Para mais informações, consulte o artigo Políticas com várias condições.

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

  •  Encerrado: O sistema observou que a condição deixou de ser cumprida, encerrou o incidente ou passaram 7 dias sem uma observação de que a condição continuava a ser cumprida.

Quando configurar uma política de alerta, certifique-se de que o estado estável fornece um sinal quando tudo está OK. Isto é necessário para garantir que o estado sem erros pode ser identificado e, se existir um incidente aberto, para esse incidente ser encerrado. Se não existir um sinal que indique que uma condição de erro parou, após a abertura de um incidente, este permanece aberto durante 7 dias após o acionamento da política de alertas.

Por exemplo, se criar uma política de alertas que lhe envia uma notificação quando a quantidade de erros é superior a 0, certifique-se de que produz uma quantidade de 0 erros quando não existem erros. Se a política de alertas devolver um valor nulo ou vazio no estado sem erros, não existe nenhum sinal para indicar quando os erros pararam. Se necessário, o PromQL permite-lhe especificar um valor predefinido que é usado quando não está disponível nenhum valor medido.

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.

Se a sua política de alertas estiver configurada para enviar notificações repetidas, a confirmação de um incidente não impede as notificações. Para as parar, efetue uma das seguintes ações:

  • Crie uma suspensão temporária para a política de alertas.
  • Desative a política de alertas.

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, o Monitoring também fecha todos os incidentes relacionados com a 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 encerre um incidente por si ou pode encerrar um incidente depois de as observações deixarem de chegar. Se fechar um incidente e, em seguida, chegarem dados que indicam que a condição foi cumprida, é criado um novo incidente. Quando fecha um incidente, essa ação não fecha outros incidentes abertos para a mesma condição. Se suspender uma política de alerta, os incidentes abertos são fechados quando a suspensão é iniciada.

A monitorização fecha automaticamente um incidente quando ocorre qualquer uma das seguintes situações:

  • Condições de limite de métricas:

    • Chega uma observação que indica que o limite não foi violado.

    • Não chegam observações, a condição está configurada para fechar incidentes quando as observações deixam de chegar e o estado do recurso subjacente é desconhecido ou não está desativado.

    • Não chegam observações durante o período de encerramento automático da política de alertas, e a condição não está configurada para encerrar automaticamente os incidentes quando as observações deixam de chegar. Para configurar a duração do fecho automático, pode usar a consola ou a API Monitoring. Google Cloud Por predefinição, a duração do encerramento automático é de sete dias. A duração mínima do encerramento automático é de 30 minutos.

  • Condições de ausência de métricas:

    • Ocorre uma observação.
    • Não chegam observações durante 24 horas após a expiração da duração de encerramento automático da política de alertas. Para configurar a duração do fecho automático, pode usar a Google Cloud consola ou a API Monitoring. Por predefinição, a duração do encerramento automático é de sete dias.

  • Condições da previsão:

    • É gerada uma previsão que prevê que a série cronológica não vai violar o limite no período de previsão.

    • Não chegam observações durante 10 minutos, a condição está configurada para fechar incidentes quando as observações deixam de chegar e o estado do recurso subjacente é desconhecido ou não está desativado.

    • Não chegam observações durante o período de encerramento automático da política de alertas, e a condição não está configurada para encerrar automaticamente os incidentes quando as observações deixam de chegar.

Por exemplo, uma política de alertas gerou um incidente porque a latência de resposta HTTP foi superior a 2 segundos durante 10 minutos consecutivos. Se a medição seguinte da latência da resposta HTTP for inferior ou igual a dois segundos, o incidente é encerrado. Da mesma forma, se não forem recebidos dados durante sete dias, o incidente é encerrado.

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 with active conditions, não é possível encerrar o incidente porque foram recebidos dados no período de alerta mais recente.

Se vir a mensagem Unable to close incident. Please try again in a few minutes., significa que não foi possível encerrar o incidente devido a um erro interno.

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?