
Strumento CLI per ispezionare e gestire i servizi in ascolto sulle porte di localhost
<div align="center">
```
██████ ███ ██████ ██ ██████
██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ████
██ ██ ██ ██ ██ ██ ██ ██
██████ ███ ██ ██ ██ ██ ██ ██
```
Know what's running on your machine.
</div>
Sonar mostra tutto ciò che è in ascolto su localhost e lo mette in ordine: ogni porta
appartiene a un **gruppo** — normalmente il repository da cui è stato avviato — e
all'interno di quel gruppo a un **servizio** con nome. Avvia i tuoi server di sviluppo con
`sonar start` e l'intero progetto diventa un'unica cosa che puoi elencare come un albero,
attendere, seguire e fermare con un singolo comando. Anche i container Docker, i progetti
Compose e i processi avviati manualmente vengono rilevati, senza alcuna
configurazione.
```
$ sonar list --tree
my-app (3 ports, running) ~/code/my-app
├─ 5432 db postgres:17 http://localhost:5432
├─ 5173 frontend vite (v5.4) http://localhost:5173
└─ 8000 api uvicorn app:app http://localhost:8000
ungrouped (1 port)
└─ 3000 next-server (v16.1.6) http://localhost:3000
```
## Installazione
### Homebrew (macOS / Linux)
```sh
brew install raskrebs/sonar/sonar
```
Homebrew 6 rifiuta le formule provenienti da tap di terze parti finché non ti fidi del tap una volta
(`Error: Refusing to load formula raskrebs/sonar/sonar from untrusted tap`):
```sh
brew trust raskrebs/sonar
```
### Script di installazione
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | bash
```
Scarica l'ultimo binario in `~/.local/bin` e lo aggiunge al tuo PATH se necessario. Riavvia il terminale o esegui `source ~/.zshrc`.
Su Windows (PowerShell):
```powershell
irm https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.ps1 | iex
```
Percorso di installazione personalizzato:
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | SONAR_INSTALL_DIR=/usr/local/bin bash
```
Installa una versione specifica:
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | SONAR_VERSION=vX.Y.Z bash
```
```powershell
$env:SONAR_VERSION="vX.Y.Z"; irm https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.ps1 | iex
```
### Utilizzo di Go
```sh
go install github.com/raskrebs/sonar@latest
```
Shell completions (tab-complete port numbers):
```sh
sonar completion zsh > "${fpath[1]}/_sonar" # zsh
sonar completion bash > /etc/bash_completion.d/sonar # bash
sonar completion fish | source # fish
```
## Sessanta secondi
Descrivi come viene eseguito il tuo progetto in un `sonar.yaml` nella radice del repository, al posto di un `dev.sh`:
```yaml
name: my-app
services:
- name: db
cmd: docker compose up db
port: 5432
- name: api
cmd: uv run uvicorn app:app --port ${port}
port: auto
depends_on: [db]
- name: frontend
cmd: npm run dev -- --port ${port} --strictPort
port: auto
depends_on: [api]
env:
VITE_API_URL: ${api.url}
```
Poi avvialo:
```sh
sonar start
```
```
✓ db http://localhost:5432 pid 41022 ~/.config/sonar/logs/my-app/db.log
✓ api http://localhost:21408 pid 41040 ~/.config/sonar/logs/my-app/api.log
✓ frontend http://localhost:21409 pid 41077 ~/.config/sonar/logs/my-app/frontend.log
3 started
following the logs; Ctrl+C stops the 3 services started here
api | INFO: Uvicorn running on http://127.0.0.1:21408
frontend | VITE v5.4 ready in 312 ms
```
Sonar sceglie una porta libera per ogni servizio `port: auto` e comunica a ciascun servizio dove si trovano gli altri, così un secondo worktree viene eseguito accanto al primo senza che una singola porta entri in conflitto. `sonar start -d` fa lo stesso in background, e `sonar down` lo arresta e restituisce le porte. In un altro terminale:
```sh
sonar list --tree
```
```
my-app (3 ports, running) ~/code/my-app
├─ 5432 db postgres:17 http://localhost:5432
├─ 21408 api uvicorn app:app http://localhost:21408
└─ 21409 frontend vite (v5.4) http://localhost:21409
```
Nessun `sonar.yaml`? `sonar start -- npm run dev` esegue un singolo comando come servizio con nome, e `sonar list` e `sonar kill` funzionano su qualsiasi cosa sia in ascolto.
Gli esempi seguenti contrassegnati con `# check` vengono eseguiti su una build appena creata da `scripts/readme-check.sh` a ogni esecuzione della CI.
## Comandi
### `sonar list`
```sh
sonar list
sonar list --tree
sonar list --group my-app
sonar list --json
# check
```
```sh
sonar list --stats # CPU, memory, threads, uptime, state
sonar list --health # HTTP health checks
sonar list --filter docker # only Docker ports
sonar list --sort name # port | pid | name | type
sonar list -a # include desktop apps
sonar list -c port,process,group,cpu,mem
sonar list --host user@server # scan a remote machine over SSH
```
Le colonne predefinite sono `port`, `process`, `group`, `container`, `image`,
`containerport`, `url`, dove `process` mostra il nome che hai assegnato alla porta
(`sonar rename`), poi il nome del servizio, poi ciò che è stato rilevato.
Colonne disponibili: `port`, `process`, `pid`, `type`, `url`, `group`, `cpu`,
`mem`, `threads`, `uptime`, `state`, `connections`, `health`, `latency`,
`container`, `image`, `containerport`, `compose`, `project`, `user`, `bind`,
`ip`.
Le app desktop e i servizi di sistema che si trovano in ascolto — Figma, Discord,
Spotify, ControlCenter, bundle `.app` di macOS, daemon in `/System/Library/` — sono
nascosti a meno che tu non passi `-a`.
### `sonar start`
Avvia un progetto dal suo `sonar.yaml`:
```sh
sonar start # every service in the nearest sonar.yaml
sonar start api frontend # only these (they still wait for their dependencies)
sonar start ../other-project # the sonar.yaml in or above another directory
sonar start -d # in the background, like `sonar up`
```
In primo piano, sonar avvia i servizi tramite il daemon, segue i loro
log con il nome del servizio davanti a ogni riga, e quando premi Ctrl+C
ferma i servizi che ha avviato. Un servizio già in esecuzione viene lasciato
in pace, e sonar ritorna da solo una volta che ogni servizio che ha avviato è terminato.
Gli argomenti prima di `--` indicano una directory o dei servizi; tutto ciò che segue `--` è un
comando. Oppure esegui un comando come servizio con nome in un gruppo:
```sh
sonar start -- npm run dev
sonar start --group my-app --name frontend -- npm run dev
sonar start --port 5173 -- npm run dev # expected port, before it binds
sonar start --detach --name api -- uv run uvicorn app:app
sonar start --list
```
Non deve essere passato nulla:
- **Group** — `--group`, altrimenti il `name` nel `sonar.yaml` più vicino, altrimenti il
nome della directory della radice git (un worktree diventa `repo@worktree`), altrimenti il nome
della directory corrente.
- **Name** — `--name`, altrimenti il servizio `sonar.yaml` il cui `cmd` corrisponde, altrimenti
inferito dal comando (`npm run dev` → `dev`, `uv run api` → `api`,
`python -m uvicorn` → `uvicorn`, `./dev.sh` → `dev.sh`).
- **Port** — `--port` è un suggerimento, non un binding: l'esecuzione appare come `starting`
finché la porta non è effettivamente in ascolto, e il daemon la usa per associare il
processo alla porta.
Il processo figlio eredita stdin, stdout, stderr, cwd e l'ambiente, più
`SONAR_GROUP`, `SONAR_NAME` e `SONAR_RUN_ID`. Ottiene il proprio process group,
così `sonar kill` abbatte l'intero albero — un dev server con i suoi watcher e
worker. Ctrl+C viene inoltrato, e sonar esce con il codice di uscita del figlio.
`--detach` ritorna immediatamente e scrive l'output in
`~/.config/sonar/logs/<group>/<name>.log`. `--list` mostra cosa ha avviato sonar,
e sotto di esso cosa è terminato nel frattempo — con il codice di uscita, e se è andato in crash
o è stato fermato (`--json` per la forma leggibile dalla macchina):
```sh
sonar start --list
sonar start --detach --name demo --port 8123 -- sleep 5
sonar start --list --json
# check
```
### `sonar.yaml`
Un progetto assegna un nome a sé stesso e ai suoi servizi in un `sonar.yaml` nella radice del repository. È opzionale — sonar raggruppa per radice git anche senza di esso — ed è pensato per essere committato:
```yaml
name: my-app
services:
- name: db
cmd: docker compose up db
port: 5432
health: /
description: Postgres 17
icon: database
color: "#4f8cc9"
- name: api
cmd: uv run uvicorn app:app --port 8000
cwd: backend
port: 8000
health: /healthz
depends_on: [db]
- name: frontend
cmd: npm run dev
port: 5173
depends_on: [api]
ports: [9229] # ports that belong to this project without a service
```
- `name` — il nome del gruppo. Nessuna barra, nessuno spazio bianco.
- `cmd`, `cwd`, `port` — come `sonar start` avvia il servizio. `cwd` è relativo
al file e non può uscire dalla sua directory.
- `health` — un percorso HTTP che il daemon interroga mentre il servizio è attivo, così un
servizio può essere *in esecuzione* ma non ancora *integro*. Riporta `ok`, `fail` o
`unknown`, con il motivo di un fallimento.
- `description`, `icon`, `color` — metadati liberi per l'app desktop; sonar
non li deduce mai.
- `depends_on` — ordine di avvio. Nominare un servizio che non è nel file, o un
ciclo, è un errore; un file non valido viene segnalato una volta e non interrompe mai una scansione.
- `env` — variabili impostate per il servizio quando sonar lo avvia.
#### `port: auto` e riferimenti
Un servizio può lasciare la sua porta a sonar, e trovare gli altri attraverso il suo
ambiente invece di un `localhost:8080` codificato:
```yaml
services:
- name: api
cmd: uv run uvicorn app:app --port ${port}
port: auto
- name: frontend
cmd: npm run dev -- --port ${port} --strictPort
port: auto
depends_on: [api]
env:
VITE_API_URL: ${api.url}
```
`sonar start` riserva una porta libera per ogni servizio `port: auto` che avvia: la
stessa ogni volta nello stesso checkout, e una diversa in ogni altro
checkout, così un worktree non entra mai in collisione con quello principale. Il servizio la riceve
come `PORT`, `SONAR_PORT` e `${port}`, e deve usarla — leggere `PORT`, o
passare `${port}` sulla sua riga di comando. Un servizio già in esecuzione mantiene
la sua porta, così uno avviato dopo la trova comunque. La prenotazione dietro una porta assegnata
dura un giorno dall'ultimo avvio; `claims.ttl` lo cambia (vedi Il
daemon).
`${port}` e `${url}` (`http://localhost:<port>`) sono del servizio stesso;
`${<service>.port}` e `${<service>.url}` sono di un altro. Funzionano in `cmd`
e in `env`. Un riferimento a un servizio che non è nel file, o a uno senza
porta, è un errore quando il file viene caricato. Qualsiasi altra cosa tra `${` e
`}`, come `${HOME}`, viene lasciata esattamente come scritta.
`sonar.yml` viene letto se è così che lo scrivi; `sonar init` scrive sempre
`sonar.yaml`. Il file era il dotfile `.sonar.yaml`, e quel nome
funziona ancora: sonar cerca `sonar.yaml`, `sonar.yml`, `.sonar.yaml` e
`.sonar.yml`, in quest'ordine, e legge il primo che trova. Le modifiche tornano
al file che sonar ha letto, così nulla viene rinominato alle tue spalle. `sonar doctor`
segnala un file con il vecchio nome, e `sonar doctor --fix` lo rinomina
(con `git mv` quando il file è tracciato). Il daemon osserva i progetti che conosce e recepisce
le modifiche al file senza un riavvio. Ogni modifica che sonar fa — dall'app
desktop, da `sonar groups add`, `rename` e `remove`, da un agente — passa
attraverso il daemon, che rigenera il file dal proprio albero sintattico, così
commenti, ordine delle chiavi e layout sopravvivono a una modifica che aggiunge, rinomina o rimuove un
servizio proprio come sopravvivono a un cambiamento di metadati. L'unica eccezione: gli spazi extra
che allineano un commento in coda (`cmd: x # note`) collassano a uno, perché la
libreria YAML conserva il commento ma non la sua colonna.
#### `sonar env`
Ciò a cui il file si risolve è leggibile senza avviare nulla:
```sh
sonar env # every service: port, url and its expanded env
sonar env frontend # one service, as export lines
sonar env --json # for tools
```
```
SERVICE PORT URL ENV
db 5432 http://localhost:5432
api 21408 http://localhost:21408 DB_URL=postgres://localhost:5432/app
frontend 21409 http://localhost:21409 VITE_API_URL=http://localhost:21408
```
Un servizio `port: auto` che non è in esecuzione riceve qui la sua assegnazione, la stessa assegnazione che effettua `sonar start`, quindi ciò che stampa `sonar env` è ciò a cui si legherà un successivo avvio; un servizio già in esecuzione mantiene la porta su cui si trova. Se nominato, un servizio viene restituito come righe `export`, così una shell può vedere cosa farebbe il servizio:
```sh
eval "$(sonar env frontend)" && npm test
```
Dietro di esso c'è `groups.env` sul daemon, per un editor o un agente che collega
un worktree prima che i suoi servizi esistano.
### `sonar up`
```sh
sonar up # the sonar.yaml at or above this directory
sonar up my-app # a group by name
sonar up --only api,frontend
sonar up --json
```
`sonar up` è `sonar start -d`, che può anche nominare un gruppo da qualsiasi posizione e
avviarlo su un altro host. Avvia ogni servizio che il `sonar.yaml` del gruppo
dichiara, nell'ordine di `depends_on`:
un servizio attende le porte dichiarate dalle sue dipendenze prima di essere avviato, e
uno che è già in ascolto viene saltato. Ognuno viene eseguito in modo detached nel proprio process
group, con il suo output in `~/.config/sonar/logs/<group>/<service>.log`, e con
l'ambiente della shell in cui hai eseguito `sonar up`, più `PORT` per un servizio
con una porta.
```
✓ db http://localhost:5432 pid 41022 ~/.config/sonar/logs/my-app/db.log
- api already running
✓ frontend http://localhost:5173 pid 41108 ~/.config/sonar/logs/my-app/frontend.log
2 started, 1 already running
```
Un servizio che non riesce ad avviarsi viene segnalato su una riga dedicata e fa sì che il comando
esca con codice diverso da zero, qualunque altra cosa sia accaduta. Arrestali tutti di nuovo con `sonar down`.
`sonar up` necessita del daemon e lo avvia se non è già in esecuzione.
### `sonar down`
```sh
sonar down # the project in the nearest sonar.yaml
sonar down my-app # a group by name
sonar down --only api,worker # only these services
```
Ferma ogni servizio del progetto — ogni porta su cui è in ascolto, e ogni
servizio che sonar ha avviato per esso che non occupa una porta, come un worker — e rilascia
le porte che sonar ha rivendicato per i suoi servizi `port: auto`. `--only` limita tutto
ciò ai servizi indicati, come `sonar up --only` avvia solo alcuni; un nome
che il file non dichiara è un errore. `sonar kill -g my-app` ferma le porte
e non rilascia nulla.
### `sonar groups` e `sonar init`
```sh
sonar init --dry-run
sonar init --service api:8000:/healthz --service web:5173
sonar groups
sonar groups --json
group=$(basename "$PWD") # sonar init names the group after the directory
sonar groups add "$group" worker --port 9000 --cmd 'uv run worker' --depends-on api
sonar groups rename "$group" worker jobs
sonar groups remove "$group" jobs
# check
```
`sonar groups` elenca ogni gruppo che sonar riesce a vedere e da dove proviene ciascun nome:
`manual` (l'hai fissato con `sonar assign`), `start` (un'esecuzione di `sonar start`),
`file` (un `sonar.yaml`) o `auto` (la radice git o il progetto Compose).
`sonar groups <name>` mostra le porte e i servizi di un gruppo, e i servizi
dichiarati ma non in esecuzione.
`sonar init` scrive un `sonar.yaml` nella radice git da ciò che riesce a dichiarare: le
porte in ascolto all'interno del progetto in questo momento (app desktop e porte sotto 1024
escluse), più ciò che un file compose o un `package.json` dichiara esplicitamente — un
servizio per ogni servizio compose, con la sua porta pubblicata e il suo `depends_on`, e
lo script `dev` eseguito da qualunque package manager a cui il tuo lockfile ti vincola.
Dove i due sono in disaccordo, vince la porta in ascolto: è una prova, non una
dichiarazione. Il file che scrive dice ciò che non è riuscito a determinare.
Nient'altro viene rilevato. Un target di un Makefile, una riga di un Procfile, un entry point
sepolto in un framework — quelle sono congetture sul tuo repository, e una tabella di
queste non sarebbe mai completa. Quella parte spetta a un agente:
```sh
sonar init --agent # whichever agent is installed
sonar init --agent codex # name one
sonar init --agent claude -- --allow-dangerously-skip-permissions
```
`--agent` apre l'agente di coding che hai già, in questo terminale, con il
prompt già inviato: ciò che sonar sa, la bozza che avrebbe scritto, il
formato, e la regola che scrive il file e non avvia nulla. Lo osservi mentre
legge il repository e approvi le sue modifiche esattamente come fai sempre — è il tuo
agente, sotto i tuoi permessi — e qualsiasi cosa dopo `--` gli viene passata. sonar
conosce `claude`, `codex`, `cursor-agent` e `opencode`; con diversi installati,
indicane uno. Quando l'agente esce, sonar carica il file e stampa i servizi che
dichiara, o perché non si carica. Senza un terminale — una pipe, CI — `--agent`
stampa il prompt invece di avviare qualsiasi cosa.
Rifiuta di sovrascrivere senza `--force`, e `--dry-run` stampa il file
invece di scriverlo. `--merge` aggiunge a un file già esistente
invece di rifiutare, e `--service name:port[:health]` — ripetibile — scrive
i servizi che indichi invece di quelli che ha trovato, mantenendo il comando che
ha indovinato per una porta che hai mantenuto. `--force` e `--merge` sono mutuamente esclusivi.
`sonar groups add <group> <name> --port N` aggiunge un servizio al `sonar.yaml` di quel gruppo,
con `--cmd`, `--cwd`, `--health`, `--description`, `--icon`,
`--color` e un `--depends-on` ripetibile per il resto. `sonar groups
rename <group> <old> <new>` rinomina uno ovunque nel file,
riferimenti `depends_on` inclusi, e `sonar groups remove <group> <name>` ne elimina uno e
lo rimuove da ogni `depends_on` che lo nominava. Tutti e tre rifiutano una modifica che
renderebbe il file non valido — un nome duplicato, una porta che un altro servizio già
rivendica, un servizio che non c'è — e nessuno di essi scrive un byte finché
l'intera modifica non è nota come valida.
Il daemon fa la scrittura, ed è per questo che il file torna con i suoi commenti
e l'ordine delle chiavi intatto, sia che la modifica provenga dalla CLI, dall'app desktop o da un
agente. `sonar groups add`, `rename` e `remove` richiedono il daemon e lo avviano se
non è già in esecuzione; i tre nomi sono sottocomandi, quindi un gruppo effettivamente
chiamato `add` si legge con `sonar groups --json`.
### `sonar kill`
```sh
sonar kill 3000 # SIGTERM, then SIGKILL after 5s
sonar kill 3000 5432 -f # SIGKILL both straight away
sonar kill 3000 --tree # the listener and everything below it
sonar kill --pid 12345 --tree # by process id
sonar kill -g my-app # a whole group, confirms unless -y
sonar kill --all --filter docker -y # every container publishing a port
sonar kill --all --project my-app # one Compose project
sonar kill 3000 --ip 127.0.0.1 # one bind address of several
sonar kill --all --dry-run --json # the plan for the whole machine
```
`--dry-run` accetta qualsiasi selettore e non modifica nulla: stampa le azioni che
il kill eseguirebbe, prima i figli, e lascia tutto in esecuzione. End to end,
contro un listener tuo:
```sh
sonar start --detach --name plan --port 8231 -- sonar map 3000 8231
sonar wait 8231
sonar kill 8231 --dry-run --json # the plan; the mapping keeps running
sonar kill 8231 -y # and now for real
# check
```
Un argomento posizionale viene letto come porta, e come pid solo quando nulla è
in ascolto su quel numero. `-g` corrisponde al gruppo risolto, a un tag o id di
esecuzione legacy, e al progetto Compose, senza distinzione tra maiuscole e minuscole.
Un processo che ignora SIGTERM riceve SIGKILL una volta che la porta è ancora in ascolto
dopo `--grace` (5s); `--no-escalate` disattiva questa opzione. I figli vengono segnalati
prima dei genitori, così un albero viene abbattuto in ordine. I container Docker vengono fermati
con `docker stop` e non vengono mai segnalati. Un listener avviato da `sonar start` viene
sempre fermato insieme al suo process group.
`--json` stampa una riga per processo:
`{port, bind_address, pid, name, method, ok, error}`, dove `method` è
`sigterm`, `sigkill`, `docker_stop`, `map_stop` o `none`. Una sweep vuota esce
con 0; un gruppo sconosciuto esce con 1.
### `sonar map`
```sh
sonar map 6873 3002 # also serve the service on 6873 from port 3002
```
Esegue un proxy TCP in primo piano finché non lo si interrompe. `sonar kill` segnala una
mappatura che ha interrotto come `map_stop`.
### `sonar rename`, `sonar assign`, `sonar history`
```sh
sonar rename 3000 storefront # a name of your own, survives restarts
sonar rename 3000 --clear
sonar assign 3000 my-app # pin a port to a group by hand
sonar assign 3000 --clear
sonar history # everything that came up, went down, restarted
sonar history 3000 --since 24h --limit 20
```
```sh
sonar history --since 1h
sonar history --json
# check
```
I nomi e i pin sono memorizzati nel database di sonar, indicizzati in base alla cosa più specifica nota sulla porta: l'esecuzione (`run:<group>/<name>`), il container (`docker:<project>/<service>`), la directory di lavoro e, per ultimo, il numero di porta. Un dev server rinominato mantiene il suo nome tra i riavvii; un nome associato alla sola porta 3000 si applica a qualunque cosa risponda lì. Questi tre comandi richiedono il daemon e lo avviano se non è in esecuzione.
### Leggere una porta
```sh
sonar info 3000 # command, user, bind, stats, health
sonar logs 3000 # tail; docker logs for containers
sonar wait 5432 3000 --timeout 60s # block until ready
sonar wait 5432 --http=/health # wait for HTTP 200-399, not just TCP
sonar next 3000 # first free port from 3000
sonar next 3000-3100 -n 3 # three consecutive free ports
sonar graph # who is connected to whom
sonar graph --dot # Graphviz
sonar open 3000 # open in the browser
sonar attach 3000 # shell into the container, or TCP
sonar watch # live view
sonar watch --stats --notify
```
```sh
sonar next 3000
sonar next 3000-3100 -n 3 --json
sonar graph --json
sonar info --help
# check
```
`sonar wait` esce con `0` (pronto), `1` (timeout) o `2` (interrotto), il che lo rende
l'elemento da inserire tra l'avvio di qualcosa e il suo test:
```sh
docker compose up -d
sonar wait 5432 3000 --timeout 60s && npm run migrate && npm run test
```
**Daemon o scansione diretta.** Ogni comando di lettura chiede al daemon se ne è in esecuzione uno, perché ha già la risposta e non deve fare il fork di `lsof`. Se nessuno è in esecuzione, eseguono la scansione direttamente e stampano una nota su stderr per segnalarlo. `sonar kill` segue la stessa regola: un daemon raggiungibile esegue l'uccisione, quindi riesegue immediatamente la scansione e la sua risposta successiva — e la cronologia delle porte — sa già che la porta è sparita. Né le letture né le uccisioni avviano un daemon alle tue spalle. `--no-daemon` forza la scansione diretta in modo silenzioso e funziona su qualsiasi comando:
```sh
sonar list --no-daemon --json
# check
```
### `sonar host`
```sh
sonar host # cpu, load, memory and disk of the machine sonar watches
sonar host --json
```
```sh
sonar host
# check
```
Il daemon misura la propria macchina secondo la cadenza di scansione e la pubblica come
riga `localhost` della collezione `hosts` dello snapshot: os e kernel, uptime, percentuale
cpu, load average, memoria e il disco che contiene `/`. La percentuale CPU è il lavoro
svolto tra due scansioni, quindi è null finché il daemon non ha scansionato due volte; un
valore che una piattaforma non può produrre — il load average su Windows, che non ne ha —
è null anziché zero. Ogni host registrato con `sonar remote add` entra
nella stessa tabella con il proprio carico. Il comando necessita di un daemon in esecuzione: è il
daemon che conserva il campione precedente rispetto al quale viene misurata una percentuale.
Le GPU sono elencate sotto il loro host con utilizzo e memoria: da `ioreg` su
macOS (la memoria Apple silicon è unificata, quindi viene mostrato solo ciò che la GPU detiene),
e da `nvidia-smi` o dai contatori sysfs di amdgpu su Linux. Il daemon le legge
ogni cinque secondi in background, mai sul percorso di un comando; `gpus` è null
dove non c'è una sorgente (Windows, Linux solo Intel) e `[]` su una macchina
senza GPU.
### `sonar remote install`
```sh
sonar remote install [email protected] # same version as this sonar
sonar remote install hetzner --version v0.6.0 # a Host from ~/.ssh/config
sonar remote install deploy@box --no-service # the binary, no daemon
```
Mette sonar su un host a cui puoi già accedere via ssh e avvia il suo daemon lì. L'archivio di rilascio viene scaricato e verificato con checksum **sull'host remoto** — nulla viene copiato da questa macchina — e il binario finisce in `~/.local/bin/sonar`, quindi nulla di tutto ciò richiede root. Il daemon viene eseguito come unità utente systemd dove l'host ne dispone (`~/.config/systemd/user/sonar.service`), e in modalità detached dove non ne dispone; `loginctl enable-linger` viene stampato come consiglio quando la sessione utente terminerebbe al logout portandosi via il daemon.
La versione installata è la versione del sonar da cui è stato eseguito, così le due estremità parlano lo stesso protocollo. Eseguirlo di nuovo aggiorna sul posto e riavvia il daemon, ed è ciò che rende un'installazione e un aggiornamento lo stesso comando.
Il target viene passato a `ssh` senza modifiche: un alias `Host` da `~/.ssh/config` funziona, e così anche `ProxyJump`, `IdentityFile` e `Port` che imposta. `--identity` e `--ssh-arg` sono lì per i flag che una configurazione non copre.
### `sonar remote`
```sh
sonar remote add [email protected] # name taken from the target
sonar remote add hetzner [email protected] # or given
sonar remote list # status, latency, version, load
sonar remote remove hetzner
sonar list --host hetzner # that host's ports
sonar list --host "*" # every host, with a HOST column
sonar info 3000 --host hetzner
```
Un host registrato esegue lo stesso daemon, e il daemon su questa macchina mantiene
una connessione SSH verso di esso — `ssh <target> sonar daemon stdio`, cercando in
`~/.local/bin` prima del `PATH` remoto — e multiplexa
ciò che riporta nello stato che ogni client già legge. Nulla di nuovo resta in ascolto
da nessuna parte: il socket del daemon remoto rimane privato all'utente SSH, e i client
non parlano mai direttamente SSH.
Ogni riga ora porta con sé l'host da cui proviene. Le righe locali dicono `localhost` e
mantengono le chiavi che hanno sempre avuto, quindi nulla di ciò che legge sonar oggi cambia;
le righe remote dicono il nome registrato e sono indicizzate come `<host>/<port>:<bind>`, che
è ciò che permette alla porta 3000 su due macchine di essere due righe. Un subscriber vede solo
localhost a meno che non chieda di più (`state.subscribe {"hosts": ["*"]}`).
Il target viene passato a `ssh` inalterato, quindi alias di `~/.ssh/config`, `ProxyJump` e
identità si applicano tutti; `--ssh-arg`, `--identity` e `--port` coprono ciò che una config
non fa, e `--remote-bin` indica un sonar che si trova altrove. Il comando predefinito viene eseguito
tramite `sh`, quindi un host Windows, il cui sonar proviene dall'installer
PowerShell, necessita di `--remote-bin sonar`. sonar non memorizza né password né chiavi. Un host che
scompare mantiene la sua riga e il suo stato mentre il daemon ritenta, con backoff da un secondo a
trenta finché rimane registrato.
`--host` accetta anche un semplice `user@host` che sonar non conosce: ricade
sulla scansione agentless `ssh` + `ss`/`lsof` e stampa un suggerimento verso
`sonar remote install`.
#### Agire su un'altra macchina
Ogni scrittura accetta anch'essa `--host`, e lì fa esattamente ciò che fa qui:
```sh
sonar kill 3000 --host hetzner # stop a port on that machine
sonar kill -g api --host hetzner # a whole group of its services
sonar kill --all --filter docker --host hetzner # its containers
sonar up api --host hetzner # start a group from its sonar.yaml
sonar logs 3000 --host hetzner # tail its output here
sonar rename 3000 storefront --host hetzner # its name, in its database
sonar assign 3000 storefront --host hetzner
```
Il daemon locale inoltra la chiamata attraverso il bridge di quell'host e restituisce ciò che
il daemon remoto ha risposto, nello stesso envelope che restituisce una chiamata locale — ogni
riga di risultato indica su quale host è avvenuta, e l'`affected` di un kill porta le
chiavi `<host>/<port>:<bind>` che lo stream usa per quelle righe. Un comando in streaming
fa streaming: `sonar up --host` stampa ogni servizio man mano che il lato remoto lo avvia, e
Ctrl-C ferma il lavoro remoto invece che solo questo terminale.
Poiché la chiave di una riga nomina già il suo host, un client può restituirla direttamente
come selettore — `{"key": "hetzner/3000:127.0.0.1"}` è l'intero selettore,
host incluso. Una chiamata agisce su una macchina; nominarne due è un errore piuttosto che
mezzo kill su ciascuna.
Due cose restano locali. `sonar attach` mette *questo* terminale davanti a un
processo, quindi rifiuta `--host` e dice di fare ssh e collegarsi lì. E una
sessione agent è stato che questo daemon detiene, quindi `sonar kill --session` non ha una
forma remota. Tutto il resto richiede il daemon in esecuzione qui — è dove
vive la connessione all'altra macchina — e lo dice invece di scansionare silenziosamente
questa macchina.
`sonar up --host` richiede che il gruppo sia nominato: il `sonar.yaml` nella tua directory
di lavoro è un percorso su questa macchina, ed è il daemon remoto che legge il
file e avvia i servizi.
### Il daemon
Un processo in background scansiona porte, risolve gruppi, esegue il polling dello stato di salute, mantiene il
database e trasmette le modifiche a chiunque sia iscritto — la CLI, l'app
desktop e gli editor.
```sh
sonar serve # in the foreground
sonar serve --detach # in the background
sonar daemon status # pid, uptime, subscribers, scans, intervals, claim ttl
sonar daemon path # the socket it listens on
sonar daemon log -n 50 -f # what it is doing
sonar daemon restart
sonar daemon stop
```
```sh
sonar daemon path
sonar daemon status --json
sonar daemon log -n 5
# check
```
| Cosa | Dove |
|---|---|
| Socket | `$XDG_RUNTIME_DIR/sonar/daemon.sock`, altrimenti `~/.config/sonar/daemon.sock`; `\\.\pipe\sonar` su Windows |
| Database | `~/.config/sonar/sonar.db` (`SONAR_DB` ha la precedenza) |
| Log del daemon | `~/.config/sonar/daemon.log`, ruotato a 5 MiB, ne vengono conservati tre |
| Log di esecuzione | `~/.config/sonar/logs/<group>/<service>.log` |
| Configurazione | `~/.config/sonar/config.yaml` |
---
[Read more](https://github.com/raskrebs/sonar)