Monitoring as Code

Monitoring as Code

Monitoring as Code vous permet de definir votre configuration de monitoring LoadFocus sous forme de fichiers versionnes et de l'appliquer depuis la ligne de commande ou la CI — de la meme facon que vous gerez votre infrastructure avec Terraform ou Pulumi. Vous decrivez les moniteurs, groupes, alertes, fenetres de maintenance, tableaux de bord et pages de statut que vous voulez ; la CLI @loadfocus/monitoring calcule la difference par rapport a ce qui est en production et la reconcilie (creation, mise a jour, suppression).

C'est declaratif et idempotent : executer deploy deux fois ne change rien la seconde fois. Vos fichiers sont la source de verite, donc les changements passent par des pull requests et l'historique de votre monitoring vit dans git.

Tout s'execute dans votre compte et votre equipe active, avec les limites de votre offre appliquees par le backend LoadFocus exactement comme dans le tableau de bord. La CLI ne fait que ce que vous pourriez faire vous-meme dans l'interface.

Comment ca marche

Vous conservez un dossier de petits fichiers YAML (ou JavaScript) — une ressource par fichier — plus un loadfocus.config.yaml qui pointe vers eux. La CLI envoie ces definitions a LoadFocus, qui les associe aux ressources en production, calcule le diff et renvoie un plan. Vous examinez le plan, puis vous l'appliquez.

  • Rediger — decrivez les ressources sous forme de fichiers (constructs YAML ou JS).
  • Planifier — deploy --dry-run montre exactement ce qui sera cree, mis a jour, adopte ou supprime.
  • Appliquer — deploy reconcilie votre compte pour qu'il corresponde aux fichiers.
  • Reconcilier l'identite — chaque ressource porte un logicalId stable que vous choisissez. C'est ainsi que la CLI suit une ressource a travers les renommages, de sorte que changer le nom d'affichage d'une verification ne la recree jamais.

Installation

La CLI est un package Node (Node 18+). Executez-la a la demande avec npx :

npx @loadfocus/monitoring --help

…ou installez-la globalement pour obtenir la commande loadfocus-monitoring :

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

Authentification

La CLI s'authentifie avec une cle d'API LoadFocus et un id d'equipe. Trouvez votre cle d'API dans le tableau de bord sous les parametres de votre compte/API, et votre id d'equipe sur la page des equipes.

Connectez-vous une fois et les identifiants sont enregistres dans ~/.loadfocus/config.json :

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

Pour la CI, preferez les variables d'environnement (elles ont priorite sur la configuration enregistree et ne touchent jamais le disque) :

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

Creer un projet

Generez un fichier de configuration et un moniteur d'exemple dans votre depot :

loadfocus-monitoring init

Cela ecrit 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 delimite tout ce que la CLI gere. Les ressources d'un projet sont reconciliees ensemble ; tout ce qui est dans le projet et qui ne figure plus dans vos fichiers est supprime au deploy. Utilisez des projets distincts pour gerer des ensembles de moniteurs independants.
  • checkMatch est le ou les globs de vos fichiers de redaction.
  • defaults renseigne schedule, locations et alertChannels pour les verifications qui les omettent.

Le workflow

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 est sur par defaut : il montre le plan et, lorsqu'il est execute de maniere interactive, demande avant de supprimer quoi que ce soit. En CI (non interactif), il refuse de supprimer sans --yes et se termine avec un code clair plutot que de rester bloque sur une invite. Ajoutez --json aux commandes de lecture/resultat pour une sortie exploitable par machine.

Adopter des moniteurs existants

Vous avez deja des moniteurs dans le tableau de bord ? Importez-les dans des fichiers au lieu de les recreer :

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

Cela ecrit un fichier par ressource et un loadfocus.config.yaml. Examinez, validez (commit), puis executez deploy --dry-run — les ressources correspondantes sont adoptees sur place (prises en gestion) plutot que dupliquees.

Ressources

