Lar/Documentos/Monitoramento

Contrato de monitoramento

Versão do contrato 2.0.0 · payload schema_version 2.0 · Planos de avaliação/pagos

O monitoramento coloca seu ramal sob vigilância constante: um semáforo aceso sua carta na lista, uma base monitoramento guia em Detalhe e uma mensagem de status Telegram separada com alertas de borda. Combina dois componentes habilitados independentemente: um empurrar batimento cardíaco (um agente no host do seu serviço relata uma programação declarada; o silêncio é em si um sinal) e pings de tempo de atividade (o painel verifica seu URLs públicos para disponibilidade).

1. Como funciona (dois componentes, uma luz)

• Empurre o batimento cardíaco: um script cron em seu host (por exemplo, um adaptado monitor.sh) POSTs um relatório de métricas v2 para o painel no intervalo você declarou. Cada relatório deve conter o veredicto reservado overall. Relatórios perdidos aumentam a luz (interruptor de homem morto): se o host, a rede ou o cron morre, você vê isso precisamente porque as chamadas param.
• Pings de tempo de atividade: o próprio painel solicita periodicamente ao público URLs você configura (site, api, docs) e verifica apenas a disponibilidade, nunca o conteúdo. Nenhum agente é necessário, um URL é suficiente.

Uma extensão está "em monitoramento" quando o monitoramento está habilitado e pelo menos um componente está configurado. Caso contrário, seu cartão mostra um ponto cinza neutro.

1b. Batimentos cardíacos e o pool de slots

Monitoramento de vidas no nível de extensão como duas listas planas independentes que compartilham um conjunto de slots: batimentos cardíacos (produtores push, anteriormente "stands") e pings de tempo de atividade (puxar cheques). Uma extensão pode ter vários batimentos cardíacos – por exemplo, um hospedeiro principal e um trabalhador remunerado. Cada batimento cardíaco empurra relata com seu próprio token ao portador e declara seu próprio apresentação (abas, seções e Telegram linhas) através de seu label. Os pings de tempo de atividade são uma lista simples separada de propriedade da extensão, não aninhada em nenhuma batimento cardíaco. O painel mescla tudo em uma luz agregada (o pior de), um Superfície de detalhes e uma mensagem de resumo Telegram.

Heartbeats e pings compartilham uma única extensão por extensão conjunto de slots: um pulsação custa um slot, um ping ativo custa um slot e sua soma não deve exceder o max_slots do plano (Teste 3 · Estúdio 10 · Frota 25). Exceder o pool retorna 409 slot_limit; após um rebaixamento o excesso está suspenso (os pings primeiro, os batimentos cardíacos por último). A resposta carrega slots_used e max_slots para que a IU possa mostrar o orçamento.

2. O semáforo

O agregado é o pior de roll-up em todos os habilitados componente de batimento cardíaco e luz de cada ping ativo, onde as gravidades são ordenadas conforme ok < warn < crit. O componente de um batimento cardíaco é max(reported, watchdog): reported é a gravidade do overall métrica do último aceito relatório; watchdog é um limite de atualização calculado a partir do recebimento do próprio painel clock (a distorção do relógio do agente é inofensiva).

A gravidade é canônica ok | warn | crit. Aliases amigáveis são normalizados na entrada: warning torna-se warn; error e critical tornam-se crit.

3. Watchdog (batimentos cardíacos perdidos)

Você declara o intervalo de relatório esperado (60s a 24h) ao habilitar o batimento cardíaco. O cão de guarda então ilumina a luz com frescor, com grace = max(60s, 25% of the interval) para absorver o cron e o jitter da rede:

Um relatório rejeitado (401/422/429) nunca atualiza o watchdog, portanto, um relatório quebrado o agente escala honestamente; o último motivo de rejeição é visível no configurações de monitoramento. A recuperação é instantânea: o primeiro relatório aceito recalcula a luz imediatamente.

4. Pings de tempo de atividade

Um ping é uma verificação de disponibilidade nomeada de um https público URL. O painel executa GET com um Tempo limite de 10s, segue no máximo 5 redirecionamentos, não lê nenhum corpo além de um limite mínimo e trata um status final da classe 2xx como sucesso (204 e 206 também contam). Uma final 3xx (loop ou limite de redirecionamento), 4xx, 5xx, tempo limite ou erro DNS/TLS/rede é um fracasso. Uma verificação com falha é confirmada por uma nova tentativa após aproximadamente 15s antes de contar, que absorve blips de rede únicos.

Os resultados do ping aparecem como métricas próprias ping:<name> no pings seção (Uptime) da base monitoramento guia e como a linha reservada Telegram pings: 🟢 api 210ms · 🟢 site 90ms · 🔴 docs (timeout). O número de pings por ramal e o intervalo mínimo dependem do plano:

O monitoramento como um todo é apenas experimental/pago; o intervalo mínimo de batimentos cardíacos é de 60 segundos em todos os planos.

