How Guardioz works

Guardioz has two parts: an agent that runs on your server, and the Guardioz web application. It supports PostgreSQL 18 on a server that you run yourself. Managed services and PostgreSQL run by a Kubernetes operator are not supported. Requirements has the full list. This page explains what each part does, how collected data becomes a finding you can act on, and what Guardioz leaves to you.

The two parts

The agent is a small program that runs on the same server as PostgreSQL. It connects to the database over the local Unix socket, as a monitoring role - a PostgreSQL user with read access to statistics and no rights of its own on your tables - in sessions that it sets to read-only. It runs a fixed list of statements against PostgreSQL’s own statistics and its system catalog. The catalog is where PostgreSQL keeps the definitions of your databases, tables and indexes. It sends the result to Guardioz as one snapshot. A profile of the machine - processors, memory and disks - travels in the first snapshot, and the agent refreshes it once a week.

Every statement the agent runs to read your database is written in its source code, and the installer puts that source code on your own server, under /opt/guardioz-agent. The install script itself is a plain text download that you can read before you run it: see Install the agent. The agent starts every connection itself, so no inbound port is opened and the PostgreSQL port is not exposed.

Guardioz is the web application at https://app.guardioz.com/. It stores each snapshot, runs its checks on that snapshot, and keeps the results as findings. You read your findings there. When a recommendation comes with a command, you copy the command from there.

From a collection to a finding

1. The agent collects. The first collection runs right after the install and carries every dataset the agent collects, including the parts that are otherwise collected daily and weekly. After that the agent collects about once an hour, with the table and index catalog every hour during the first 24 hours and once a day after that, and size measurements once a week. The schedule is a design decision that keeps the agent’s load on your database small. See Why the agent collects once an hour.
2. The agent sends one snapshot over HTTPS. The agent tries up to three times. A snapshot that still cannot be delivered is dropped, and the next collection takes fresh data. Nothing is queued on your server.
3. Guardioz runs the checks that this snapshot has data for. A check whose data is not in the snapshot reaches no verdict: either it does not run and you see no new result for it, or its group shows Not evaluated with the reason. Guardioz never reaches a verdict from data it does not have. A check that does not apply to your server, for example the archiving check when archive_mode is off, reaches no verdict either: its group page shows Not evaluated with the reason, and the group has no row on the Findings page. See What Guardioz checks.
4. The results are stored as findings, which you read on the Findings page. Every finding has one of three severities: critical, warning or suggestion. Opening or refreshing a page in Guardioz never runs a check: the pages show what the last analysis stored. When an analysis finds a group of checks that appeared or became more severe, Guardioz sends one email about that server to the account of your organization. Today an organization has one account. In Account Settings you choose the levels to receive email about: critical is selected until you change it, warning and suggestion are not. The plan decides which levels can send email: critical only on the Free plan, every level on the Team and Scale plans. Guardioz sends no email when a problem is resolved, and delivery is not guaranteed. See Email alerts.
5. You apply a change. You run the command yourself, on your own schedule. The check runs again on the next snapshot that carries the data it needs, and the finding is updated to match. For a setting that PostgreSQL applies on a reload, that is the next collection, about an hour later. For an index or a table, it is the next collection that carries the catalog: every hour during the first 24 hours after the registration, and once a day after that. A setting that needs a restart changes after PostgreSQL restarts. See Apply a recommendation.

What Guardioz does not do

• The agent makes no change to your database. It reads your database with SELECT and SHOW statements only. The other statements it sends change only its own session: one sets the session to read-only, so PostgreSQL itself refuses any write from it, and on a server whose DateStyle is not ISO the database driver also sets the date format of the session. The agent does not edit a configuration file, does not reload and does not restart PostgreSQL. The installer makes its own one-time changes when you install the agent: see What the installer changes on your server.
• You run every command. A recommendation is text that you copy, look at, and run when you decide to. Nothing is applied for you.
• Guardioz opens no connection to your server. Every connection starts on your side, outbound.
• Guardioz is not real-time monitoring, and that is a design decision. It monitors your server around the clock, on a schedule: a collection about once an hour, not a sample every few seconds, and it draws no second-by-second graphs of your metrics. Every query a monitoring tool runs uses the processors, memory and disk of your database server, also during an incident, when the server can least afford them. So the agent asks rarely. The conditions Guardioz checks last or build up over hours or days, so an hourly collection gives the checks what they need, and a more frequent one would add load without adding a check. See Why the agent collects once an hour.
• Guardioz does not tell you that your database or your server stopped. It is not an uptime monitor. While PostgreSQL does not answer, the agent cannot collect, and no snapshot arrives. No email says so. The Servers page shows how long ago the last snapshot arrived, and the status dot of the server turns yellow after 90 minutes without a snapshot and red after 150 minutes. See Manage your servers.
• The agent does not read the rows of your tables. It reads statistics views and system catalogs. One of those views, pg_stat_activity, shows the statement each session is running at the moment of collection, or ran last when it is idle. When a statement carries a value written directly in its text, for example WHERE email = 'anna@example.com', that value is collected with it. The full list of what the agent reads and sends is on What the agent reads and sends.

What Guardioz checks today

Guardioz checks a fixed set of PostgreSQL settings, the indexes in your monitored databases, your replication slots, and the archiving of transaction logs: an archiver that has stopped, fails or falls behind. It also checks transactions that stay open so long that PostgreSQL cannot clean up dead rows. That check is called Open transactions and cleanup. A second check about cleanup, Tables behind on cleanup, reports a table that lets dead rows build up for a long time before automatic cleanup starts. Where Guardioz can calculate a safe value, the finding carries the statement that lowers the number of dead rows that starts cleanup of that table. Each check is listed, with what it looks at and what you get, on What Guardioz checks.

Most checks reach a verdict on the first snapshot. A few compare one collection with the next, so their first verdict arrives after the following collection, about an hour later. The checks page says which ones.

The agent collects more than these checks use. A view or a counter on What the agent reads and sends does not mean that Guardioz reports on it: Guardioz reports only on what the checks page lists.

What Guardioz does not cover today

• The queries that run on your server. Guardioz does not read pg_stat_statements and reports nothing about slow queries. Query analysis is planned.
• Unused indexes, indexes you are missing, and table or index bloat. The index checks cover invalid indexes and exact duplicates.
• Replication lag of a running replica. The replication check looks at slots.
• Locks, deadlocks and long-running queries. Open transactions and cleanup is about cleanup that PostgreSQL cannot do, not about how long a query runs.
• How many connections a server uses.
• Free disk space on its own. The agent measures it, and two checks use it as an input, but no check warns about a disk that fills up. The replication slot check reports low free space only when an inactive slot holds a large part of the transaction-log disk.
• How close a database is to transaction-ID wraparound.
• Backups: what your archive of transaction logs holds, and whether a backup can be restored.
• Whether your database or your server is up. See What Guardioz does not do.
• Settings other than the ones on the checks page. The agent collects every setting, and Guardioz evaluates the set it has rules for.
• Cost analysis.

The full list is on What Guardioz checks.

Next steps

RequirementsWhat a server needs before you install the agent, and what is not supported.

QuickstartInstall the agent on a Linux server and read your first finding.

Security and accessWho connects to your database, with which rights, and where the data goes.