Monitoring as Code

Monitoring as Code

Monitoring as Code te permite definir tu configuracion de monitoreo de LoadFocus como archivos versionados y aplicarla desde la linea de comandos o CI, igual que gestionas la infraestructura con Terraform o Pulumi. Describes los monitores, grupos, alertas, ventanas de mantenimiento, paneles y paginas de estado que quieres; la CLI @loadfocus/monitoring calcula la diferencia con lo que esta en produccion y la reconcilia (crear, actualizar, eliminar).

Es declarativa e idempotente: ejecutar deploy dos veces no cambia nada la segunda vez. Tus archivos son la fuente de verdad, asi que los cambios pasan por pull requests y el historial de tu monitoreo vive en git.

Todo se ejecuta dentro de tu cuenta y tu equipo activo, con los limites de tu plan aplicados por el backend de LoadFocus exactamente igual que en el panel. La CLI solo hace lo que tu mismo podrias hacer en la interfaz.

Como funciona

Mantienes una carpeta de archivos YAML (o JavaScript) pequenos (un recurso por archivo) mas un loadfocus.config.yaml que apunta a ellos. La CLI envia esas definiciones a LoadFocus, que las mapea a recursos en produccion, las compara y devuelve un plan. Revisas el plan y luego lo aplicas.

  • Escribe — describe los recursos como archivos (constructos YAML o JS).
  • Planifica — deploy --dry-run muestra exactamente que se va a crear, actualizar, adoptar o eliminar.
  • Aplica — deploy reconcilia tu cuenta para que coincida con los archivos.
  • Reconcilia la identidad — cada recurso lleva un logicalId estable que tu eliges. Asi es como la CLI rastrea un recurso a traves de los cambios de nombre, de modo que cambiar el nombre visible de una comprobacion nunca la recrea.

Instalacion

La CLI es un paquete de Node (Node 18+). Ejecutala bajo demanda con npx:

npx @loadfocus/monitoring --help

…o instalala globalmente para obtener el comando loadfocus-monitoring:

npm install -g @loadfocus/monitoring
loadfocus-monitoring --help

Autenticacion

La CLI se autentica con una clave de API de LoadFocus y un id de equipo. Encuentra tu clave de API en el panel, en los ajustes de tu cuenta/API, y tu id de equipo en la pagina de equipos.

Inicia sesion una vez y las credenciales se guardan en ~/.loadfocus/config.json:

loadfocus-monitoring login
loadfocus-monitoring whoami        # confirm who you are and which team you're targeting

Para CI, prefiere las variables de entorno (anulan la configuracion guardada y nunca tocan el disco):

export LOADFOCUS_API_KEY="apikey_xxxxxxxx"
export TEAM_ID="team_xxxxxxxx"
# optional: export API_URL="https://apimonitor.loadfocus.com"

Crear un proyecto

Genera un archivo de configuracion y un monitor de ejemplo en tu repositorio:

loadfocus-monitoring init

Esto escribe loadfocus.config.yaml:

project: my-project          # a namespace for this set of resources
checkMatch:
  - "monitors/**/*.{check,group,alertRule,maintenanceWindow,dashboard,statusPage,alertChannel,variable}.{yaml,yml,js}"
defaults:
  schedule: "300"            # applied to checks that omit a schedule
  locations: [us-east-1]
  • project delimita todo lo que la CLI gestiona. Los recursos de un proyecto se reconcilian juntos; cualquier cosa del proyecto que ya no este en tus archivos se elimina en deploy. Usa proyectos separados para gestionar conjuntos independientes de monitores.
  • checkMatch es el glob (o los globs) de tus archivos de autoria.
  • defaults rellenan schedule, locations y alertChannels para las comprobaciones que los omiten.

El flujo de trabajo

loadfocus-monitoring validate          # compile locally + server-side dry-run; great as a PR gate
loadfocus-monitoring deploy --dry-run  # show the plan (created / updated / adopted / deleted)
loadfocus-monitoring deploy            # apply it
loadfocus-monitoring list              # inventory of what's deployed in the project
loadfocus-monitoring list --status     # …with each check's latest up/down/degraded status
loadfocus-monitoring get <logicalId>   # show one deployed resource
loadfocus-monitoring trigger <logicalId>   # run a check now
loadfocus-monitoring destroy           # delete everything managed in the project

