Pular para o conteúdo principal
Versão: 0.4 · atual

Planejar uma janela de manutenção

Guia de instruçõesRevisado em 11 de outubro de 2026
Aplica-se a:Excubius 0.4Funções: Operador, Editor, Administrador de entidade
PlanosFree · Core · Pro · EnterpriseImplantaçãoAuto-hospedado

Uma janela de manutenção abrange um período em que se espera que os recursos se comportem mal: uma noite de patches, um teste de failover, uma migração. Durante a janela, o Excubius continua observando e registrando, mas não notifica ninguém. Este guia mostra as três formas de criar uma janela, pelo console e pela API.

Antes de começar​

  • Você precisa da função Operator (operador) ou superior na entidade. Os visualizadores podem ver as janelas, mas não criá-las.
  • Decida o escopo: uma entidade inteira (tudo o que está nela e abaixo dela) ou alguns recursos (e tudo o que foi descoberto abaixo deles, como os grupos de disponibilidade e os bancos de dados de uma instância).

Escolher como começar​

NecessidadeUse
O trabalho começa agora mesmoStart maintenance now: de 1 minuto a 7 dias
Uma noite planejadaSchedule a window › Once: início e término no horário do seu navegador, com até um ano de duração
Um horário de rotinaSchedule a window › Every week: dias da semana, horário local de início, duração e fuso horário

Agendar uma janela semanal​

  1. Abra Settings › Maintenance windows e escolha a entidade no seletor, por exemplo Veredas Ltda. › Produção.
  2. Selecione Schedule a window.
  3. Escreva o Reason. Ele é interno: aparece no console, nas linhas do tempo dos alertas e no log de auditoria, nunca na página de status.
  4. Escolha Every week.
  5. Escolha os Days, o Local start time, a Duration (minutes) e o Time zone, por exemplo sábado às 23:00 por 180 minutos em America/Santo_Domingo.
  6. Em Covers, mantenha All of Produção, que traz o nome da entidade escolhida, ou escolha Only some resources e selecione-os.
  7. Opcionalmente, selecione Announce on the status page e informe um Public title e uma Public description. Apenas esses dois textos são publicados.
  8. Selecione Save window. A janela aparece em Next 14 days.

Para uma janela única, escolha Once na etapa 4 e informe quando ela começa (Starts) e termina (Ends), no horário do seu navegador.

Iniciar a manutenção agora​

  1. Abra Settings › Maintenance windows e escolha a entidade.
  2. Em Start maintenance now, insira For (minutes) e o Reason, por exemplo 45 minutos e Aplicação de patches em sql-ventas-02 (mudança CHG-2231).
  3. Em Covers, mantenha a entidade inteira, por exemplo All of Produção, ou escolha Only some resources e selecione-os.
  4. Selecione Start now.

A janela aparece em Active now com o horário de término. Quando o trabalho terminar antes, selecione End now nela.

O que uma janela abrange​

EscopoAbrange
A entidadeTodos os recursos da entidade e de todas as entidades abaixo dela, conforme a árvore estiver a cada momento: os recursos adicionados ou movidos para o ramo depois também são abrangidos
Alguns recursosOs recursos selecionados, da entidade ou abaixo dela, e tudo o que foi descoberto abaixo deles: os grupos de disponibilidade, os bancos de dados e os servidores vinculados de uma instância

Um alerta gerado em uma instância sobre um dos bancos de dados ou servidores vinculados dela é abrangido quando esse filho é abrangido. Uma janela em um banco de dados silencia os alertas desse banco de dados, e não os do restante da instância.

O que acontece durante a janela​

  • Os recursos abrangidos mostram o estado Em manutenção em vez da integridade deles, nos cartões dos painéis, nas listas de recursos e na página do recurso.
  • As verificações continuam sendo executadas e as métricas continuam sendo armazenadas, de modo que o histórico fica completo e o estado real volta no momento em que a janela termina.
  • Um alerta que é aberto fica marcado com a janela e nada é enviado. A linha do tempo dele informa que foi aberto durante a manutenção.
  • Um alerta que se normaliza antes do fim é resolvido em silêncio, já que nada foi anunciado.
  • Um alerta ainda aberto quando a janela termina é anunciado nesse momento, como se tivesse acabado de abrir, pelo roteamento habitual, com o período de silêncio e os silenciamentos.
  • A linha do tempo do recurso registra quando cada janela começou e terminou e se alguém a encerrou antes.
