Criar e gerenciar sonecas

Este documento descreve como criar e gerenciar os 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 aos quais se aplica.

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

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

Antes de começar

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

    • Para ter as permissões necessárias para visualizar e editar os adiamentos usando o console do Google Cloud, peça ao administrador para conceder a você o papel de IAM Editor do Monitoring (roles/monitoring.editor) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

      Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de 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.

  2. Para usar os exemplos da API Cloud Monitoring neste documento, faça o seguinte:

    1. Crie uma variável de ambiente, PROJECT_ID, para armazenar o ID do projeto do Google Cloud:

      PROJECT_ID=PROJECT_ID

    2. Autentique-se na Google Cloud CLI:

      gcloud auth login

    3. Defina o projeto padrão do 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 funcionaram informarem de repente que você não está autenticado, reenvie este comando.

Criar um adiamento

Para evitar que as políticas de alertas criem incidentes e enviem notificações, crie um adiamento.

É possível criar um adiamento usando o console do Google Cloud, a CLI gcloud ou a API Cloud Monitoring.

Console

  1. No painel de navegação do console do Google Cloud, selecione Monitoramento e  Alertas:

    Acessar Alertas

  2. Para criar um adiamento de um incidente aberto, faça o seguinte:
    1. No painel Incidentes da página "Alertas", encontre o incidente e clique no Resumo do incidente.
    2. Na página Detalhes do incidente, clique em Adiar e selecione a duração do adiamento. Não é possível configurar outros campos.

  3. Caso contrário, faça o seguinte:

    1. Na página Alertas, clique em Criar adiamento.
    2. Digite um nome descritivo para o adiamento. Esse nome é mostrado na página Alertas.
    3. Selecione um Horário de início. Insira um horário específico ou inicie o adiamento quando ele for criado.
    4. Insira a Duração. O valor desse campo determina quanto tempo o adiamento vai durar.

    5. Preencha a seção Critérios de adiamento. Use o menu Políticas de alertas para selecionar as políticas de alertas às quais o adiamento se aplica.

      É possível adicionar até 16 políticas de alertas a um adiamento.

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

    6. Clique em Criar.

API Cloud Monitoring

Para criar um adiamento, invoque o método snoozes.create emitindo uma solicitação POST para o endpoint Snooze. Forneça 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

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/2986666341878464512",
  "criteria": {
    "policies": [
      "projects/my-project/alertPolicies/787884840895011889"
    ]
  },
  "interval": {
    "startTime": "2022-11-12T19:00:20Z",
    "endTime": "2022-11-12T19:05:20Z"
  },
  "displayName": "Snooze2"
}

CLI da gcloud

Para criar um adiamento, 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

No comando anterior, a end-time precisa ser pelo menos um minuto mais tarde que a start-time. É necessário seguir as regras de formatação ISO 8601. No entanto, você pode especificar horários absolutos ou relativos. O exemplo a seguir especifica tempos absolutos. Para iniciar um adiamento 30 minutos a partir do horário atual, use --start-time="+PTM30M".

Se você especificar vários projetos, separe-os por vírgula.

Por exemplo, o comando a seguir cria um adiamento com o nome de exibição "Semana de manutenção". O adiamento se aplica a duas políticas de alertas e abrange o intervalo de tempo de 1o a 7 de março:

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

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

{
 "name": "projects/my-project/snoozes/98765",
 "displayName": "Maintenance Week",
 "interval": {
   "startTime": "2023-03-01T08:00:00Z",
   "endTime": "2023-03-08T04:59:59Z"
 },
 "criteria": {
   "policies": [
     "projects/my-project/alertPolicies/12345",
     "projects/my-project/alertPolicies/23451",
   ]
 }
}

Se bem-sucedido, a resposta a esse comando será semelhante a esta:

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

O nome de uma política de alertas não é exibido no console do Google Cloud. Para determinar o nome de uma política de alertas, siga um destes procedimentos:

  • Execute o comando gcloud alpha monitoring policies list. Os dados de resposta desse comando incluem o nome das políticas de alertas.
  • Veja a representação JSON de uma política de alertas. É possível 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 Cloud Scheduler, para executar o script na programação necessária.

Listar sonecas

Quando você cria um adiamento, ele é adicionado ao registro histórico de adiamentos do 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 exibir os detalhes de 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 painel de navegação do console do Google Cloud, selecione Monitoramento e  Alertas:

    Acessar Alertas

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

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

    • Para editar, copiar, cancelar ou encerrar um adiamento, use o menu Mais opções para o adiamento. O estado de adiamento determina quais opções estão disponíveis.
    • Para listar todos os adiamentos, ative a opção Mostrar adiamentos anteriores. Por padrão, apenas os adiamentos ativos e futuros são listados.
    • Para alterar o período de exibição da tabela Linha do tempo, use o menu Intervalo de tempo. Por padrão, a tabela mostra os dados da próxima hora. No entanto, você pode modificar esse campo para especificar períodos passados ou futuros. Os adiamentos expirados são mantidos por 13 meses.
    • Para ver os detalhes de um adiamento específico, clique em Ver detalhes.
    • Para ver um resumo dos adiamentos ativos, coloque o ponteiro na área sombreada da linha Ativos na tabela Linha do tempo. A dica exibe as informações resumidas.
    • Para ver uma representação gráfica dos adiamentos ativos, expanda a linha Ativos da tabela Linha do tempo.

API Cloud Monitoring

Para listar todos os adiamentos pertencentes a um projeto do Google Cloud, invoque o método snoozes.list:

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

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:

