Les passerelles d’agents sont des plans de contrôle : elles authentifient les outils, distribuent les appels modèles et appliquent les budgets. Les journaux racontent l’incident après coup, mais les métriques Prometheus révèlent une dérive progressive de latence avant la page. En 2026, les déploiements OpenClaw matures exposent un endpoint texte /metrics (ou un port admin jumeau) que les SRE scrapent avec une cardinalité prévisible, des noms cohérents et des exemplaires seulement quand le tracing est actif. Ce guide couvre la topologie de scrape, histogrammes contre summaries, hygiène des labels, l’alignement avec probes de santé et pipelines de logs, et la répétition sur un Mac mini loué via timers LaunchAgent calés sur la prod. Lisez aussi santé de la passerelle et monitoring, journalisation, rédaction et logrotate, checklist de migration et upgrade, et drainage de trafic nginx pour garder alertes, logs et métriques synchrones pendant les déploiements.
MacHTML propose des Mac mini Apple Silicon cloud autour de 16,9 USD par jour, ce qui permet un hôte de répétition dédié avec les mêmes jobs de scrape que la production.
Pourquoi Prometheus de premier plan
Contrairement aux applis monolithiques, les passerelles multiplexent des flux asynchrones : websockets d’outils, lots HTTP, retries fournisseurs et effets de bord disque. Un pic de p99 peut rester invisible sur le CPU agrégé car le travail saute entre workers. Compteurs et histogrammes Prometheus capturent volume d’erreurs, profondeur de files et fenêtres de backoff avec peu de surcoût si l’instrumentation est disciplinée. Sans eux, on ne taille que rarement les appels d’outils coûteux jusqu’à la facture.
OpenClaw vit des pannes partielles : un fournisseur ralentit pendant que d’autres restent sains. Il faut des fractions de succès par route sans milliers de combinaisons de labels—c’est le fil conducteur ci-dessous.
Conception du scrape /metrics
Ne servez pas les métriques sur le même socket que le trafic client sans mTLS et ACL strictes. Le schéma classique lie 127.0.0.1:9108 sur l’hôte passerelle et laisse un agent Prometheus scraper via tunnel SSH ou peering VPC. Si exposition distante, terminez TLS sur nginx avec certificats client d’une PKI interne.
scrape_configs:
- job_name: openclaw-gateway
scrape_interval: 15s
metrics_path: /metrics
static_configs:
- targets: ['gateway-prod.internal:9108']Respectez la sémantique de staleness Prometheus : si les scrapes échouent pendant un déploiement, les graphes doivent blanchir plutôt que mentir. Cadencez les intervalles avec systemd ou LaunchAgent pour éviter que le premier scrape post-boot tombe sur un pic JIT qui trompe l’autoscaler.
Histogrammes vs summaries en 2026
Les histogrammes natifs exposent des buckets structurés tandis que Prometheus calcule des quantiles cohérents entre réplicas. Les summaries côté client pré-calculent des quantiles non moyennables entre pods. Sur OpenClaw, préférez les histogrammes pour latence et durée d’outil, avec des bornes alignées sur les SLO (250ms, 500ms, 1s, 2s, 5s). Les summaries restent acceptables pour des SDK incontrôlables, mais ne mélangez pas les deux sur un même nom de métrique.
Les exemplaires relient les traces : n’attachez des trace IDs que si l’échantillonnage de queue le permet, et masquez les identifiants clients. Sur Mac de répétition, désactivez les exemplaires par défaut pour limiter la TSDB locale.
Cardinalité et budgets de labels
Chaque combinaison de labels est une série. Les passerelles poussent à étiqueter clés API, modèles, UUID ou chemins—interdit. Émettez des labels bornés comme provider="anthropic" ou region="us-west" et poussez la haute cardinalité vers les logs structurés déjà rédigés selon l’article de journalisation cité en introduction. Fixez un budget dur : moins de deux cents séries custom par process hors runtime Go.
Les recording rules agrègent par route : sum by (route)(rate(openclaw_tool_calls_total[5m])) est plus sûr que des IDs d’outil sauf enums fermées validées à la compilation.
Coupler métriques, probes et logs
Les métriques ne remplacent pas les sondes ; elles les complètent. Les probes répondent « le port répond-il ? », les compteurs « la file se vide-t-elle ? ». Câblez les tableaux pour corréler basculements rouges et gateway_errors_total. Pendant les upgrades (checklist liée en intro), suspendez l’autoscaler si le succès de scrape chute sous cinq neuf pendant deux intervalles.
Scrapes pendant les drains nginx
Les bascules roulantes déplacent le poids amont avant la fin des processus. Si la découverte de service retarde, Prometheus peut encore toucher des pods terminants. Utilisez des readiness gates pour retirer les endpoints dès le drain, comme dans l’article nginx cité en introduction. Si scrape via nginx, ajoutez un location dédié avec allowlist IP plutôt que de recycler des certificats publics à rotation décorrélée.
LaunchAgent pour scrapers locaux
Sur laptops et Mac mini cloud, LaunchAgent bat cron pour la précision et Unified Logging. Planifiez un curl léger vers /metrics chaque minute pour attraper les régressions d’exposition avant la CI.
<key>StartInterval</key>
<integer>60</integer>Gardez les agents non privilégiés ; ne stockez jamais de bearer tokens dans les plists—utilisez le trousseau macOS via un helper signé.
Répétition sur Mac cloud
Un Mac mini cloud reproduit l’ordonnanceur Apple, la sensibilité à la casse et la pile TLS. Copiez les jobs de scrape avec rétention courte, lancez un générateur de charge et surveillez la compaction TSDB. À environ 16,9 USD par jour, des soaks multi-jours deviennent raisonnables sans saturer le staging partagé.
Sécurité : TLS et séparation admin
Les métriques divulguent files, versions et états de disjoncteurs. Protégez-les par politiques réseau, tunnels SSH ou mesh zero trust. Si JSON debug coexiste, séparez les content-types et évitez qu’un DNS marketing n’expose un port admin.
SLO : burn rates et recording rules
Définissez des SLI sur latence et taux d’erreur, puis des alertes multi-fenêtres sur la combustion. Précalculez des fenêtres 5m/1h pour des dashboards réactifs. Calibrez sur incidents réels et reliez runbooks, panneaux PromQL et requêtes logs par identifiant de requête.
Matrice : exporter ou supprimer
| Signal | Exporter ? | Note |
|---|---|---|
| UUID par requête | Non | Logs rédigés. |
| Jauge de profondeur de file | Oui | Indispensable au backpressure. |
| Compteurs 429 par fournisseur | Oui | Labels bornés ; corréler Retry-After. |
| Échantillons tas | Non | pprof séparé avec auth. |
Checklist numérotée
- Inventorier les séries et supprimer celles hors budget.
- Aligner les buckets histogrammes sur les SLO et documenter les bornes.
- Finaliser TLS, ACL et relabel pour retirer les secrets d’environnement.
- Tester le drain pour que les pods terminés disparaissent avant scrape.
- Valider probes et métriques sous charge synthétique sur Mac cloud.
- Livrer des dashboards Grafana annotés par fenêtre de déploiement.
- Déployer des canaries LaunchAgent pour détecter la dérive d’exposition.
- Régler rétention et downsampling sur Prometheus de répétition.
FAQ
Prometheus sur l’hôte passerelle ?
Souvent non—scrapez vers une TSDB centralisée pour limiter le rayon d’explosion.
OpenTelemetry ?
Complémentaire ; traduisez en exposition Prometheus si PromQL est la norme.
Tester la cardinalité en CI ?
Prenez un snapshot du nombre de séries après tests d’intégration et échouez si de nouveaux labels arrivent sans revue.
Des métriques fiables prolongent la même culture que les probes de disponibilité et les logs structurés. Répéter les scrapes sur un Mac mini MacHTML à environ 16,9 USD par jour attrape TLS, réseau et timing avant la prod.
Répéter les métriques passerelle sur Mac mini cloud
Copiez les jobs de scrape, profilez la cardinalité TSDB et validez LaunchAgent sur macOS réel avant de fusionner l’observabilité.