deploy es seguro por defecto: muestra el plan y, cuando se ejecuta de forma interactiva, pregunta antes de eliminar nada. En CI (no interactivo), se niega a eliminar sin --yes y termina con un codigo claro en lugar de quedarse colgado en un prompt. Anade --json a los comandos de lectura/resultado para una salida legible por maquina.

Adoptar monitores existentes

Ya tienes monitores en el panel? Importalos a archivos en lugar de recrearlos:

loadfocus-monitoring import --project my-project --out monitors

Esto escribe un archivo por recurso y un loadfocus.config.yaml. Revisa, haz commit y luego ejecuta deploy --dry-run: los recursos coincidentes se adoptan en su lugar (quedan bajo gestion) en vez de duplicarse.

Recursos

Cada recurso es un archivo con un kind, un logicalId (tu identificador estable) y los campos de ese kind. Las referencias entre recursos usan logicalIds (o nombres para los canales de alerta); el servidor las resuelve y el orden de despliegue se gestiona por ti.

Comprobaciones

Un unico kind Monitor cubre todos los tipos de comprobacion mediante type: api, browser, multistep, tcp, heartbeat.

kind: check
type: api
logicalId: home
name: Home API
schedule: "300"            # seconds between runs
locations: [us-east-1, eu-west-1]
request:
  url: "https://example.com/health"
  method: GET
assertions:
  - { type: statusCode, comparison: equals, value: 200 }
  - { type: responseTime, comparison: lessThan, value: 1000 }
  • api — peticion HTTP con aserciones sobre estado, cuerpo, cabeceras, tiempo de respuesta y expiracion de SSL.
  • browser — un script de flujo de usuario de Playwright con capturas de pantalla y tiempos por paso (de pago).
  • multistep — una secuencia ordenada de peticiones de API que pasan datos entre pasos.
  • tcp — una comprobacion de puerto/alcanzabilidad desde varias regiones.
  • heartbeat — un interruptor de hombre muerto: un trabajo externo hace ping a una URL segun una programacion, y LoadFocus alerta si falta un ping.

Grupos

Comparte ubicaciones, canales de alerta, frecuencia y activacion entre muchas comprobaciones. Una comprobacion se une a un grupo con group: <logicalId>.

kind: group
logicalId: web
name: Web services
locations: [us-east-1, eu-west-1]

Reglas de alerta

Alerta cuando la metrica de una comprobacion cruza un umbral.

kind: alertRule
logicalId: home-latency
name: Home API latency
check: home               # reference a check by logicalId
metric: responseTime      # responseTime | statusCode | duration
condition: above
conditionValue: 1500      # milliseconds

Canales de alerta

Gestiona los canales de notificacion como codigo y referencialos por nombre desde una comprobacion, grupo o regla de alerta. Tipos (type) admitidos: email, slack, microsoftteams, webhook, discord, pagerduty, opsgenie. Los campos secretos (webhookUrl, routingKey, apiKey) toman una referencia {{secrets.NAME}}: el valor se almacena con env set-secret y se resuelve al enviar una alerta, nunca se incluye en tus archivos.

kind: alertChannel
logicalId: oncall          # the name checks / groups / alert rules reference
type: pagerduty
routingKey: "{{secrets.PAGERDUTY_KEY}}"

Ventanas de mantenimiento

Suprime las alertas durante el trabajo planificado. Las horas son UTC. startsAt / endsAt aceptan una cadena ISO-8601 (por ejemplo, "2026-07-01T00:00:00Z") o milisegundos unix.

kind: maintenanceWindow
logicalId: weekly-deploy
name: Weekly deploy window
enabled: true
startsAt: "2026-07-01T00:00:00Z"   # ISO-8601 or unix ms
endsAt: "2026-07-01T02:00:00Z"
repeat: weekly            # none | daily | weekly | monthly
weekdays: [2]             # 0=Sun … 6=Sat
targets:
  allChecks: false
  checkIds: [home]        # by logicalId

Paneles

Una vista compartida de comprobaciones seleccionadas, opcionalmente publica mediante un slug.

kind: dashboard
logicalId: status-overview
name: Status overview
visibility: private       # private | public
checks: [home]            # by logicalId
window: 24h               # 24h | 7d | 30d

