Manage the agent service

The agent runs as a service, one service for each PostgreSQL instance that it monitors. This page has one section for each action: list the services, see the state of one, read its log, stop it, start it, restart it, and collect one snapshot right now.

Before you start

• You need administrator rights on the server that runs PostgreSQL: root, or an account that can use sudo.
• The name of a service ends with the port of its PostgreSQL instance. On Linux the name uses hyphens, for example guardioz-agent-5432. On FreeBSD it uses underscores, for example guardioz_agent_5432. Replace 5432 in every command with the port of your PostgreSQL instance.
• The Linux commands that need administrator rights use sudo. As root, leave sudo out. On FreeBSD, run the commands as root.

List the agent services

On the server that runs PostgreSQL, list the agent services. This is the command to run when you do not know the port.

Linux

systemctl list-unit-files 'guardioz-agent-*'

FreeBSD

service -e | grep guardioz_agent

The list has one entry for each agent service on this server. The number at the end of a name is the port of the PostgreSQL instance that it monitors. When the list is empty, no agent is installed on this server. See Install the agent or Agent and data problems.

See the state of the service

On the server that runs PostgreSQL, show the state of one service. Run it with administrator rights.

Linux

sudo systemctl status guardioz-agent-5432 --no-pager

The line that starts with Active: carries the state. active (running) means that the service runs. inactive (dead) means that it is stopped. failed means that it stopped with an error, and the log says why.

FreeBSD

service guardioz_agent_5432 status

The command reports whether the service runs.

A running service means that the agent process is up. It does not prove that the last snapshot reached Guardioz. To confirm that, see Check that the agent works.

Read the log

On the server that runs PostgreSQL, show the last 50 lines that the agent wrote. Run it with administrator rights.

Linux

sudo journalctl -u guardioz-agent-5432 -n 50 --no-pager

The agent has no log file of its own on Linux. It writes to the system journal.

FreeBSD

tail -n 50 /var/log/guardioz_agent_5432.log

newsyslog(8) rotates this file by the rule that the installer wrote. FreeBSD runs newsyslog once an hour, and it then starts a new file once the current one is larger than 1 MB and keeps 7 compressed older files next to it. See What the installer changes on your server.

Each line that the agent writes carries the date and the time, then the level (DEBUG, INFO, WARNING or ERROR), then [guardioz-agent], then the message. On Linux the journal adds its own date, the host name and the process name in front of that.

The line Snapshot sent (HTTP 202) reports that a snapshot reached Guardioz.

After a start the log stays quiet for one full interval, about an hour. That is normal. See When the agent collects.

Stop the agent

Caution

While the service is stopped, the agent collects nothing and Guardioz receives no snapshot. Nothing is queued on the server, so the hours without a snapshot stay a gap in the history. Your findings stay as they were at the last snapshot.

On the server that runs PostgreSQL, stop the service. The command needs administrator rights.

Linux

sudo systemctl stop guardioz-agent-5432

FreeBSD

service guardioz_agent_5432 stop

Stopping the service does not remove it. The installer set it to start at boot, so it starts again when the server reboots. To confirm that it is stopped now, use the command in See the state of the service. To remove the agent from the server, see Remove Guardioz from a server.

Start the agent

On the server that runs PostgreSQL, start the service. The command needs administrator rights.

Linux

sudo systemctl start guardioz-agent-5432

FreeBSD

service guardioz_agent_5432 start

The agent waits one full interval before its first collection, so the next snapshot arrives about an hour later. To send one at once, see Run a collection now.

Restart the agent

Restart the service after you change the configuration file. The agent reads that file once, at start. The command runs on the server that runs PostgreSQL and needs administrator rights.

Linux

sudo systemctl restart guardioz-agent-5432

FreeBSD

service guardioz_agent_5432 restart

A restart also starts a service that was stopped. As after any start, the next scheduled collection comes one interval later.

Run a collection now

A collection started by hand carries every part at once: the hourly datasets, the catalog of tables and indexes, and the size measurements. It sends them as one snapshot and then exits.

It measures table and index sizes, so it does more work on your server and takes longer than an hourly collection. The agent gives those measurements a time budget for each database and records what it did not measure. For that budget, see Limits.

Run it once when you want a result now, for example after you applied a recommendation. Leave the regular collections to the service, and do not run it on a schedule of your own. During the first day after the registration, a collection started by hand does not move the hourly catalog of the service.

Guardioz takes at most one snapshot of a server every 10 minutes. A collection that you start less than 10 minutes after the last snapshot of that server is refused: the output shows Cockpit refused the snapshot (HTTP 429): with the reason, and no Snapshot sent (HTTP 202). Run it again later. When the next scheduled collection of the service comes less than 10 minutes after yours, Guardioz refuses that one in the same way, the service log shows the same line, and that hour stays a gap in the history.

The collection runs as root on the server that runs PostgreSQL, because only root and the account that runs the service can read the configuration file. It does not stop the service and it does not need the service to be stopped.

Linux

sudo env PYTHONPATH=/opt/guardioz-agent /opt/guardioz-agent/venv/bin/python -m guardioz_agent.cli -c /etc/guardioz-agent/config-5432.yaml --once

The command starts with sudo env, because plain sudo removes PYTHONPATH from the environment and the agent is then not found. As root, leave out sudo and keep env.

FreeBSD

On FreeBSD the agent runs with one exact Python interpreter, chosen when the agent was installed, so the command names that interpreter. Read it from the service script, as root:

grep command_args /usr/local/etc/rc.d/guardioz_agent_5432

The path directly before -m guardioz_agent.cli is that interpreter, for example /usr/local/bin/python3.12. Run the collection as root, with that path in place of PYTHON:

env PYTHONPATH=/opt/guardioz-agent PYTHON -m guardioz_agent.cli -c /etc/guardioz-agent/config-5432.yaml --once

The output goes to your terminal and not to the service log. The line Snapshot sent (HTTP 202) reports that the snapshot reached Guardioz.

The last line is Guardioz Agent stopped., whether the snapshot was sent or not. The command exits with code 0 even when the collection or the send failed. The exit code therefore tells you nothing about the result. When you do not see Snapshot sent (HTTP 202), read the lines with the level ERROR and see Agent and data problems.

When the snapshot reaches Guardioz, it counts as the daily and the weekly part too, so the service does not collect those parts again on its next collection. During the first 24 hours after the registration the service still collects the catalog on its next collection, because the catalog is collected every hour then. See When the agent collects.

If something goes wrong

• The service does not run, or the log reports an error: Agent and data problems.
• Nothing matches what you see: write to contact@guardioz.com. For what to include, see Get help.

Next steps

When the agent collectsThe hourly, daily and weekly parts, and what they mean for a finding.

Agent configurationThe configuration file, its keys and the command-line options.

Update the agentUpdate in place, keep the server and its history, and roll back.