Criar e gerenciar suspensões

Neste documento, descrevemos como criar e gerenciar seus adiamentos. Um adiamento impede que o Cloud Monitoring crie incidentes e emita notificações durante um período específico. Cada adiamento especifica os recursos a que ele se aplica.

Para uma visão geral conceitual, consulte Adiar notificações e incidentes.

Para criar e gerenciar adiamentos, use o console Google Cloud ou a API Cloud Monitoring.

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

Antes de começar

Conclua as etapas a seguir no projeto do Google Cloud que armazena sua política de alertas:

  1. Verifique se você tem as permissões necessárias:

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

  2. Se você quiser usar os exemplos da API Cloud Monitoring neste documento, faça o seguinte:

    1. Crie uma variável de ambiente, PROJECT_ID, para manter o ID do seu projetoGoogle Cloud :

      PROJECT_ID=PROJECT_ID

    2. Faça a autenticação na Google Cloud CLI:

      gcloud auth login

    3. Defina o projeto padrão Google Cloud :

      gcloud config set project ${PROJECT_ID}

    4. Crie um token de autorização:

      ACCESS_TOKEN=`gcloud auth print-access-token`

      É necessário atualizar o token de acesso periodicamente. Se os comandos que funcionavam informarem de repente que você não está autenticado, reenvie esse comando.

Criar um adiamento

Para impedir que as políticas de alerta criem incidentes e enviem notificações, crie um adiamento. Quando você restringe uma suspensão a uma política de alertas, ela pode incluir filtros baseados em rótulos. Se você adicionar filtros com base em rótulos, a suspensão será aplicada apenas aos incidentes que corresponderem aos filtros. Depois de criar uma suspensão, não é possível modificar o filtro baseado em rótulos ou a lista de políticas a que ela se aplica.

Console

O console do Google Cloud oferece duas maneiras de criar uma soneca:

  • Se você começar na página Detalhes do incidente de um incidente aberto, a caixa de diálogo que você preenche para criar a suspensão temporária será pré-configurada para listar sua política de alertas. A caixa de diálogo também permite selecionar marcadores, que são anexados à ação de adiar como filtros baseados em marcadores.

  • Se você começar na página Alertas, poderá criar uma suspensão temporária com critérios que listam até 16 políticas de alertas. No entanto, não é possível anexar filtros com base em rótulos ao adiamento, mesmo que os critérios de adiamento listem uma política de alertas.

Para criar uma ação de adiar de um incidente aberto, faça o seguinte:

  1. No console 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 do App Hub ou o projeto de gerenciamento da pasta com app ativado.
  3. No painel Incidentes da página Alertas, encontre seu incidente e clique em Resumo do incidente.
  4. Na página Detalhes do incidente, clique em Adiar e selecione a duração do adiamento.

  5. Opcional: para adicionar um filtro com base em rótulos à sua soneca, acesse a seção Rótulos e selecione um ou mais rótulos. Um filtro com base em rótulos pode incluir rótulos de recursos e métricas. Quando a política de alertas não é baseada em PromQL, o filtro também pode incluir rótulos de metadados.

    Normalmente, as suspensões temporárias são aplicadas a todos os incidentes criados por uma política de alertas. Com os filtros, é possível adiar incidentes cujos rótulos correspondam aos rótulos no filtro.

  6. Clique em Adiar. A suspensão agora se aplica à política de alertas que criou o incidente.

Para criar uma ação de adiamento na página Alertas, faça o seguinte:

  1. No console 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 do App Hub ou o projeto de gerenciamento da pasta com app ativado.
  3. Na página Alertas, clique em Criar adiamento.
  4. Digite um nome descritivo para o adiamento. Esse nome é mostrado na página Alertas.
  5. Selecione um Horário de início. Você pode inserir um horário específico ou iniciar o adiamento quando ele for criado.
  6. Insira a Duração. O valor desse campo determina a duração do adiamento.

  7. Preencha a seção Critérios de adiamento. Use o menu Políticas de alertas para selecionar as políticas a que a suspensão se aplica.

    É possível adicionar até 16 políticas de alertas a uma suspensão.

    Depois que um adiamento é criado, os critérios não podem ser modificados.

    Depois de preencher a seção Critérios de adiamento, o painel Criar adiamento lista os incidentes anteriores que correspondem aos critérios.

  8. Clique em Criar.