{
  "snoozes": [
    {
      "name": "projects/my-project/snoozes/2986663705844383744",
      "criteria": {
        "policies": [
          "projects/my-project/alertPolicies/787884840895011889"
        ]
      },
      "interval": {
        "startTime": "2022-11-08T19:00:20Z",
        "endTime": "2022-11-08T19:05:20Z"
      },
      "displayName": "Snooze1"
    }
  ]
}

Para acessar informações sobre um adiamento específico, invoque o método snoozes.get e especifique os ID do projeto e do adiamento. Na resposta anterior, o ID de soneca é 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/2986663705844383744",
  "criteria": {
    "policies": [
      "projects/my-project/alertPolicies/787884840895011889"
    ]
  },
  "interval": {
    "startTime": "2022-11-08T19:00:20Z",
    "endTime": "2022-11-08T19:05:20Z"
  },
  "displayName": "Snooze1"
}

CLI da gcloud

Para listar os adiamentos no projeto atual, execute o comando gcloud monitoring snoozes list:

gcloud monitoring snoozes list OPTIONAL_FLAGS

Para informações sobre as sinalizações 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, formatados como YAML. Por exemplo, a resposta a esse comando para o projeto do Google Cloud com o 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/98765

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

gcloud monitoring snoozes describe NAME

Por exemplo, para exibir os detalhes do adiamento com o nome projects/my-project/snoozes/98765, execute o seguinte comando:

gcloud monitoring snoozes describe projects/my-project/snoozes/98765

Se você fornecer um NAME inválido a 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 um adiamento

Você pode editar o nome e o período de um adiamento futuro e o nome e horário de término de um adiamento ativo. Por exemplo, quando uma janela de manutenção é reprogramada, talvez seja necessário editar um adiamento.

Não é possível editar um adiamento anterior nem os critérios de um adiamento. No entanto, se você quiser programar um adiamento passado para um período futuro, copie o adiamento e aplique as alterações à cópia antes de selecionar Criar.

Console

Para editar um adiamento, faça o seguinte:

  1. No painel de navegação do console do Google Cloud, selecione Monitoramento e  Alertas:

    Acessar Alertas

  2. Clique em Ver todos os adiamentos no painel Adiar.
  3. Na lista de adiamentos, encontre aquele que você quer editar e selecione Editar adiamento no menu Mais opções.
  4. Clique em Salvar depois de concluir as mudanças.

API Cloud Monitoring

Para modificar um adiamento existente, invoque o método snoozes.patch emitindo uma solicitação PATCH para o endpoint Snooze. É necessário 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 para uso em URL.

Para os próximos adiamentos, você pode 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 adições anteriores.

Para atualizar o displayName de um adiamento, crie um arquivo JSON, my-updated-snooze.json, que descreva o objeto de adiamento e atualize 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

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

{
  "name": "projects/my-project/snoozes/2986665388391530496",
  "criteria": {
    "policies": [
      "projects/my-project/alertPolicies/7164333552684403347"
    ]
  },
  "interval": {
    "startTime": "2022-11-08T22:26:05Z",
    "endTime": "2022-11-08T22:31:05Z"
  },
  "displayName": "Updated snooze name"
}

CLI da gcloud

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

gcloud monitoring snoozes update NAME OPTIONAL_FLAGS

Para ver uma lista de opções do comando update, consulte a página de referência gcloud monitoring snoozes update.

Por exemplo, para mudar o nome de exibição do adiamento com o nome projects/my-project/snoozes/98765, execute o seguinte comando:

gcloud monitoring snoozes update projects/my-project/snoozes/98765  --display-name="March Maintenance"

Finalizar ou cancelar um adiamento

Se você quiser receber notificações sobre recursos que correspondem aos critérios especificados em um adiamento ativo, encerre o adiamento. Por exemplo, quando a manutenção planejada é concluída mais rapidamente do que o previsto, convém encerrar um adiamento.

Se você não quiser mais um soneca futura, cancele-o. A operação de cancelamento define a duração como zero e resulta na transição do adiamento para o estado Past.

Console

Para encerrar um adiamento ativo ou cancelar um próximo, faça o seguinte:

  1. No painel de navegação do console do Google Cloud, selecione Monitoramento e  Alertas:

    Acessar Alertas

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

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

    • Para encerrar um adiamento ativo, selecione Finalizar agora no menu Mais opções.
    • Para cancelar um adiamento futuro, selecione Cancelar adiamento no menu Mais opções.

API Cloud Monitoring

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

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

CLI da gcloud

Para encerrar um adiamento ativo ou cancelar um futuro, execute o comando gcloud monitoring snoozes cancel:

gcloud monitoring snoozes cancel NAME

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

gcloud monitoring snoozes cancel projects/my-project/snoozes/98765

Copiar um adiamento

Quando você quiser usar um adiamento atual como modelo para outro, faça uma cópia. Quando você copia um adiamento, o editor de adiamento é aberto com todos os campos, exceto o horário de início definido com os valores do adiamento original. É possível modificar todos os campos antes de clicar em Criar.

Para copiar um adiamento usando o console, faça o seguinte:

  1. No painel de navegação do console do Google Cloud, selecione Monitoramento e  Alertas:

    Acessar Alertas

  2. Clique em Ver todos os adiamentos no painel Adiar.
  3. Na lista, encontre o adiamento que você quer editar e selecione Copiar adiamento no menu Mais opções.
  4. Aplique as modificações à cópia e clique em Criar.

A seguir