Zenovay status-agent

zenovay status-agent est un daemon en arrière-plan qui maintient un résumé Zenovay en direct — visiteurs actifs, MRR, taux d'erreur — dans votre barre de statut tmux, et qui peut déclencher des notifications de bureau lorsque des règles de seuil sont franchies. C'est le « tableau de bord toujours actif » pour les ingénieurs qui vivent dans le terminal.

Status-agent est une fonctionnalité pour utilisateurs avancés. Les mêmes données sont disponibles via zenovay live et le tableau de bord sur app.zenovay.com. Utilisez status-agent quand vous voulez une vue passive et ambiante, présente partout où vit votre terminal.

Démarrage rapide

# Démarrer le daemon — sondage toutes les 60 s, écrit ~/.zenovay/tmux-status
zenovay status-agent --daemonize

# Le brancher à tmux (~/.tmux.conf)
zenovay status-agent --install-tmux  # affiche la ligne de conf ; copiez + rechargez tmux

# Arrêter
zenovay status-agent --stop

Une fois le daemon démarré, votre barre de statut tmux affiche quelque chose comme :

● 142 live  ▲ MRR $48.7k  ✗ 3 err/s  14:02

Chaque segment est coloré — vert pour les visiteurs en direct, ambre pour le MRR, rouge pour les erreurs. Lorsqu'un seuil est franchi, le segment entier est brièvement affiché en vidéo inversée pendant 30 secondes, en signal visuel accompagnant la notification de bureau.

Règles de seuil

Passez --notify-on avec des règles key>value ou key<value séparées par des virgules :

zenovay status-agent --daemonize --notify-on "error_rate>5,revenue_drop>20"

Clés prises en charge :

Le déclenchement d'une règle entraîne :

1. La notification de bureau native de l'OS (voir plateformes de notification)
2. Le clignotement en vidéo inversée pendant 30 secondes dans le segment de statut tmux

Pour éviter le spam de notifications, le couple règle + bucket de valeur est limité à une alerte par tranche de 5 minutes. Ainsi un « error_rate>5 » durable ne se déclenche pas 60 fois en une heure — une fois lorsqu'il franchit le seuil pour la première fois, puis silencieux jusqu'à ce que la valeur passe dans un bucket différent.

Configuration persistante

--save-config écrit les options de l'invocation courante dans ~/.config/zenovay/config.json afin que vous n'ayez plus à les répéter :

# Enregistrer une fois
zenovay status-agent --notify-on "error_rate>5" --interval-ms 30000 --save-config

# Toutes les invocations suivantes reprennent la config enregistrée
zenovay status-agent --daemonize   # utilise error_rate>5 + 30000ms automatiquement

Inspecter la configuration enregistrée :

zenovay status-agent --show-config
# {
#   "refreshIntervalMs": 30000,
#   "notifyOn": "error_rate>5",
#   "notifierPlatform": "auto"
# }

Les options CLI prennent toujours le pas sur la configuration enregistrée pour une invocation donnée.

Démarrage automatique au boot

macOS — launchd

zenovay status-agent --install-launchd > ~/Library/LaunchAgents/com.zenovay.status-agent.plist
launchctl load ~/Library/LaunchAgents/com.zenovay.status-agent.plist

Linux — service utilisateur systemd

mkdir -p ~/.config/systemd/user
zenovay status-agent --install-systemd > ~/.config/systemd/user/zenovay-status-agent.service
systemctl --user enable --now zenovay-status-agent

Windows

Aucun helper de démarrage automatique pour le moment ; utilisez le Planificateur de tâches manuellement, ou lancez-le depuis une session shell d'autostart.

Plateformes de notification

Le daemon détecte votre plateforme et utilise le meilleur notifieur natif disponible, avec un fallback universel :

OSC 9 est une séquence d'échappement terminal qui fonctionne dans iTerm2, WezTerm, Windows Terminal, Konsole et la plupart des terminaux modernes — aucune installation supplémentaire requise. Les notifieurs natifs vous donnent des notifications toast au niveau OS qui survivent à la fermeture de la fenêtre du terminal ; OSC 9 ne se déclenche que si le terminal a le focus.

Si le notifieur natif n'est pas installé, le daemon retombe silencieusement sur OSC 9 — pas d'erreur, pas de notification ignorée.

Emplacements des fichiers

Cycle de vie

--daemonize fork un processus enfant détaché et retourne immédiatement. Les invocations --daemonize ultérieures refusent de démarrer un second daemon (cela provoquerait deux processus se disputant le fichier de statut) :

$ zenovay status-agent --daemonize
status-agent: already running (PID 12345). Use --stop first.

--stop lit le fichier PID, envoie SIGTERM et supprime le fichier. Inclut une vérification de vivacité pour éviter d'envoyer SIGTERM à un PID recyclé :

$ zenovay status-agent --stop
Stopped (PID: 12345)

L'arrêt est immédiat — la polling loop du daemon sort de son sommeil dès SIGTERM, plutôt que d'attendre jusqu'à 60 secondes le prochain tick. Les mises à jour du statut tmux s'arrêtent donc en quelques millisecondes après le retour de --stop.

Événements de télémétrie

Le daemon émet 4 événements de télémétrie (sous réserve de votre préférence d'opt-out zenovay telemetry) :

Cela nous aide à comprendre quels seuils les utilisateurs configurent réellement, et si la fonctionnalité mérite d'être développée davantage. Aucun ID de site, code de tracking ni valeur de métrique réelle n'est envoyé — uniquement les clés de règle et les buckets.

Dépannage

« no PID file — daemon not running? »

--stop a été lancé sans daemon actif. Idempotent — sûr à relancer.

La barre de statut n'affiche rien

Vérifiez que le fichier est bien écrit :

cat ~/.zenovay/tmux-status
# Devrait afficher : #[fg=colour141]● ...

Si le fichier est vide ou absent, le daemon n'est pas en cours d'exécution. Lancez zenovay status-agent --daemonize pour le démarrer. Si le fichier EST renseigné mais que tmux ne l'affiche pas, vous avez oublié la ligne de conf — zenovay status-agent --install-tmux la réaffiche.

Notifications muettes

Si vous êtes sur macOS sans terminal-notifier installé, OSC 9 ne se déclenche que lorsque le terminal d'origine a le focus. brew install terminal-notifier pour des toasts au niveau OS. Idem sur Linux : apt install libnotify-bin.

Le daemon plante / meurt entre les ticks

Vérifiez ~/.zenovay/status-agent.pid après quelques minutes. S'il a disparu, le daemon est mort. Lancez-le en avant-plan pour obtenir des stack traces : zenovay status-agent --child --interval-ms 5000.

Source et retours

Le code source du CLI est privé pour l'équipe Zenovay ; les binaires sont publics sur npm + GitHub Releases + le tap Homebrew. Les rapports de bug et les demandes de fonctionnalités sont les bienvenus sur community.zenovay.com.