5. Colocando uma extensão no monitoramento

Na extensão Configurações, bloco de monitoramento:

• Ative o monitoramento (planos de teste/pago).
• Batimento cardíaco: habilite-o e declare o intervalo do relatório; o painel emite um portador token de monitoramento, mostrado exatamente uma vez (gire-o a qualquer momento; o token antigo obtém imediatamente 401). Coloque o token e o endpoint URL no ambiente do seu agente.
• Pings: adicione URLs públicos nomeados (por exemplo, site, api, docs) com intervalo por ping, até o limite do plano.
• Telegram: ativar a entrega de monitoramento e, opcionalmente, definir um grupo/chat separado.

6. O formato do relatório

O relatório é a mesma carga útil v2 orientada por metadados que o contrato de métricas personalizadas (guias, seções, Telegram linhas, métricas), enviado para POST /api/v1/monitoring/report com Authorization: Bearer <monitoring token>. Adições de monitoramento IDs reservados:

Limites: carga útil no máximo 64 KB, no máximo 200 métricas, no máximo 2 relatórios por minuto por fonte (o excesso fica em 429 e não não conta como um batimento cardíaco).

6.1. Relatório de exemplo

{
  "schema_version": "2.0",
  "generated_at": "2026-07-12T10:19:58Z",
  "tabs":     [ { "id": "stand", "title": "Stand", "order": 5, "icon": "server" } ],
  "sections": [ { "tab": "stand",      "id": "docker", "title": "Docker", "order": 0 },
                { "tab": "monitoring", "id": "host",   "title": "Host",   "order": 10 } ],
  "telegram": { "header": "{sev} {name} monitoring",
                "lines": [ { "id": "host",   "order": 0, "prefix": "🖥 " },
                           { "id": "docker", "order": 1, "prefix": "📦 " } ] },
  "metrics": [
    { "id": "overall", "kind": "status", "state": "ok", "severity": "ok" },

    { "id": "issues", "kind": "list",
      "value": { "items": [ { "text": "RAM 91% (7.1/7.8G)", "severity": "warn" } ] },
      "dashboard": { "show": true, "tab": "monitoring", "section": "host", "order": 0,
                     "render": "list", "name": "Issues" },
      "telegram":  { "show": false } },

    { "id": "ram", "kind": "percent", "label": "RAM", "value": 91, "severity": "warn",
      "dashboard": { "show": true, "tab": "monitoring", "section": "host", "order": 1,
                     "render": "kpi" },
      "telegram":  { "show": true, "line": "host", "pos": 10,
                     "format": "RAM {value}%", "sep": " · " } }
  ]
}

Resposta bem sucedida:

{ "accepted": true, "effective": "green", "next_expected_by": "2026-07-12T10:26:13Z" }

7. Integrando um script de monitor (estilo monitor.sh)

Se você já executa um script de verificação de integridade do cron, adicione um POST de melhor esforço no final do seu tique. Uma falha na entrega não deve quebrar o tick: o watchdog irá pegar um silêncio prolongado de qualquer maneira.

# monitor.env
EXTOPS_REPORT_URL="https://extops.dev/api/v1/monitoring/report"
EXTOPS_REPORT_TOKEN="<monitoring token from Settings>"

# end of the tick: build the payload with jq from the values you already computed,
# then push it best-effort (never let delivery break the tick itself)
payload="$(jq -n --arg sev "$SEVERITY" '{
  schema_version: "2.0",
  generated_at: (now | todate),
  metrics: [ { id: "overall", kind: "status", state: $sev, severity: $sev } ]
}')"
curl -sS -m 10 -X POST "$EXTOPS_REPORT_URL" \
  -H "Authorization: Bearer $EXTOPS_REPORT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$payload" || true

Mapeie as gravidades do seu script para o conjunto canônico (critical é aceito e normalizado para crit) e alimentar sua lista de problemas existente na métrica issues. Defina o intervalo declarado igual ao cron período.

8. Telegram: mensagem de status e alertas separados

• Os dados de monitoramento vão para Telegram como um status editável separado mensagem, distinto do status das métricas personalizadas: cabeçalho + o linha reservada pings + as linhas declaradas pelo seu relatório.
• Opcionalmente, encaminhe o monitoramento para um grupo/chat separado; quando não definido, o chat do canal da extensão será usado. O transporte do bot é compartilhado com o canal da extensão.
• Alertas de borda disparar em cada mudança da cor agregada, em ambos direções, incluindo recuperação de volta ao verde (com duração do incidente). Enquanto a cor é estável, há silêncio; alterações de configuração (pausar, editar pings) não alerte.

9. O contrato legível por máquina

A descrição formal do endpoint do relatório, o esquema de carga útil, o reservado ids e a semântica do semáforo é o arquivo OpenAPI 3.1. Ele carrega o mesma versão do contrato (2.0.0).