@tailowl/agent

Agent serveur Tailowl : CPU, RAM, disque, réseau, charge + heartbeat — export OTLP/JSON, zéro dépendance (Node ≥ 18).

Au premier battement, le serveur s'auto-enregistre dans la vue Serveurs de votre projet et apparaît en ligne tant que le heartbeat est frais (< 3 min).

Installation

npm i -g @tailowl/agent        # ou : pnpm add -g @tailowl/agent

Essai sans installation : npx @tailowl/agent --once --url … --key …

Utilisation

tailowl-agent --url https://<votre-instance> --key <clé API du projet>

L'agent envoie un lot de métriques toutes les 30 s par défaut. Pour un cron ou un timer systemd :

tailowl-agent --once --url https://… --key …    # un seul envoi puis quitte

En permanence sans Docker (service systemd)

Lancé à la main, l'agent s'arrête quand vous fermez la session SSH ou redémarrez le serveur. Le service fourni le relance tout seul (Node installé pour tout le système, ex. paquet nodejs ; pas via nvm). Une commande à la fois :

sudo npm i -g @tailowl/agent
sudo cp "$(npm root -g)/@tailowl/agent/tailowl-agent.service" /etc/systemd/system/
sudo install -m 600 /dev/null /etc/tailowl-agent.env
sudo nano /etc/tailowl-agent.env          # TAILOWL_URL=https://…  TAILOWL_KEY=…  TAILOWL_ENV=prod  (une par ligne)
sudo systemctl daemon-reload
sudo systemctl enable --now tailowl-agent
systemctl status tailowl-agent            # « active (running) »

La clé reste dans /etc/tailowl-agent.env (lisible par root seul) : elle n'apparaît ni dans ps ni dans l'historique du terminal. Le service tourne sans droits particuliers (utilisateur temporaire, système en lecture seule, 64 Mo max). Mise à jour : sudo npm i -g @tailowl/agent@latest, puis sudo systemctl restart tailowl-agent.

En conteneur Docker (recommandé sur un serveur qui utilise déjà Docker)

docker run -d --name tailowl-agent --restart unless-stopped --network host --read-only \
  -e TAILOWL_URL=https://<votre-instance> -e TAILOWL_KEY=<clé API du projet> \
  ghcr.io/<owner>/tailowl/agent:latest

--network host : l'agent voit les interfaces réseau et le nom de l'hôte ; CPU, RAM, charge et disque racine sont ceux de l'hôte.

Options

| Option | Description | Défaut | |---|---|---| | --url <url> | Base de votre instance Tailowl (TAILOWL_URL) | — | | --key <clé> | Clé API du projet (TAILOWL_KEY) | — | | --interval <sec> | Période d'envoi (min 10) | 30 | | --once | Un envoi puis quitte | — | | --host <nom> | Nom affiché dans la vue Serveurs | hostname | | --env <nom> | Environnement (prod, staging…) | — | | --service <nom> | Service principal hébergé | — |

Métriques publiées

| Métrique | Description | |---|---| | system.cpu.usage | % CPU global (delta des jiffies) | | system.mem.used / system.mem.total | RAM utilisée / totale (octets) | | system.disk.used / system.disk.total | Disque racine (octets) | | system.network.rx / system.network.tx | Débit par interface (octets/s, Linux) | | system.load.1 | Charge moyenne 1 min | | tailowl.host.heartbeat | Battement — auto-enregistre le serveur |

Attributs attachés au serveur : os.type, os.version, host.arch, host.cpu.cores, tailowl.agent.version, deployment.environment, service.name.

Quotas

Le nombre de points acceptés par minute dépend du plan (les points au-delà sont rejetés proprement via partial_success OTLP — jamais d'erreur 429). À 10 métriques / battement, un intervalle de 30 s consomme ~20 points/min.