Agent

Datasentinel offers two monitoring approaches: agent-based and agentless. This guide focuses on the installation of an agent, applicable when you opt for the agent-based monitoring method.

Datasentinel requires the installation of the pg_stat_statements extension within your PostgreSQL instances.

Refer to the installation guide for pg_stat_statements and instructions on setting the recommended parameters. The extension mut be installed on the internal database named postgres

The examples are based on a standard PostgreSQL installation with a server running the CentOS 7 operating system

Step-by-Step Installation Instructions

You need to install just one agent per server, which can effectively monitor multiple PostgreSQL clusters.

When required, the agent can also be installed on an intermediary server.

Date	Last available agent version
2026-02-02	3.9.1	Release Notes

1

Download file

• RedHat/Centos/AlmaLinux 9

• RedHat/Centos/AlmaLinux 8

• RedHat/Centos 7

• (Deprecated) RedHat/Centos 6

• Debian Buster / Bullseye

• (Deprecated) Debian Stretch

• (Deprecated) Debian Jessie

The file size is approximately 35 MB.

2

Install and start the agent

Whenever possible, avoid using the root account.

Uncompress the downloaded file

tar xvzf datasentinel-agent-rhel9.tar.gz

There are two ways to start the agent:

• Using an alias

alias datasentinel='DATASENTINEL_PATH=`pwd`/datasentinel;$DATASENTINEL_PATH/datasentinel'
datasentinel start agent

• By setting environment variables

export DATASENTINEL_PATH="`pwd`/datasentinel"
export PATH=$DATASENTINEL_PATH:$PATH
datasentinel start agent

LD_LIBRARY_PATH=$DATASENTINEL_PATH/lib is optional and only needed in case of shared library loading errors.

3

Test the status

datasentinel status agent

   Copyright 2023 (c) Datasentinel- All rights reserved        www.datasentinel.io
   ================================================================================

            Agent
               Version : 3.3.0
               Server : pg-crm-4529
                  Port : 8282
            Start time : 2023-03-18 15:45:31
      Collection rate : low
Table monitoring limit : 1000
Query monitoring limit : 30000
         Sql max size : 256000

            Proxy
                  host :
                  port : 0
                  user :
            password :

         Upload
                  host : upload_server_to_be_defined
                  port : 443

      Connections
            declared : 0
               running : 0
         not running : 0

Check this point if the agent is up and running, but the CLI is indicating a negative response:

What could be the reason if the agent is running but the CLI responds with "NO"?

The agent registers its server name with the platform, enabling communication between the platform and the agent, as well as ensuring proper functionality of the agent CLI

If the server name is unknown (for example, not present in DNS servers), you can set the following environment variable before starting the agent:

// Example
export DATASENTINEL_AGENT_HOST=172.16.250.199

The server name will also be utilized to generate the distinctive pg_instance tag, uniquely identifying instances across the entire platform.

pg_instance is formed by concatenating the server name with @ and the connection name. Refer to Tags section for more details

4

Platform upload

The platform is where metrics are sent. In SaaS mode, it’s the name of the Datasentinel SaaS server.

The default port for https is 443, unless you’ve customized it during local platform installation.

// Setting the platform 
datasentinel set server <<repository_server>> <<port>>

5

Token settings

A token is required to communicate with the platform.

The token is the license provided by the Datasentinel team. You can also copy the token from Agents Submenu in the User Interface.

// Setting the token
datasentinel set token <<token_value>>

The agent uses a self-signed certificate found in the config subdirectory.

• cert_datasentinel.pem

• key_datasentinel.pem

6

Check platform and token

The command checks the communication between the agent and the platform server

datasentinel show token

7

Automatic Startup Configuration

It's adviced to configure automatic startup of the agent at server startup and to avoid unexpected agent stops

This example below requires Agent version 3.9 or later, as the DATASENTINEL_FOREGROUND environment variable was introduced in this version. Create a new systemd service file at /usr/lib/systemd/system/datasentinel-agent.service

## Basic systemd Service
[Unit]
Description=DataSentinel Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=postgres

Environment=DATASENTINEL_FOREGROUND=1

ExecStart=/var/lib/pgsql/datasentinel/datasentinel start agent
ExecStop=/var/lib/pgsql/datasentinel/datasentinel stop agent

# Restart automatically if it crashes
#Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start the service

$ systemctl daemon-reload
$ systemctl enable datasentinel-agent
$ systemctl start datasentinel-agent
$ systemctl status datasentinel-agent

● datasentinel-agent.service - DataSentinel Agent
     Loaded: loaded (/usr/lib/systemd/system/datasentinel-agent.service; enabled; preset: disabled)
     Active: active (running) since Fri 2026-01-30 13:23:45 CET; 1s ago
   Main PID: 76505 (datasentinel)
      Tasks: 7 (limit: 48683)
     Memory: 51.0M
        CPU: 1.250s
     CGroup: /system.slice/datasentinel-agent.service
             └─76505 /var/lib/pgsql/datasentinel/datasentinel start agent

Jan 30 13:23:45 pg-crm-4743 systemd[1]: Started DataSentinel Agent.

PostgreSQL

Example of configuring and adding a connection. Refer to PostgreSQL clusters for more details

The pg_stat_statements extension must be installed in the internal database named postgres before monitoring a cluster.

User

Version >= 10

create user datasentinel password 'myPassword';
grant pg_monitor,pg_read_all_settings,pg_read_all_stats to datasentinel;

// If you intend to utilize the option for terminating a session directly from the User Interface
grant pg_signal_backend to datasentinel;

It's important to highlight that the user doesn't write data in PostgreSQL Access is confined to read-only permissions solely for retrieving metrics.

