Hogar/Documentos/Escucha

Contrato de seguimiento

Versión de contrato 2.0.0 · esquema de carga útil versión 2.0 · Planes de prueba/pago

El monitoreo pone a su extensión bajo vigilancia constante: un semáforo en vivo encendido su carta en la lista, una base escucha pestaña en Detalle y un mensaje de estado Telegram separado con alertas de borde. combina dos componentes habilitados de forma independiente: un empujar el latido del corazón (un agente en el host de su servicio informa en un horario declarado; el silencio es en sí misma una señal) y pings de tiempo de actividad (el panel comprueba su público URLs para disponibilidad).

1. Cómo funciona (dos componentes, una luz)

• Empujar el latido del corazón: un script cron en su host (por ejemplo, un script adaptado monitor.sh) POSTs un informe de métricas v2 al panel en el intervalo declaraste. Cada informe debe llevar el veredicto reservado overall. Los informes perdidos aumentan la luz (interruptor de hombre muerto): si el host, la red o cron muere, lo ves precisamente porque las llamadas se detienen.
• Pings de tiempo de actividad: el propio panel solicita periódicamente al público URLs que configura (sitio, api, documentos) y verifica solo la disponibilidad, nunca el contenido. No se necesita ningún agente, un URL es suficiente.

Una extensión está "en monitoreo" cuando el monitoreo está habilitado y al menos una componente está configurado. De lo contrario, su tarjeta muestra un punto gris neutro.

1b. Los latidos del corazón y el grupo de tragamonedas

El monitoreo vive a nivel de extensión como dos listas planas independientes que comparten un grupo de tragamonedas: latidos del corazon (empujar a los productores, anteriormente "stands") y pings de tiempo de actividad (tirar cheques). Una extensión puede tener varios latidos del corazón: por ejemplo, un anfitrión principal y un trabajador remunerado. Cada latido empuja informes con su propio token al portador y declara lo suyo presentación (pestañas, secciones y Telegram líneas) a través de su label. Los pings de tiempo de actividad son una lista plana separada propiedad de la extensión, no anidada bajo ningún latido del corazón. El panel fusiona todo en una luz agregada (la peor), una Superficie detallada y un mensaje resumido Telegram.

Los latidos y los pings comparten una única extensión por extensión. piscina de tragamonedas: uno un latido cuesta un espacio, un ping activo cuesta un espacio y su suma no debe exceder el max_slots del plan (Prueba 3 · Studio 10 · Fleet 25). Exceder el grupo devuelve 409 slot_limit; después de una rebaja el exceso está suspendido (los pings primero, los latidos al final). La respuesta lleva slots_used y max_slots para que la interfaz de usuario pueda mostrar el presupuesto.

2. El semáforo

El agregado es el lo peor de resumen en todos los habilitados componente del latido del corazón y la luz de cada ping activo, donde la gravedad se ordena como ok < warn < crit. El componente del latido del corazón es max(reported, watchdog): reported es la gravedad del overall métrica de la última aceptado informe; watchdog es un piso de frescura calculado a partir de la recepción del propio panel. reloj (la desviación del reloj del agente es inofensiva).

La gravedad es canónica ok | warn | crit. Los alias amigables se normalizan al ingresar: warning se convierte warn; error y critical se convierten en crit.

3. Perro guardián (latidos perdidos)

Usted declara el intervalo de informe esperado (60 s a 24 h) al habilitar el latido del corazón. A continuación, el perro guardián ilumina la luz con frescura, con grace = max(60s, 25% of the interval) para absorber el cron y la fluctuación de la red:

Un informe rechazado (401 / 422 / 429) nunca actualiza el mecanismo de vigilancia, por lo que un informe roto el agente escala honestamente; el último motivo del rechazo es visible en el configuración de monitoreo. La recuperación es instantánea: se vuelve a calcular el primer informe aceptado la luz inmediatamente.

4. Pings de tiempo de actividad

Un ping es una verificación de disponibilidad con nombre de un https URL público. el panel realiza GET con un tiempo de espera de 10 segundos, sigue como máximo 5 redirecciones, no lee ningún cuerpo más allá de un límite mínimo y trata un estado final de clase 2xx como éxito (204 y 206 también cuentan). una final 3xx (bucle o límite de redireccionamiento), 4xx, 5xx, tiempo de espera o DNS/TLS/error de red es un fracaso. Una verificación fallida se confirma mediante un reintento después de aproximadamente 15 segundos antes de que cuente, que absorbe las fluctuaciones de una sola red.

Los resultados del ping aparecen como métricas propias ping:<name> en el pings sección (Uptime) de la base escucha pestaña y como la línea reservada Telegram pings: 🟢 api 210ms · 🟢 site 90ms · 🔴 docs (timeout). La cantidad de pings por extensión y el intervalo mínimo dependen del plan:

El monitoreo en su conjunto es solo de prueba/pago; el intervalo mínimo de latidos es de 60 segundos en todos los planes.

5. Ampliar el seguimiento

En la extensión Ajustes, bloque de seguimiento:

• Active el monitoreo (planes de prueba/pago).
• Latido del corazón: habilítelo y declare el intervalo del informe; el panel emite al portador token de monitoreo, mostrado exactamente una vez (gírelo en cualquier momento; el token antiguo obtiene inmediatamente 401). Pon el token y el punto final. URL en el entorno de su agente.
• Pings: agregue URLs públicos con nombre (por ejemplo, site, api, docs) con un intervalo por ping, hasta el límite del plan.
• Telegram: habilita la supervisión de la entrega y, opcionalmente, establece un grupo/chat separado.

6. El formato del informe

El informe tiene la misma carga útil v2 basada en metadatos que el contrato de métricas personalizadas (pestañas, secciones, Telegram líneas, métricas), empujado a POST /api/v1/monitoring/report con Authorization: Bearer <monitoring token>. Monitoreo agrega identificaciones reservadas:

Límites: carga útil como máximo 64KB, como mucho 200 métricas, a lo sumo 2 informes por minuto por fuente (el exceso obtiene 429 y no no cuenta como un latido del corazón).

6.1. Informe de ejemplo

{
  "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": " · " } }
  ]
}

Respuesta exitosa:

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

7. Integración de un script de monitor (estilo monitor.sh)

Si ya ejecuta un script de verificación de estado cron, agregue un POST de mejor esfuerzo al final final de su tic. Un fallo en la entrega no debe romper el tic: el organismo de control De todos modos, capte un silencio prolongado.

# 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

Asigne la gravedad de su script al conjunto canónico (critical es aceptado y normalizado a crit) y alimente su lista de problemas existente en la métrica issues. Establecer el intervalo declarado igual al cron período.

8. Telegram: mensaje de estado y alertas separados

• Los datos de monitoreo van a Telegram como estado editable separado mensaje, distinto del estado de métricas personalizadas: encabezado + el línea reservada pings + las líneas que declara su informe.
• Opcionalmente, enrute el monitoreo a un grupo/chat separado; cuando no configurado, se utiliza el canal de chat de la extensión. El transporte del bot se comparte con el canal de la extensión.
• Alertas de borde fuego en cada cambio de color del agregado, en ambos direcciones, incluida la recuperación de regreso a verde (con la duración del incidente). mientras el color es estable hay silencio; cambios de configuración (pausar, editar pings) no alertes.

9. El contrato legible por máquina

La descripción formal del punto final del informe, el esquema de carga útil, el reservado Los identificadores y la semántica del semáforo son el archivo OpenAPI 3.1. lleva el misma versión de contrato (2.0.0).