API Cloud Monitoring

Com a API Cloud Monitoring, é possível criar uma suspensão temporária com critérios que listam até 16 políticas de alertas. Se o adiamento se aplicar a uma política de alertas, você também poderá incluir filtros com base em rótulos.

Para criar uma suspensão, invoque o método snoozes.create enviando uma solicitação POST ao endpoint Snooze. É necessário fornecer um objeto snooze:

curl -d @my-snooze.json -H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-X POST https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/snoozes

Na expressão anterior, PROJECT_ID é uma variável de ambiente que armazena o ID do projeto. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

O método retorna um objeto snooze. O campo "name", que inclui o ID de adiamento gerado pelo Monitoring, é a única diferença entre o objeto retornado e o conteúdo de my-snooze.json:

{
  "name": "projects/my-project/snoozes/778899",
  "criteria": {
    "policies": [
      "projects/my-project/alertPolicies/001122"
    ]
  },
  "interval": {
    "startTime": "2022-11-12T19:00:20Z",
    "endTime": "2022-11-12T19:05:20Z"
  },
  "displayName": "Snooze2"
}

CLI da gcloud

Com a CLI gcloud, é possível criar uma suspensão temporária com critérios que listam até 16 políticas de alertas. Se o adiamento se aplicar a uma política de alertas, você também poderá incluir filtros com base em rótulos.

Para criar uma suspensão, execute o comando gcloud monitoring snoozes create:

gcloud monitoring snoozes create --criteria-policies=LIST_OF_POLICIES --display-name=DISPLAY_NAME --start-time=START_TIME --end-time=END_TIME --project=PROJECT_ID --criteria-filter=FILTER

Antes de executar o comando anterior, substitua o seguinte:

  • LIST_OF_POLICIES: as políticas a que o adiamento se aplica. Se você especificar vários projetos, separe-os com uma vírgula.
  • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
  • DISPLAY_NAME: o nome a ser exibido no console do Google Cloud .
  • START_TIME: o horário de início.

  • END_TIME : o horário de término. O valor precisa ser pelo menos um minuto depois do horário de início.

    Para os horários de início e término, siga as regras de formatação ISO 8601. No entanto, é possível especificar horários absolutos ou relativos. O exemplo a seguir especifica horários absolutos. Para adiar um lembrete em 30 minutos a partir do horário atual, use --start-time="+PTM30M".

  • FILTER: opcional. Um filtro com base em rótulos pode ser definido quando o adiamento se aplica a uma política de alertas. O filtro, que pode incluir rótulos de recurso, métrica e metadados, aplica a suspensão a incidentes com rótulos correspondentes. Quando a política de alertas é baseada em PromQL, o filtro não pode usar rótulos de metadados. Para mais informações, consulte a página de referência do gcloud monitoring snoozes create.

Por exemplo, o comando a seguir cria uma suspensão para uma política de alertas com o ID "12345". O período de adiamento é o intervalo de 1º de março de 2025 a 7 de março de 2025.

gcloud monitoring snoozes create --display-name="Maintenance Week" \
    --criteria-policies="projects/my-project/alertPolicies/12345" \
    --start-time="2025-03-01T03:00:00.0-0500" \
    --end-time="2025-03-07T23:59:59.5-0500" \
    --project=PROJECT_ID

O exemplo anterior cria o seguinte adiamento em my-project:

{
  "name": "projects/my-project/snoozes/778899",
  "criteria": {
    "policies": [
      "projects/my-project/alertPolicies/12345"
    ]
  },
  "interval": {
    "startTime": "2025-03-01T03:00:00.0-0500",
    "endTime": "2025-03-07T23:59:59.5-0500"
  },
  "displayName": "Maintenance Week"
}

Se a operação for bem-sucedida, a resposta a esse comando será semelhante a esta:

Created snooze [projects/my-project/snoozes/778899]

O nome de uma política de alertas não é exibido no console Google Cloud . Para determinar o nome de uma política de alertas, faça o seguinte:

  • Execute o comando gcloud alpha monitoring policies list. Os dados de resposta deste comando incluem o nome das suas políticas de alertas.
  • Confira a representação JSON de uma política de alertas. Você pode fazer o download da representação JSON para seu sistema local usando uma opção na página Detalhes da política.

Criar adiamentos recorrentes

Para criar adiamentos que ocorrem em intervalos recorrentes, escreva um script que crie um adiamento para uma política de alertas. Em seguida, use um programador de jobs, como cron ou o Cloud Scheduler, para executar o script na programação necessária.

Listar adiamentos

Quando você cria uma ação de adiar, ela é adicionada ao registro histórico de adiamentos do seu projeto. Esse registro mostra os adiamentos expirados, ativos e futuros. Não é possível remover entradas desse registro, ou seja, não é possível excluir um adiamento. No entanto, nessa visualização, é possível mostrar os detalhes sobre um adiamento e realizar ações como editar ou copiar o adiamento.

Console

Para ver uma lista de adiamentos, faça o seguinte:

  1. No console 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 do App Hub ou o projeto de gerenciamento da pasta com app ativado.

  3. Clique em Ver todos os adiamentos no painel Adiar.

    A página Adiar mostra uma lista de adiamentos e uma linha do tempo que exibe graficamente os adiamentos passados, futuros e ativos.

    • Para editar, copiar, cancelar ou encerrar uma soneca, use o menu Mais opções da soneca. O estado de adiamento determina quais opções estão disponíveis.
    • Para listar todas as sonecas, ative a opção Mostrar sonecas anteriores. Por padrão, apenas os adiamentos ativos e futuros são listados.
    • Para mudar o período de exibição da tabela Linha do tempo, use o menu Período. Por padrão, a tabela mostra dados da próxima hora. No entanto, é possível modificar esse campo para especificar períodos passados ou futuros. As adições expiradas são mantidas por 13 meses.
    • Para ver detalhes sobre um adiamento específico, clique em Ver detalhes.
    • Para ver um resumo das adições ativas, coloque o ponteiro na área sombreada da linha Ativa na tabela Linha do tempo. A dica mostra as informações resumidas.
    • Para ver uma representação gráfica das adições ativas, expanda a linha Ativa da tabela Linha do tempo.

API Cloud Monitoring

Para listar todas as adições que pertencem a um projeto Google Cloud , invoque o método snoozes.list:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/snoozes

Na expressão anterior, PROJECT_ID é uma variável de ambiente que armazena o ID do projeto. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

O método retorna uma lista de objetos snooze. Por exemplo, quando um projeto tem um adiamento, a resposta ao comando snoozes.list é semelhante a esta:

{
  "name": "projects/my-project/snoozes/778899",
  "criteria": {
    "policies": [
      "projects/my-project/alertPolicies/12345"
    ]
  },
  "interval": {
    "startTime": "2025-03-01T03:00:00.0-0500",
    "endTime": "2025-03-07T23:59:59.5-0500"
  },
  "displayName": "Snooze2"
}

Para receber informações sobre um adiamento específico, invoque o método snoozes.get e especifique o ID do projeto e do adiamento. Na resposta anterior, o ID da suspensão é 2986663705844383744:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/snoozes/${SNOOZE_ID}

O método retorna um único objeto snooze:

