Agent configuration

The agent reads one configuration file at start. This page lists where that file lives, what each key in it means, and which command-line options the agent has.

The configuration file

The installer writes one file for each monitored PostgreSQL instance, named after the port of that instance. For the instance on port 5432 the file is /etc/guardioz-agent/config-5432.yaml. The format is YAML.

The file belongs to root and its mode is 0640. Its group has the same name as the system account that runs the agent’s service, and the service runs with that group, so the running agent can read the file and cannot change it.

The registration step of the installer is the only thing that writes this file. The agent never rewrites it while it runs.

Caution

The file holds two secrets: the collector key of this server, and the password of the monitoring role inside the connection string. Keep the file on the server. When you write to us about a problem, send the log lines and not the file.

Keys

The agent uses the value in the Default column when the key is not in the file. The installer writes every key.

Key	Default	Meaning
api_url	none, required	The address of Guardioz that the agent sends snapshots to. The agent adds /api/v1/collector/snapshot to it. Without a value the agent writes api_url is not configured and stops.
collector_key	none, required	The secret that identifies this server to Guardioz. The registration writes it. Without a value the agent writes collector_key is not configured and stops.
dsn	host=/var/run/postgresql dbname=postgres	The PostgreSQL connection string, written as key=value pairs separated by spaces - the same form that psql and other PostgreSQL client programs accept. It carries the name and the password of the monitoring role, the read-only PostgreSQL user that the installer created for the agent. The installer writes the local socket directory, the port, the database postgres and the role guardioz_monitor. On FreeBSD the socket directory is /tmp. See What the installer changes on your server.
interval	3600	The number of seconds that the agent waits between collections. The installer writes 3600, which is one hour, and Guardioz is designed for that value: keep it. Every collection reads statistics from the cluster and from each of your databases, so a shorter interval repeats that work more often on your server, and it adds no check. The agent does not run with less than 900: it writes interval is 60 s; the agent runs with at least 900 s. (with your value) and does not start. With an interval of about 90 minutes or more, the status dot on the Servers page turns yellow before each snapshot while the agent works normally, and with more than 150 minutes it also turns red, because the dot expects one snapshot per hour. See Why the agent collects once an hour. The interval does not bring the daily or the weekly part forward: the daily part is due 24 hours after the last one that reached Guardioz (1 hour during the first 24 hours after the registration), and the weekly part 7 days after.
log_level	INFO	How much the agent writes to its log: DEBUG, INFO, WARNING or ERROR. A value that the agent does not know becomes INFO. With WARNING or ERROR, the log no longer shows Snapshot sent (HTTP 202), nor the starting and the waiting line that the other pages use to confirm that the agent works. The installer writes INFO.

This is the shape of the file. The values on your server are different:

/etc/guardioz-agent/config-5432.yaml

api_url: https://app.guardioz.com
collector_key: COLLECTOR_KEY
dsn: user=guardioz_monitor dbname=postgres host=/var/run/postgresql port=5432 password=MONITORING_PASSWORD
interval: 3600
log_level: INFO

COLLECTOR_KEY and MONITORING_PASSWORD stand for the two secrets that the registration wrote.

Keep collector_key and dsn as the registration wrote them. Guardioz accepts snapshots only for a key it knows, and the password in the connection string is the one that the installer gave the monitoring role.

Caution

Keep the key=value form that the installer wrote in dsn. At start the agent writes the connection string to its log and cuts it at the text password=, so the password stays out of the log. A connection string in the URI form postgresql://user:password@host/database does not contain that text, so the agent writes the whole string, password included. When your file holds a URI, write it in the key=value form and restart the service.

Apply a change

On the server that runs PostgreSQL, as root, edit the file with the editor you normally use. A change takes effect when the service restarts, because the agent reads the file once, at start.

After the restart, confirm that the service runs and that its log carries no error. When it starts, the agent writes the interval and the connection string to its log, with the password removed, so a change to the interval or to the connection details is visible there. The restart command and the log command are both on Manage the agent service.

After a restart the agent waits one full interval before its first collection, so the next snapshot arrives about an hour later. See When the agent collects. To get a snapshot at once, run a collection by hand: see Manage the agent service.

Command-line options

Option	Default	What it does
-c, --config	/etc/guardioz-agent/config.yaml	The path of the configuration file to read. The service passes the file of its own instance. Without the option the agent reads the path in the GUARDIOZ_CONFIG environment variable, and then the default path.
--once	off	Collect once, send the snapshot and exit. This collects every part, including the catalog and the size measurements. See Manage the agent service.
-h, --help		Print the options and exit.

The agent also has two subcommands that the installer uses. register registers the server and writes the configuration file. scram-verifier computes the hash of the monitoring role’s password that the installer sends PostgreSQL. You do not run either of them by hand.

The agent has no option that prints a version number. For what to send when you write to us, see Get help.

The keys api_url, collector_key, dsn and interval have matching environment variables: GUARDIOZ_API_URL, GUARDIOZ_COLLECTOR_KEY, GUARDIOZ_DSN and GUARDIOZ_INTERVAL. When one of these variables is set, the agent uses its value instead of the value in the file. The installed service sets none of them, and log_level has no environment variable.

Several PostgreSQL instances on one host

Guardioz does not support a server that runs more than one PostgreSQL instance. The settings recommendations that depend on hardware are computed for the whole server, not for one instance, and nothing in Guardioz marks them as wrong. See Requirements.

One install command registers one instance: when your server runs more than one PostgreSQL 18 instance, the installer asks which one to register and changes nothing on the others. The installer does not refuse a second install command for another port of the same server. A host that carries more than one registered instance is still outside what Guardioz supports, for the reason above. On such a host each registered instance has its own files, all named after the port. For the instance on port 5432 these are:

• the configuration file /etc/guardioz-agent/config-5432.yaml,
• the schedule file /var/lib/guardioz-agent/state-config-5432.json,
• the service guardioz-agent-5432 on Linux, or guardioz_agent_5432 on FreeBSD.

The agent’s code under /opt/guardioz-agent and the system account for the agent’s service are shared by every instance on the host.

If you need Guardioz on a server with more than one instance, write to contact@guardioz.com and tell us about the server.

Next steps

Manage the agent serviceSee the state, read the log, restart, and run a collection now.

When the agent collectsThe hourly, daily and weekly parts, and the wait after a start.

What the installer changes on your serverEvery file, account and PostgreSQL change that the installation makes.