Skip to main content

Auto-discovery

Auto-discovery is the core of the configless model. The agent enumerates what is on the host and reports it as facts. The server matches those facts against the signed catalog and pushes back the definitions that apply. Nothing you did not run gets monitored, and nothing runs that was not matched and signed.

What the agent enumerates​

  • Processes: name, command line, binary path.
  • Listening ports: TCP and UDP, with the owning process.
  • Installed packages: dpkg, rpm, apk, and brew on macOS.
  • Service units and their state (systemd units, Windows services via the SCM).
  • Init system: systemd, OpenRC, or sysvinit, so a definition can target "any host with init X" or any Linux host.
  • Scheduled jobs: cron entries from the system crontab, cron.d, user spools, and the cron.hourly through cron.monthly directories.

On Windows the equivalents come from native WinAPI: processes via Toolhelp, services via the SCM, packages from the registry Uninstall keys, ports via iphlpapi.

How matching works​

Each definition carries a match rule: a process name, a listening port, a package, a service unit, an init family, or a capability. When a host's facts satisfy the rule, the server pushes that definition and the agent activates its probes. A host running mod_php, for example, honestly does not match a php-fpm definition, because there is no php-fpm process.

Real paths, not defaults​

Where a probe needs a location, the agent reads the service's actual config rather than guessing: nginx -T for the access log, mysqladmin variables for the datadir, socket and slow log, the php-fpm pool config from the command line. Non-standard layouts are found. You can still override any location four ways, see Location overrides.

Change detection and inventory​

The agent watches a cheap change signal (package database mtimes plus the set of listening ports) and re-runs discovery within about 30 seconds of a change. On the server side the inventory is kept current: when a fact disappears (a service removed, a port closed) the gateway writes a tombstone so the inventory reflects reality within seconds.

Discovered entities become inventory facts of a kind: process, port, package, unit, init, cronjob, plus net for the host IP addresses. Deeper probes add more kinds such as vhost, device, guest, and docker.

Containers are excluded from host discovery​

Containerized processes are filtered out of host discovery by their cgroup markers, so a Postgres inside a container never matches a host-level definition. Containers are the Docker probe's domain, and container APM is addressed explicitly. This also means a Proxmox node does not falsely match services running inside its guests.