{
  "name": "projects/my-project/snoozes/778899",
  "criteria": {
    "policies": [
      "projects/my-project/alertPolicies/12345"
    ]
  },
  "interval": {
    "startTime": "2025-03-01T03:00:00.0-0500",
    "endTime": "2025-03-07T23:59:59.5-0500"
  },
  "displayName": "Snooze2"
}

CLI da gcloud

Para listar as adições no projeto atual, execute o comando gcloud monitoring snoozes list:

gcloud monitoring snoozes list --project=PROJECT_ID OPTIONAL_FLAGS

Antes de executar o comando anterior, substitua o seguinte:

  • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
  • OPTIONAL_FLAGS: para informações sobre as flags opcionais, consulte a página de referência do gcloud monitoring snoozes list.

A resposta a esse comando é uma lista de nomes de adiamentos no projeto, formatada como YAML. Por exemplo, a resposta a esse comando para o projetoGoogle Cloud com ID my-project é uma única entrada:

criteria:
  policies:
  - projects/my-project/alertPolicies/12345
  - projects/my-project/alertPolicies/23451
displayName: Maintenance Week
interval:
  endTime: '2023-03-08T04:59:59Z'
  startTime: '2023-03-01T08:00:00Z'
name: projects/my-project/snoozes/778899

Para listar detalhes sobre um adiamento específico, execute o comando gcloud monitoring snoozes describe:

gcloud monitoring snoozes describe NAME --project=PROJECT_ID

Por exemplo, para mostrar os detalhes sobre a ação de adiar com o nome projects/my-project/snoozes/778899, execute o seguinte comando:

gcloud monitoring snoozes describe projects/my-project/snoozes/778899 --project=PROJECT_ID

Se você fornecer um NAME inválido para um comando describe, a resposta vai conter um código de erro 500 e a seguinte mensagem:

Internal error encountered. Please retry after a few seconds. If internal errors persist, contact support at https://cloud.google.com/support/docs.

Editar uma soneca

É possível editar o nome e o período de uma soneca futura, além do nome e do horário de término de uma soneca ativa. Por exemplo, quando uma janela de manutenção é reprogramada, talvez seja necessário editar uma soneca.

Não é possível editar um adiamento anterior, os critérios de qualquer adiamento ou os filtros baseados em rótulos anexados a um adiamento.

Se quiser programar um adiamento passado para um período futuro, copie o adiamento e aplique as mudanças à cópia antes de selecionar Criar.

Console

Para editar uma soneca, faça o seguinte:

  1. No console 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 do App Hub ou o projeto de gerenciamento da pasta com app ativado.
  3. Clique em Ver todos os adiamentos no painel Adiar.
  4. Na lista de adiamentos, encontre o que você quer editar e selecione Editar adiamento no menu Mais opções.
  5. Clique em Salvar depois de concluir as mudanças.

API Cloud Monitoring

Para modificar uma suspensão programada, invoque o método snoozes.patch enviando uma solicitação PATCH ao endpoint Snooze. Você precisa fornecer o objeto snooze revisado e incluir parâmetros de consulta que identifiquem quais campos foram modificados. Ao usar curl, os parâmetros de consulta precisam ser codificados em URL.

Para adiamentos futuros, é possível modificar o nome e o período. Para adiamentos ativos, é possível modificar o nome e o horário de término. Não é possível modificar adiamentos anteriores.

Para atualizar o displayName de um adiamento, crie um arquivo JSON, my-updated-snooze.json, que descreve o objeto de adiamento e atualiza o nome de exibição. Em seguida, execute o comando:

curl -d @my-updated-snooze.json -H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-X PATCH https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/snoozes/${SNOOZE_ID}?updateMask=displayName

Na expressão anterior:

  • PROJECT_ID é uma variável de ambiente que armazena o ID do seu projeto. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

  • SNOOZE_ID é uma variável de ambiente que armazena o ID do adiamento.