Chaque ressource est un fichier avec un kind, un logicalId (votre identifiant stable) et les champs propres a ce kind. Les references entre ressources utilisent des logicalId (ou des noms pour les canaux d'alerte) — le serveur les resout, et l'ordre de deploiement est gere pour vous.

Verifications

Un seul kind Monitor couvre chaque type de verification via 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 — requete HTTP avec des assertions sur le statut, le corps, les en-tetes, le temps de reponse, l'expiration SSL.
  • browser — un script de parcours utilisateur Playwright avec captures d'ecran et chronometrages par etape (payant).
  • multistep — une sequence ordonnee de requetes API qui passent des donnees entre les etapes.
  • tcp — une verification de port/joignabilite depuis plusieurs regions.
  • heartbeat — un dispositif d'homme mort : un job externe ping une URL selon une planification, et LoadFocus alerte si un ping est manque.

Groupes

Partagez les regions, les canaux d'alerte, la frequence et l'activation entre plusieurs verifications. Une verification rejoint un groupe avec group: <logicalId>.

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

Regles d'alerte

Alerter quand une metrique d'une verification franchit un seuil.

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

Canaux d'alerte

Gerez les canaux de notification en tant que code et referencez-les par leur nom depuis une verification, un groupe ou une regle d'alerte. Types (type) pris en charge : email, slack, microsoftteams, webhook, discord, pagerduty, opsgenie. Les champs secrets (webhookUrl, routingKey, apiKey) acceptent une reference {{secrets.NAME}} — la valeur est stockee avec env set-secret et resolue lors de l'envoi d'une alerte, jamais versionnee dans vos fichiers.

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

Fenetres de maintenance

Supprimer les alertes pendant des travaux planifies. Les horaires sont en UTC. startsAt / endsAt acceptent une chaine ISO-8601 (par ex. "2026-07-01T00:00:00Z") ou des millisecondes 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

Tableaux de bord

Une vue partagee de verifications selectionnees, eventuellement publique via un slug.

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

Pages de statut

Une page de statut publique a <slug>.loadfoc.us, eventuellement sur votre propre domaine personnalise.

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 domaine personnalise est mis en service une fois que vous creez le CNAME et que le certificat est emis — deploy le declare ; la verification se fait hors bande.

Variables

Valeurs non secretes (URLs de base, identifiants) que les verifications referencent au moment de l'execution via {{vars.NAME}}. Le logicalId est la cle de la variable. (Pour les secrets, utilisez env set-secret — ne les placez jamais dans des fichiers.)

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

Rediger en JavaScript ou TypeScript

Si vous preferez le code au YAML, construisez les memes definitions de maniere programmatique et exportez-les — les constructs produisent des ressources identiques :

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'] });

Pointez checkMatch vers vos fichiers .js et la CLI les charge comme n'importe quelle autre ressource.

Secrets et variables

Referencez des valeurs depuis vos verifications sans les versionner. Les secrets (jetons, mots de passe) sont geres uniquement de maniere imperative et references via {{secrets.NAME}} dans les champs de verification et les champs secrets des canaux d'alerte. Les variables (non secretes) peuvent etre declarees sous forme de fichiers (kind: variable, ci-dessus) ou definies de maniere imperative, et sont referencees via {{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)

L'executer en CI

Un pipeline typique valide a chaque pull request et deploie a la fusion sur la branche principale.

# .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

Bon a savoir

  • logicalId est l'identite. Gardez-le stable. Vous pouvez renommer librement le name ou le title d'une verification ; changer son logicalId est traite comme la suppression d'une ressource et la creation d'une autre.
  • Les suppressions sont limitees au projet. deploy ne retire que les ressources du project courant qui ne figurent plus dans vos fichiers — jamais quoi que ce soit dans un autre projet ou cree en dehors de Monitoring as Code (jusqu'a ce que vous l'adoptiez).
  • Les slugs de page de statut sont globaux. slug devient un sous-domaine, il doit donc etre unique parmi tous les clients LoadFocus.
  • Les fonctionnalites payantes echouent bruyamment. Une equipe gratuite qui declare un champ reserve aux offres payantes (un domaine personnalise de page de statut, la suppression du badge « Powered by ») recoit une erreur claire au deploy plutot qu'un resultat partiel silencieux.
  • Les limites d'offre s'appliquent. Creer des ressources via la CLI est soumis aux memes quotas d'offre que le tableau de bord.

Associes

Précédent
Import depuis un Sitemap
Suivant
Onboarding LoadFocus