observação

Uma janela de manutenção não é um silenciamento. Um silenciamento silencia um alerta existente por algum tempo; uma janela silencia tudo o que diz respeito a um conjunto de recursos durante um período, incluindo alertas que ainda não existem.

Janelas semanais e horário de verão​

  • Quando os relógios são adiantados, um horário de início que não existe começa logo após o salto.
  • Quando os relógios são atrasados, um horário de início que ocorre duas vezes usa a primeira ocorrência.
  • A duração é tempo decorrido, por isso uma janela que atravessa uma mudança termina uma hora mais cedo ou mais tarde no relógio de parede.
  • Uma janela pode atravessar a meia-noite ou o fim da semana: domingo às 23:00 por três horas termina na segunda-feira às 02:00. Uma ocorrência dura até uma semana.
  • End now em uma janela semanal encerra apenas a ocorrência atual; as próximas acontecem conforme o planejado. Editar o agendamento desfaz isso.

Alterar ou excluir uma janela​

All windows lista as janelas próprias da entidade, as das entidades abaixo dela e as herdadas dos ancestrais, marcadas com From e o nome da entidade. Cada uma tem ações de edição e exclusão.

Excluir uma janela ativa primeiro a encerra, e a linha do tempo dela mantém o início e o término. Os alertas que ela marcou mantêm a entrada na linha do tempo, mas perdem o link para a janela excluída.

Funções e auditoria​

AçãoFunção na entidade da janela
Ver as janelas ativas e futurasViewer
Criar, iniciar, editar, encerrar ou excluirOperator

Toda alteração é gravada no log de auditoria: maintenance.create, maintenance.start_now, maintenance.update, maintenance.end e maintenance.delete.

Pela API​

$BASE é https://<your server>/api/v1 e $TOKEN é o seu token de acesso; consulte Início rápido: adicionar uma instância do SQL Server com a API.

# a two-hour weekly slot for the whole Production branch
curl -sS -X POST "$BASE/maintenance-windows" -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{
"entity_id": "'"$PROD"'", "kind": "weekly", "reason": "Weekly index maintenance",
"weekly": {"days": ["sun"], "start_time": "02:00", "duration_minutes": 120,
"timezone": "America/Santo_Domingo"}}'

# sql-ventas-02 is being patched now, for 45 minutes
curl -sS -X POST "$BASE/maintenance-windows/now" -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{
"entity_id": "'"$PROD"'", "resource_ids": ["'"$SQL02"'"], "minutes": 45,
"reason": "Patching sql-ventas-02 (change CHG-2231)"}'

# done early
curl -sS -X POST "$BASE/maintenance-windows/$WINDOW/end" -H "Authorization: Bearer $TOKEN"
SolicitaçãoFinalidade
GET /maintenance-windows?entity={id}As janelas de uma entidade, com as das entidades abaixo dela e as herdadas; filtre com state=active,scheduled,ended
GET /maintenance-windows/active e /upcomingO que está em manutenção agora e o que vem a seguir
POST /maintenance-windowsCriar uma janela: kind é once (com starts_at e ends_at) ou weekly (com weekly); scope é entity ou resources (com resource_ids)
POST /maintenance-windows/nowIniciar uma agora por minutes, na entidade ou em resource_ids
PATCH /maintenance-windows/{id}Alterar qualquer campo
POST /maintenance-windows/{id}/endEncerrar agora a ocorrência ativa
DELETE /maintenance-windows/{id}Excluir uma janela; uma janela ativa é encerrada primeiro

Para anunciar uma janela na página de status, adicione "public": true com public_title e, opcionalmente, public_description. Uma janela semanal pode ser delimitada com starts_at e ends_at opcionais: contam apenas as ocorrências que começam entre essas datas. Uma janela única pode registrar o fuso horário em que foi planejada com timezone.