O método retorna um objeto snooze idêntico ao conteúdo do arquivo my-updated-snooze.json:

{
  "name": "projects/my-project/snoozes/778899",
  "criteria": {
    "policies": [
      "projects/my-project/alertPolicies/12345"
    ]
  },
  "interval": {
    "startTime": "2025-03-01T03:00:00.0-0500",
    "endTime": "2025-03-07T23:59:59.5-0500"
  },
  "displayName": "Snooze2"
}

CLI da gcloud

Para editar uma soneca, execute o comando gcloud monitoring snoozes update. É possível atualizar o nome de exibição, o horário de início e o horário de término:

gcloud monitoring snoozes update NAME --project=PROJECT_ID OPTIONAL_FLAGS

Antes de executar o comando anterior, substitua o seguinte:

  • NAME: o nome da ação de adiar.
  • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
  • OPTIONAL_FLAGS: para informações sobre as flags opcionais, consulte a página de referência do gcloud monitoring snoozes update.

Por exemplo, para mudar o nome de exibição da ação de adiar com o nome projects/my-project/snoozes/778899, execute o seguinte comando:

gcloud monitoring snoozes update projects/my-project/snoozes/778899 --display-name="Maintenance Week" --project=PROJECT_ID

Encerrar ou cancelar uma soneca

Se você quiser receber notificações de recursos que correspondem aos critérios especificados em uma suspensão ativa, encerre a suspensão. Por exemplo, quando uma manutenção programada é concluída mais rápido do que o previsto, talvez você queira encerrar um adiamento.

Se você tiver um adiamento programado que não quer mais, cancele-o. A operação de cancelamento define a duração como zero e faz com que a soneca passe para o estado Passado.

Console

Para encerrar uma soneca ativa ou cancelar uma soneca futura, faça o seguinte:

  1. No console 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 do App Hub ou o projeto de gerenciamento da pasta com app ativado.
  3. Clique em Ver todos os adiamentos no painel Adiar.

  4. Na lista de adiamentos, encontre o que você quer encerrar ou cancelar e siga um destes procedimentos:

    • Para encerrar uma soneca ativa, selecione Encerrar agora no menu Mais opções.
    • Para cancelar uma soneca programada, selecione Cancelar soneca no menu Mais opções.

API Cloud Monitoring

Para encerrar um adiamento ativo, edite-o e defina o horário de término como o horário atual. Para mais informações, consulte Editar uma soneca.

Para cancelar um adiamento futuro, edite-o e defina o horário de término como o horário de início. O horário de início precisa ser no futuro. Para mais informações, consulte Editar uma soneca.

CLI da gcloud

Para encerrar uma ação de adiar ativa ou cancelar uma ação de adiar futura, execute o comando gcloud monitoring snoozes cancel:

gcloud monitoring snoozes cancel NAME --project=PROJECT_ID

Antes de executar o comando anterior, substitua o seguinte:

  • NAME: o nome da ação de adiar.
  • PROJECT_ID: o identificador do projeto. Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

Por exemplo, para cancelar o adiamento com o nome projects/my-project/snoozes/778899, execute o seguinte comando:

gcloud monitoring snoozes cancel projects/my-project/snoozes/778899 --project=PROJECT_ID

Copiar um adiamento

Quando quiser usar uma suspensão como modelo para outra, faça uma cópia. Ao copiar um adiamento, o editor de adiamento é aberto com todos os campos, exceto o horário de início, definidos com os valores do adiamento original. É possível modificar todos os campos antes de clicar em Criar.

Para copiar uma ação de adiar usando o console, faça o seguinte:

  1. No console 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 do App Hub ou o projeto de gerenciamento da pasta com app ativado.
  3. Clique em Ver todos os adiamentos no painel Adiar.
  4. Na lista de adiamentos, encontre o que você quer editar e selecione Copiar adiamento no menu Mais opções.
  5. Aplique as modificações à cópia e clique em Criar.

A seguir