
Ferramenta CLI para inspecionar e gerenciar serviços escutando em portas localhost
<div align="center">
```
██████ ███ ██████ ██ ██████
██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ████
██ ██ ██ ██ ██ ██ ██ ██
██████ ███ ██ ██ ██ ██ ██ ██
```
Saiba o que está sendo executado na sua máquina.
</div>
O Sonar mostra tudo o que está escutando em localhost e organiza em ordem: cada porta
pertence a um **grupo** — normalmente o repositório de onde foi iniciado — e
dentro desse grupo a um **serviço** nomeado. Inicie seus servidores de desenvolvimento com
`sonar start` e o projeto inteiro se torna uma coisa só que você pode listar como uma árvore,
aguardar, acompanhar e parar com um único comando. Contêineres Docker, projetos Compose
e processos iniciados manualmente também são detectados, sem nenhuma
configuração.
```
$ 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
```
## Instalação
### Homebrew (macOS / Linux)
```sh
brew install raskrebs/sonar/sonar
```
Homebrew 6 recusa fórmulas de taps de terceiros até que você confie no tap uma vez
(`Error: Refusing to load formula raskrebs/sonar/sonar from untrusted tap`):
```sh
brew trust raskrebs/sonar
```
### Script de instalação
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | bash
```
Baixa o binário mais recente para `~/.local/bin` e adiciona-o ao seu PATH, se necessário. Reinicie o terminal ou execute `source ~/.zshrc`.
No Windows (PowerShell):
```powershell
irm https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.ps1 | iex
```
Local de instalação personalizado:
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | SONAR_INSTALL_DIR=/usr/local/bin bash
```
Instale uma versão específica:
```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
```
### Usando 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
```
## Sessenta segundos
Descreva como o seu projeto é executado em um `sonar.yaml` na raiz do repositório,
em vez de um `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}
```
Em seguida, inicie-o:
```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
```
O Sonar escolhe uma porta livre para cada serviço `port: auto` e informa a cada serviço onde os outros estão, para que um segundo worktree seja executado ao lado do primeiro sem que uma única porta entre em conflito. `sonar start -d` faz o mesmo em segundo plano, e `sonar down` o interrompe e devolve as portas. Em outro terminal:
```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
```
Sem `sonar.yaml`? `sonar start -- npm run dev` executa um comando como um serviço nomeado, e `sonar list` e `sonar kill` funcionam em qualquer coisa que esteja escutando.
Os exemplos abaixo marcados com `# check` são executados contra uma build nova por
`scripts/readme-check.sh` em cada execução de CI.
## Comandos
### `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
```
As colunas padrão são `port`, `process`, `group`, `container`, `image`,
`containerport`, `url`, onde `process` mostra o nome que você deu à porta
(`sonar rename`), depois o nome do serviço, depois o que foi detectado.
Colunas disponíveis: `port`, `process`, `pid`, `type`, `url`, `group`, `cpu`,
`mem`, `threads`, `uptime`, `state`, `connections`, `health`, `latency`,
`container`, `image`, `containerport`, `compose`, `project`, `user`, `bind`,
`ip`.
Aplicativos de desktop e serviços de sistema que por acaso estejam escutando — Figma, Discord,
Spotify, ControlCenter, pacotes `.app` do macOS, daemons em `/System/Library/` — são
ocultados a menos que você passe `-a`.
### `sonar start`
Inicia um projeto a partir do seu `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`
```
Em primeiro plano, o sonar inicia os serviços através do daemon, acompanha os seus
logs com o nome do serviço à frente de cada linha, e quando prime Ctrl+C
para os serviços que iniciou. Um serviço que já estava em execução é deixado
em paz, e o sonar regressa por si próprio assim que todos os serviços que iniciou tiverem terminado.
Os argumentos antes de `--` nomeiam um diretório ou serviços; tudo depois de `--` é um
comando. Ou execute um comando como um serviço nomeado num grupo:
```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
```
Nada precisa ser passado:
- **Group** — `--group`, senão o `name` no `sonar.yaml` mais próximo, senão o
nome do diretório raiz do git (um worktree se torna `repo@worktree`), senão o nome
do diretório atual.
- **Name** — `--name`, senão o serviço `sonar.yaml` cujo `cmd` corresponde, senão
inferido a partir do comando (`npm run dev` → `dev`, `uv run api` → `api`,
`python -m uvicorn` → `uvicorn`, `./dev.sh` → `dev.sh`).
- **Port** — `--port` é uma dica, não um vínculo: a execução aparece como `starting`
até que a porta esteja realmente escutando, e o daemon a usa para corresponder o
processo à porta.
O processo filho herda stdin, stdout, stderr, cwd e environment, além de
`SONAR_GROUP`, `SONAR_NAME` e `SONAR_RUN_ID`. Ele recebe seu próprio process group,
então `sonar kill` derruba toda a árvore — um dev server com seus watchers e
workers. Ctrl+C é encaminhado, e o sonar sai com o exit code do processo filho.
`--detach` retorna imediatamente e grava a saída em
`~/.config/sonar/logs/<group>/<name>.log`. `--list` mostra o que o sonar iniciou,
e abaixo disso o que desde então terminou — com o exit code, e se travou
ou foi interrompido (`--json` para a forma legível por máquina):
```sh
sonar start --list
sonar start --detach --name demo --port 8123 -- sleep 5
sonar start --list --json
# check
```
### `sonar.yaml`
Um projeto nomeia a si mesmo e aos seus serviços em um `sonar.yaml` na raiz do
repositório. Ele é opcional — o sonar agrupa pela raiz do git sem ele — e
destina-se a ser commitado:
```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` — o nome do grupo. Sem barras, sem espaços em branco.
- `cmd`, `cwd`, `port` — como o `sonar start` inicia o serviço. O `cwd` é relativo ao
ficheiro e não pode sair do seu diretório.
- `health` — um caminho HTTP que o daemon consulta enquanto o serviço está ativo, para que um
serviço possa estar *em execução* mas ainda não *saudável*. Reporta `ok`, `fail` ou
`unknown`, com o motivo da falha.
- `description`, `icon`, `color` — metadados de formato livre para a aplicação de desktop; o sonar
nunca os infere.
- `depends_on` — ordem de arranque. Nomear um serviço que não está no ficheiro, ou um
ciclo, é um erro; um ficheiro inválido é reportado uma vez e nunca interrompe uma análise.
- `env` — variáveis definidas para o serviço quando o sonar o inicia.
#### `port: auto` e referências
Um serviço pode deixar a sua porta ao critério do sonar, e encontrar os outros através do seu
ambiente em vez de um `localhost:8080` codificado:
```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` reivindica uma porta livre para cada serviço `port: auto` que inicia: a
mesma todas as vezes no mesmo checkout, e uma diferente em cada outro
checkout, para que um worktree nunca colida com o principal. O serviço a recebe
como `PORT`, `SONAR_PORT` e `${port}`, e precisa usá-la — ler `PORT`, ou
passar `${port}` na linha de comando. Um serviço que já está em execução mantém
sua porta, então um iniciado depois ainda a encontra. A reivindicação por trás de uma porta
atribuída dura um dia desde o último start; `claims.ttl` muda isso (veja O
daemon).
`${port}` e `${url}` (`http://localhost:<port>`) são do próprio serviço;
`${<service>.port}` e `${<service>.url}` são de outro. Eles funcionam em `cmd`
e em `env`. Uma referência a um serviço que não está no arquivo, ou a um sem
porta, é um erro quando o arquivo é carregado. Qualquer outra coisa entre `${` e
`}`, como `${HOME}`, é deixada exatamente como escrita.
`sonar.yml` é lido se for assim que você escreve; `sonar init` sempre grava
`sonar.yaml`. O arquivo costumava ser o dotfile `.sonar.yaml`, e esse nome
ainda funciona: o sonar procura por `sonar.yaml`, `sonar.yml`, `.sonar.yaml` e
`.sonar.yml`, nessa ordem, e lê o primeiro que encontrar. As edições voltam
para o arquivo que o sonar leu, então nada é renomeado pelas suas costas. `sonar doctor`
aponta um arquivo com o nome antigo, e `sonar doctor --fix` o renomeia
(com `git mv` quando o arquivo é rastreado). O daemon observa os projetos que conhece e capta
edições no arquivo sem reiniciar. Toda edição que o sonar faz — do aplicativo
de desktop, de `sonar groups add`, `rename` e `remove`, de um agente — passa
pelo daemon, que re-renderiza o arquivo a partir de sua própria árvore de sintaxe, então
comentários, ordem das chaves e layout sobrevivem a uma edição que adiciona, renomeia ou remove um
serviço, assim como sobrevivem a uma mudança de metadados. A única exceção: espaços extras
alinhando um comentário à direita (`cmd: x # note`) colapsam para um, porque a
biblioteca YAML mantém o comentário mas não sua coluna.
#### `sonar env`
O que o arquivo resolve é legível sem iniciar nada:
```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
```
Um serviço `port: auto` que não está em execução recebe sua reivindicação aqui, a mesma reivindicação que `sonar start` faz, então o que `sonar env` imprime é o que uma inicialização posterior vincula; um serviço que já está em execução mantém a porta em que está. Nomeado, um serviço é exibido como linhas `export`, para que um shell possa ver o que o serviço faria:
```sh
eval "$(sonar env frontend)" && npm test
```
Por trás dele está `groups.env` no daemon, para um editor ou um agente que
configura um worktree antes de seus serviços existirem.
### `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`, que também pode nomear um grupo de qualquer lugar e
iniciá-lo em outro host. Ele inicia todos os serviços que o `sonar.yaml` do grupo
declara, na ordem de `depends_on`:
um serviço aguarda as portas que suas dependências declaram antes de ser iniciado, e
um que já está escutando é ignorado. Cada um é executado em segundo plano em seu próprio grupo de processos, com sua saída em `~/.config/sonar/logs/<group>/<service>.log`, e com o ambiente do shell em que você executou `sonar up`, mais `PORT` para um serviço
com uma 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
```
Um serviço que falha ao iniciar é reportado na sua própria linha e faz com que o comando termine com código diferente de zero, independentemente de qualquer outra coisa que tenha surgido. Pare todos eles novamente com `sonar down`.
`sonar up` precisa do daemon e o inicia se ele ainda não estiver em execução.
### `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
```
Para todos os serviços do projeto — todas as portas em que escuta e todos os
serviços que o sonar iniciou por ele que não detêm uma porta, como um worker — e liberta
as portas que o sonar reivindicou para os seus serviços `port: auto`. `--only` restringe tudo
isso aos serviços nomeados, tal como `sonar up --only` inicia apenas alguns; um nome
que o ficheiro não declara é um erro. `sonar kill -g my-app` para as portas
e não liberta nada.
### `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` lista todos os grupos que o sonar consegue ver e de onde veio cada nome:
`manual` (você fixou-o com `sonar assign`), `start` (uma execução de `sonar start`),
`file` (um `sonar.yaml`) ou `auto` (a raiz do git ou o projeto Compose).
`sonar groups <name>` mostra as portas e serviços de um grupo, e os serviços
que estão declarados mas não estão em execução.
`sonar init` escreve um `sonar.yaml` na raiz do git a partir do que consegue afirmar: as
portas à escuta dentro do projeto neste momento (aplicações de desktop e portas abaixo de 1024
excluídas), mais o que um ficheiro compose ou um `package.json` declara diretamente — um
serviço por serviço compose, com a sua porta publicada e o seu `depends_on`, e
o script `dev` executado pelo gestor de pacotes a que o seu lockfile o vincula.
Onde os dois discordam, a porta à escuta vence: é evidência, não uma
afirmação. O ficheiro que escreve diz o que não conseguiu determinar.
Nada mais é detetado. Um alvo de Makefile, uma linha de Procfile, um ponto de entrada
enterrado num framework — são suposições sobre o seu repositório, e uma tabela
deles nunca estaria terminada. Essa parte vai para um agente:
```sh
sonar init --agent # whichever agent is installed
sonar init --agent codex # name one
sonar init --agent claude -- --allow-dangerously-skip-permissions
```
`--agent` abre o agente de programação que você já tem, neste terminal, com o
prompt já enviado: o que o sonar sabe, o rascunho que ele teria escrito, o
formato, e a regra de que ele escreve o arquivo e não inicia nada. Você o observa
ler o repositório e aprovar suas edições exatamente como sempre faz — é o seu
agente, sob suas permissões — e qualquer coisa após `--` é passada para ele. O sonar
conhece `claude`, `codex`, `cursor-agent` e `opencode`; com vários instalados,
nomeie um. Quando o agente sai, o sonar carrega o arquivo e imprime os serviços que
ele declara, ou por que ele não carrega. Sem um terminal — um pipe, CI — `--agent`
imprime o prompt em vez de iniciar qualquer coisa.
Ele se recusa a sobrescrever sem `--force`, e `--dry-run` imprime o arquivo
em vez de escrevê-lo. `--merge` anexa a um arquivo que já existe
em vez de recusar, e `--service name:port[:health]` — repetível — escreve
os serviços que você nomeia em vez dos que ele encontrou, mantendo o comando que ele
adivinhou para uma porta que você manteve. `--force` e `--merge` são mutuamente exclusivos.
`sonar groups add <group> <name> --port N` anexa um serviço ao `sonar.yaml` desse grupo,
com `--cmd`, `--cwd`, `--health`, `--description`, `--icon`,
`--color` e um `--depends-on` repetível para o resto. `sonar groups
rename <group> <old> <new>` renomeia um em todos os lugares do arquivo,
referências `depends_on` incluídas, e `sonar groups remove <group> <name>` exclui um e
o remove de todo `depends_on` que o nomeava. Todos os três recusam uma edição que
deixaria o arquivo inválido — um nome duplicado, uma porta que outro serviço já
reivindica, um serviço que não está lá — e nenhum deles escreve um byte até que
toda a edição seja considerada boa.
O daemon faz a escrita, e é por isso que o arquivo volta com seus comentários
e ordem de chaves intactos, seja a edição vinda da CLI, do aplicativo desktop ou de um
agente. `sonar groups add`, `rename` e `remove` precisam do daemon e o iniciam se
ele ainda não estiver em execução; os três nomes são subcomandos, então um grupo de fato
chamado `add` é lido com `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` aceita qualquer seletor e não altera nada: imprime as ações que o
kill executaria, filhos primeiro, e deixa tudo em execução. De ponta a ponta,
contra um listener seu:
```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
```
Um argumento posicional é lido como uma porta, e como um pid apenas quando nada está
a escutar nesse número. `-g` corresponde ao grupo resolvido, a uma tag ou
id de execução legada, e ao projeto Compose, sem distinção de maiúsculas e minúsculas.
Um processo que ignora SIGTERM recebe SIGKILL assim que a porta ainda estiver a escutar
após `--grace` (5s); `--no-escalate` desativa isso. Os filhos são sinalizados
antes dos pais, para que uma árvore seja derrubada por ordem. Os contentores Docker são parados
com `docker stop` e nunca são sinalizados. Um listener iniciado por `sonar start` é
sempre parado juntamente com o seu grupo de processos.
`--json` imprime uma linha por processo:
`{port, bind_address, pid, name, method, ok, error}`, onde `method` é
`sigterm`, `sigkill`, `docker_stop`, `map_stop` ou `none`. Uma varredura vazia sai
com 0; um grupo desconhecido sai com 1.
### `sonar map`
```sh
sonar map 6873 3002 # also serve the service on 6873 from port 3002
```
Executa um proxy TCP em primeiro plano até que você o interrompa. `sonar kill` reporta um mapeamento que ele interrompeu como `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
```
Nomes e pins são armazenados no banco de dados do sonar, indexados pela coisa mais específica conhecida sobre a porta: a execução (`run:<group>/<name>`), o contêiner (`docker:<project>/<service>`), o diretório de trabalho e, por último, o número da porta. Um servidor de desenvolvimento renomeado mantém seu nome entre reinicializações; um nome fixado apenas à porta 3000 aplica-se a qualquer coisa que responda ali. Esses três comandos precisam do daemon e o iniciam se ele não estiver em execução.
### Lendo uma 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` sai com `0` (pronto), `1` (timeout) ou `2` (interrompido), o que
o torna a coisa a colocar entre iniciar algo e testá-lo:
```sh
docker compose up -d
sonar wait 5432 3000 --timeout 60s && npm run migrate && npm run test
```
**Daemon ou varredura direta.** Todo comando de leitura pergunta ao daemon se algum está em execução, porque ele já tem a resposta e não precisa fazer fork do `lsof`. Se nenhum estiver em execução, eles varrem diretamente e imprimem uma nota no stderr informando isso. `sonar kill` segue a mesma regra: um daemon acessível faz a eliminação, então ele revarre imediatamente e sua próxima resposta — e o histórico de portas — já sabe que a porta se foi. Nem leituras nem eliminações iniciam um daemon pelas suas costas. `--no-daemon` força a varredura direta silenciosamente e funciona em qualquer 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
```
O daemon mede a sua própria máquina na cadência de varredura e publica-a como a
linha `localhost` da coleção `hosts` do snapshot: os e kernel, uptime, percentagem de cpu,
load average, memória e o disco que contém `/`. A percentagem de CPU é o trabalho
realizado entre duas varreduras, pelo que é nula até o daemon ter varrido duas vezes; um
valor que uma plataforma não consegue produzir — o load average no Windows, que não tem nenhum —
é nulo em vez de zero. Cada host registado com `sonar remote add` junta-se
à mesma tabela com a sua própria carga. O comando precisa de um daemon em execução: é o
daemon que detém a amostra anterior contra a qual uma percentagem é medida.
As GPUs são listadas sob o seu host com utilização e memória: a partir do `ioreg` no
macOS (a memória do Apple silicon é unificada, pelo que apenas o que a GPU detém é mostrado),
e a partir do `nvidia-smi` ou dos contadores sysfs do amdgpu no Linux. O daemon lê-as
a cada cinco segundos em segundo plano, nunca no caminho de um comando; `gpus` é nulo
onde não há fonte (Windows, Linux apenas com Intel) e `[]` numa máquina sem
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
```
Coloca o sonar num host para o qual já consegue fazer ssh e inicia o seu daemon lá. O
arquivo de release é baixado e verificado com checksum **no host remoto** — nada
é copiado desta máquina — e o binário fica em `~/.local/bin/sonar`, pelo que
nada disso precisa de root. O daemon corre como uma unit de utilizador systemd onde o host
tem uma (`~/.config/systemd/user/sonar.service`), e destacado onde não
tem; `loginctl enable-linger` é impresso como conselho quando a sessão de utilizador terminaria
no logout e levaria o daemon com ela.
A versão instalada é a versão do sonar a partir da qual o executou, para que as duas
pontas falem o mesmo protocolo. Executá-lo novamente atualiza no local e reinicia
o daemon, que é o que faz com que uma instalação e uma atualização sejam o mesmo comando.
O alvo vai para `ssh` sem alterações: um alias `Host` de `~/.ssh/config` funciona,
e também funcionam o `ProxyJump`, `IdentityFile` e `Port` que define. `--identity` e
`--ssh-arg` existem para os flags que uma configuração não cobre.
### `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
```
Um host registrado executa o mesmo daemon, e o daemon nesta máquina mantém
uma conexão SSH com ele — `ssh <target> sonar daemon stdio`, procurando em
`~/.local/bin` antes do `PATH` remoto — e multiplexa
o que ele reporta para o estado que todo cliente já lê. Nada novo escuta
em lugar nenhum: o socket do daemon remoto permanece privado para o usuário SSH, e os clientes
nunca falam SSH por conta própria.
Cada linha agora carrega o host de onde veio. Linhas locais dizem `localhost` e
mantêm as chaves que sempre tiveram, então nada que lê o sonar hoje muda;
linhas remotas dizem o nome registrado e são indexadas por `<host>/<port>:<bind>`, o que
é o que permite que a porta 3000 em duas máquinas sejam duas linhas. Um assinante vê apenas
localhost a menos que peça mais (`state.subscribe {"hosts": ["*"]}`).
O alvo vai para o `ssh` sem alterações, então aliases de `~/.ssh/config`, `ProxyJump` e
identidades todos se aplicam; `--ssh-arg`, `--identity` e `--port` cobrem o que uma config
não cobre, e `--remote-bin` nomeia um sonar que está em outro lugar. O comando
padrão é executado através de `sh`, então um host Windows, cujo sonar vem do
instalador PowerShell, precisa de `--remote-bin sonar`. O sonar não armazena senha nem chave. Um host que desaparece mantém sua
linha e seu status enquanto o daemon tenta novamente, recuando de um segundo a
trinta enquanto permanecer registrado.
`--host` também ainda aceita um `user@host` simples que o sonar não conhece: ele
recorre à varredura agentless `ssh` + `ss`/`lsof` e imprime uma dica para
`sonar remote install`.
#### Agindo em outra máquina
Toda escrita também aceita `--host`, e faz lá exatamente o que faz aqui:
```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
```
O daemon local encaminha a chamada através da bridge desse host e devolve o que
o daemon remoto respondeu, no mesmo envelope que uma chamada local retorna — cada
linha de resultado diz em que host aconteceu, e o `affected` de um kill carrega as
chaves `<host>/<port>:<bind>` que o stream usa para essas linhas. Um comando de
streaming faz streaming: `sonar up --host` imprime cada serviço à medida que o
lado remoto o inicia, e Ctrl-C interrompe o trabalho remoto em vez de apenas este
terminal.
Como a chave de uma linha já nomeia o seu host, um cliente pode devolvê-la
diretamente como seletor — `{"key": "hetzner/3000:127.0.0.1"}` é a totalidade de um seletor,
host incluído. Uma chamada atua sobre uma máquina; nomear duas é um erro em vez de
meio kill em cada uma.
Duas coisas permanecem locais. `sonar attach` coloca *este* terminal à frente de um
processo, por isso recusa `--host` e diz para fazer ssh e attach lá. E uma
sessão de agente é estado que este daemon mantém, por isso `sonar kill --session` não tem
forma remota. Tudo o resto precisa do daemon a correr aqui — é onde a
ligação à outra máquina vive — e di-lo em vez de silenciosamente fazer scan
a esta máquina.
`sonar up --host` precisa do grupo nomeado: o `sonar.yaml` no teu diretório de trabalho
é um caminho nesta máquina, e é o daemon remoto que lê o
ficheiro e inicia os serviços.
### O daemon
Um processo em segundo plano faz scan de portas, resolve grupos, faz polling de saúde, mantém a
base de dados e faz stream de alterações para quem estiver subscrito — a CLI, a aplicação
desktop e os editores.
```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
```
| O quê | Onde |
|---|---|
| Socket | `$XDG_RUNTIME_DIR/sonar/daemon.sock`, senão `~/.config/sonar/daemon.sock`; `\\.\pipe\sonar` no Windows |
| Base de dados | `~/.config/sonar/sonar.db` (`SONAR_DB` substitui) |
| Log do daemon | `~/.config/sonar/daemon.log`, rotacionado a 5 MiB, três mantidos |
| Logs de execução | `~/.config/sonar/logs/<group>/<service>.log` |
| Configuração | `~/.config/sonar/config.yaml` |
---
[Read more](https://github.com/raskrebs/sonar)