Agents and modules generated by the plugin

The plugin will create a main agent for each configured PostgreSQL target. That agent will contain the following modules depending on the enabled configuration.

The POSTGRESQL connection module is always generated, regardless of the enabled tokens, and reflects the overall availability of the instance.

POSTGRESQL connection

**PostgreSQL instance availability.** It will be 1 if the connection to the instance was successfully established and 0 otherwise.

If engine_uptime is enabled:

restart detection

**It will be 0 if an unexpected restart has been detected, and 1 otherwise.** This allows detection of unexpected PostgreSQL service restarts that may affect database availability or interrupt service continuity.

If query_stats is enabled:

queries	Number of active queries. Allows monitoring of the current query workload on the PostgreSQL instance.
insert	Number of active INSERT queries. Useful for evaluating current write activity and insert workload.
delete	Number of active DELETE queries. Helps identify active deletion operations that may impact performance.
update	Number of active UPDATE queries. Allows monitoring of active data modification operations.

If analyze_connections is enabled:

session usage

**Percentage of connection usage compared to the configured maximum.** Useful for identifying connection saturation or resource exhaustion scenarios.

If cache_stats is enabled:

allocated buffer cache	Total allocated shared buffers. Represents the amount of memory reserved by PostgreSQL for data caching.
backend used buffer cache	Buffers used by backend processes. Helps evaluate memory usage generated by active processes.
checkpoints buffer cache	Buffers written by checkpoints. Useful for analyzing checkpoint disk synchronization activity.
cleaned buffer cache	Buffers cleaned by the background writer. Helps evaluate cache cleanup activity.

If fragmentation_ratio is enabled:

fragmentation ratio

**Estimated average fragmentation ratio.** High values may indicate wasted storage space or degraded performance.

If scan_databases is enabled, the plugin will discover the databases available on the PostgreSQL target.

The connection module will always be created for each discovered database.

If agent_per_database is enabled, a separate agent will be created for each discovered database. Otherwise, database modules will be created within the main agent using the corresponding database name as prefix.

If Storage statistics is enabled:

database size	Total database size. Useful for monitoring storage growth.
tables size	Total space used by tables. Helps evaluate storage consumed by data structures.
indexes size	Total space used by indexes. Useful for identifying excessive index growth.
temp bytes	Temporary data written to disk. May indicate expensive sorting or temporary processing operations.
temp files	Number of temporary files created. Useful for identifying temporary workload pressure.

If Query performance is enabled:

long queries	Long-running active queries. Useful for detecting slow or problematic queries.
oldest query age	Execution time of the oldest active query. Helps identify long-running operations or blocking scenarios.
sequential scans	Number of sequential scans. High values may indicate missing indexes.
index scans	Number of index scans. Useful for evaluating effective index usage.
cache hit ratio	Database cache hit ratio. Helps evaluate memory access efficiency.

If Connections statistics is enabled:

active connections	Number of active connections. Reflects current user or application activity.
idle connections	Number of idle connections. Helps detect unused but open sessions.
total connections	Total number of open connections. Provides overall connection consumption visibility.

If Transaction statistics is enabled:

transactions	Total executed transactions. Reflects general transactional activity.
commits	Committed transactions. Indicates successfully completed operations.
rollbacks	Rolled back transactions. May indicate failures or canceled operations.
rollback ratio	Rollback ratio. Helps identify abnormal transactional behavior.
deadlocks	Detected deadlocks. Useful for identifying locking conflicts.
conflicts	Detected database conflicts. Helps evaluate concurrency issues.

If Table statistics is enabled:

table count	Total number of user tables. Structural inventory of the database.
index count	Total number of user indexes. Useful for structural monitoring.
live tuples	Estimated active rows. Reflects useful stored data volume.
dead tuples	Estimated obsolete rows pending cleanup. Useful for identifying VACUUM requirements.
fragmentation ratio	Estimated table fragmentation ratio. Helps evaluate storage health.

If Advanced performance is enabled:

blocks read	Blocks read from disk. Useful for measuring physical storage access.
blocks hit	Blocks retrieved from cache. Useful for measuring memory access efficiency.

The plugin will also create a module for each custom query defined in the configuration file. Custom queries with target_scope=instances will be assigned to the main (instance) agent, while those with target_scope=databases will be assigned to the corresponding database agents.

In PostgreSQL 17 and later versions, the modules "backend used buffer cache", "checkpoints buffer cache", and "cleaned buffer cache" are not available.