Version < 10

The user must have the role superuser

create user datasentinel password 'myPassword';
alter user datasentinel with superuser;

The default setting for the PostgreSQL search_path variable is "$user", public.

If the search_path has been modified at the instance level, it's essential to ensure that the user account, typically datasentinel, includes the public schema in its search_path.

If the public schema is not included, you will need to update it accordingly.

ALTER USER datasentinel SET search_path TO "$user", public;
// Connect with datasentinel user
SHOW search_path;

File pg_hba.conf

• Add authorization for the user datasentinel to connect to all databases with a password

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             datasentinel    127.0.0.1/0             md5

The user needs to be able to connect to ALL databases.

• Reload the configuration

select pg_reload_conf();

Add Instance

cat > myInstance.json <<EOF
{
  "host": "host_name",
  "port": postgres_port,
  "user": "datasentinel",
  "password": "myPassword",
  "tags": "application=application_name,environment=application_type,datacenter=datacenter"
}
EOF

Replace MyConnectionName with a meaningful connection name in your environment.

datasentinel add connection myConnectionName -f myInstance.json

A script is present in the datasentinel subdirectory as an example named connection_example.sh

The tags are customizable, allowing you to define your own tags. They are extremely useful in the user interface for filtering, grouping data, and defining role-based access.

Tags

Useful CLI commands

CLI

• Display the agent status

datasentinel status agent

• Display the connections

datasentinel show connections

For a comprehensive list of options, simply type datasentinel without any arguments

datasentinel

Copyright 2023 (c) Datasentinel- All rights reserved        www.datasentinel.io
================================================================================

   Agent:
         - start agent
         - stop agent
         - status agent
         - show metrics
               Show internal agent metrics and cache activity
         - set port <port number>
         - set collection-rate <low|high>
               low: The sessions collection is done every 10 seconds
               high: The sessions collection is done every second  (Default value)
               If the datasentinel extension is not installed, the collection-rate is automatically adjusted to low value
         - set tables-monitoring-limit (default 1000)
               The agent monitors the activity of tables and indexes if the number of tables in the connection is less than the defined limit
         - set query-monitoring-limit (default 15000)
               The agent tracks query activity, storing unique IDs in a daily cache. Exceeding limit triggers automatic deactivation of query monitoring.

   Connections: when the connections are disabled, the agent is disconnected.
         - enable all
         - disable all

   Connection:
         - add connection <name> -f <json file>
         - update connection <name> -f <json file>
               json example: {
                              "host": "hostname",
                              "port": 4587,
                              "user": "username",
                              "password": "value",
                              "tags": "key=value,key=value,..."
                              }

         - update connection <name> samples <on|off> (default off)
               Collect and send sample queries, with literal values if present

         - update connection <name> lock-monitoring <on|off> (default on)
               Scan blocking sessions (longer than lock-monitoring-delay) and send blocking reports

         - update connection <name> lock-monitoring-delay <seconds> (default 30)
               Minimum number of seconds before triggering a blocking scenario

         - update connection <name> table-monitoring <on|off> (default on)
               Monitor the activity of tables and indexes (The number of tables must be lower than the maximum limit set at the agent level (default 1000)

         - update connection <name> query-monitoring <on|off> (default on)
               Monitor pg_stat_statements query activity

         - update connection <name> query-monitoring-optimize <on|off> (default on)
               Group similar pg_stat_statements queries

         - update connection <name> query-monitoring-min-calls <calls> (default 2)
         - update connection <name> query-monitoring-min-time <seconds> (default 1)
               Retrieve pg_stat_statements queries executed n times (calls) OR with total execution time exceeding specified seconds

         - update connection <name> test-query-monitoring-optimize
               Test and optimize pg_stat_statements query contents with previous parameters, display results

         - delete connection <name>
         - enable connection <name>
         - disable connection <name>

         - show connections
         - show connection <name>

   Dump connection in JSON format:
         - dump connection <name>

   Upload server:
         - set server <host> <port>
         - show server
         - test server

   Token:
         - set token <value>
         - show token

   Proxy:
         - set proxy -f <json file>
               json example: {
                              "host": "hostname",
                              "port": 4587,
                              "user": "username (optional)",
                              "password": "value (optional)"
                              }
         - delete proxy
         - show proxy

API

All operations are available through Agent API.

API Reference

By default, the agent listens on port 8282, but you have the flexibility to modify this configuration.

curl -k https://localhost:8282/api/agent/status

{
"version": "3.3.0",
"server": "pg-crm-4529",
"port": 8282,
"last_upload": "",
"collection-rate": "low",
"remove_proxy_os_env": false,
"tables-monitoring-limit": 1000,
"query-monitoring-limit": 30000,
"sql-max-size": 256000,
"start_time": "2023-03-18 15:45:31",
"proxy": {
   "host": "",
   "port": 0,
   "user": "",
   "password": ""
},
"upload_server": {
   "host": "51.15.237.231",
   "port": 443
},
"connections": {
   "connections": 1,
   "running": 1,
   "not running": 0
 }
}

Most of the operations need a token to be passed in the headers calls.

Configuration Files

The agent stores its configuration on the hidden directory .datasentinel located in the user’s home directory.

2 files are present:

• agent.yml

• connections.yml

Agent properties can be directly modified through these files, except for passwords which are encrypted for security reasons.

Log File

The agent’s actions are recorded in the datasentinel.log file located in the log subdirectory of its distribution.

The log file is automatically rotated to remove outdated entries and manage data retention.

By default, the log level is set to INFO. To increase the log level, one can set it to debug in the [agent] section of the configuration file agent.yml.