Paginas de estado

Una pagina de estado publica en <slug>.loadfoc.us, opcionalmente en tu propio dominio personalizado.

kind: statusPage
logicalId: public-status
title: Acme Status
slug: acme                # -> acme.loadfoc.us (globally unique)
enabled: true
customDomain: status.acme.com   # optional, paid; point a CNAME at cname.loadfoc.us
groups:
  - { id: core, name: Core Services, order: 0 }
components:
  - id: api
    name: API
    groupId: core
    monitors: [home]      # checks shown on this component, by logicalId
branding:
  brandColor: "#5353a4"
  colorTheme: dark

Un dominio personalizado entra en funcionamiento una vez que creas el CNAME y se emite el certificado: deploy lo declara; la verificacion ocurre fuera de banda.

Variables

Valores no secretos (URLs base, IDs) que las comprobaciones referencian en tiempo de ejecucion como {{vars.NAME}}. El logicalId es la clave de la variable. (Para los secretos, usa env set-secret: nunca los pongas en archivos.)

kind: variable
logicalId: BASE_URL
value: "https://api.example.com"

Autoria en JavaScript o TypeScript

Si prefieres codigo en lugar de YAML, construye las mismas definiciones de forma programatica y exportalas: los constructos producen recursos identicos:

const { Monitor, Group, AlertRule, Maintenance, Dashboard, StatusPage, AlertChannel, Variable } = require('@loadfocus/monitoring');


new Monitor({
  type: 'api', logicalId: 'home', name: 'Home API', schedule: '300',
  locations: ['us-east-1'],
  request: { url: 'https://example.com/health', method: 'GET' },
  assertions: [{ type: 'statusCode', comparison: 'equals', value: 200 }],
});


new Group({ logicalId: 'web', name: 'Web services', locations: ['us-east-1'] });

Apunta checkMatch a tus archivos .js y la CLI los carga como cualquier otro recurso.

Secretos y variables

Referencia valores desde tus comprobaciones sin incluirlos en el repositorio. Los secretos (tokens, contrasenas) se gestionan unicamente de forma imperativa y se referencian como {{secrets.NAME}} en los campos de las comprobaciones y en los campos secretos de los canales de alerta. Las variables (no secretas) pueden declararse como archivos (kind: variable, arriba) o establecerse de forma imperativa, y se referencian como {{vars.NAME}}.

loadfocus-monitoring env set-secret API_TOKEN "s3cr3t"
loadfocus-monitoring env set-variable BASE_URL "https://example.com"
loadfocus-monitoring env ls            # list secret + variable keys (values never shown)

Ejecutarla en CI

Un pipeline tipico valida en cada pull request y despliega al hacer merge a la rama principal.

# .github/workflows/monitoring.yml
name: monitoring
on:
  pull_request:
  push:
    branches: [main]
jobs:
  monitoring:
    runs-on: ubuntu-latest
    env:
      LOADFOCUS_API_KEY: ${{ secrets.LOADFOCUS_API_KEY }}
      TEAM_ID: ${{ secrets.LOADFOCUS_TEAM_ID }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npx @loadfocus/monitoring validate
      - if: github.ref == 'refs/heads/main'
        run: npx @loadfocus/monitoring deploy --yes

Cosas que conviene saber

  • logicalId es la identidad. Mantenlo estable. Puedes renombrar libremente el name o el title de una comprobacion; cambiar su logicalId se trata como eliminar un recurso y crear otro.
  • Las eliminaciones se limitan al proyecto. deploy solo retira recursos del project actual que ya no estan en tus archivos, nunca nada de otro proyecto ni creado fuera de Monitoring as Code (hasta que lo adoptes).
  • Los slugs de las paginas de estado son globales. El slug se convierte en un subdominio, asi que debe ser unico entre todos los clientes de LoadFocus.
  • Las funciones de pago fallan de forma explicita. Un equipo gratuito que declare un campo solo de pago (un dominio personalizado en una pagina de estado, quitar la insignia "Powered by") recibe un error claro en deploy en lugar de un resultado parcial silencioso.
  • Se aplican los limites del plan. Crear recursos mediante la CLI esta sujeto a las mismas cuotas de plan que el panel.

Relacionado

Anterior
Importar desde Sitemap
Siguiente
Onboarding de LoadFocus