# Agent

{% hint style="info" %}
Datasentinel requires the installation of the **pg\_stat\_statements** extension within your PostgreSQL instances.

Refer to the installation guide for [pg\_stat\_statements](https://docs.datasentinel.io/manual/getting-started/postgresql-clusters/extensions/pg_stat_statements) and instructions on setting the recommended parameters. \
The extension mut be installed on the internal  database named **postgres**
{% endhint %}

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

## Step-by-Step Installation Instructions

{% hint style="info" %}
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.
{% endhint %}

<table><thead><tr><th width="182.33333333333331">Date</th><th>Last available agent version</th><th></th></tr></thead><tbody><tr><td>2026-02-02</td><td><strong>3.9.1</strong></td><td><a href="../../implementation/agent-usage/release-notes">Release Notes</a></td></tr></tbody></table>

{% stepper %}
{% step %}

### Download file

* [RedHat/Centos/AlmaLinux 9](https://app.datasentinel.io/ds-api/download/datasentinel-agent-rhel9-latest.tar.gz)
* [RedHat/Centos/AlmaLinux 8](https://app.datasentinel.io/ds-api/download/datasentinel-agent-rhel8-latest.tar.gz)
* [RedHat/Centos 7](https://app.datasentinel.io/ds-api/download/datasentinel-agent-rhel7-latest.tar.gz)
* (Deprecated) [RedHat/Centos 6](https://app.datasentinel.io/ds-api/download/datasentinel-agent-rhel6-latest.tar.gz)
* [Debian Buster / Bullseye](https://app.datasentinel.io/ds-api/download/datasentinel-agent-debian-buster-latest.tar.gz)
* (Deprecated) [Debian Stretch](https://app.datasentinel.io/ds-api/download/datasentinel-agent-debian-stretch-latest.tar.gz)
* (Deprecated) [Debian Jessie](https://app.datasentinel.io/ds-api/download/datasentinel-agent-debian-jessie-latest.tar.gz)

*The file size is approximately 35 MB.*

{% endstep %}

{% step %}

### Install and start the agent

{% hint style="info" %}
Whenever possible, avoid using the root account.
{% endhint %}

Uncompress the downloaded file

```bash
tar xvzf datasentinel-agent-rhel9.tar.gz
```

There are two ways to start the agent:

* Using an alias

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

* By setting environment variables

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

{% hint style="info" %}
`LD_LIBRARY_PATH=$DATASENTINEL_PATH/lib` is optional and only needed in case of shared library loading errors.
{% endhint %}
{% endstep %}

{% step %}

### Test the status

```bash
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
```

{% hint style="warning" %}
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"?](https://docs.datasentinel.io/manual/faqs/agent-faq#what-could-be-the-reason-if-the-agent-is-running-but-the-cli-responds-with-no)
{% endhint %}

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](https://docs.datasentinel.io/manual/implementation/agent-usage/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:

```bash
// Example
export DATASENTINEL_AGENT_HOST=172.16.250.199
```

{% hint style="info" %}
The server name will also be utilized to generate the distinctive pg\_instance tag, uniquely identifying instances across the entire platform.

\
\&#xNAN;*pg\_instance is formed by concatenating the server name with **@**  and the connection name. Refer to* [*Tags section*](https://docs.datasentinel.io/manual/features/tips-and-hints/tags) *for more details*
{% endhint %}
{% endstep %}

{% step %}

### 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.

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

{% endstep %}

{% step %}

### 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.

```bash
// 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`

{% endstep %}

{% step %}

### Check platform and token

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

```bash
datasentinel show token
```

{% endstep %}

{% step %}

### Automatic Startup Configuration

It's adviced to configure automatic startup of the agent at server startup and to avoid [unexpected agent stops](https://docs.datasentinel.io/manual/implementation/troubleshooting/unexpected-agent-termination)

This example below requires [**Agent version 3.9 or later**](https://docs.datasentinel.io/manual/implementation/agent-usage/release-notes), 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`&#x20;

```bash
## 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

```bash
$ 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.
```

{% endstep %}
{% endstepper %}

## PostgreSQL

Example of configuring and adding a connection. Refer to [PostgreSQL clusters](https://docs.datasentinel.io/manual/getting-started/postgresql-clusters) for more details

{% hint style="danger" %}
The [pg\_stat\_statements](https://docs.datasentinel.io/manual/getting-started/postgresql-clusters/extensions/pg_stat_statements) extension must be installed in the internal database named **postgres** before monitoring a cluster.&#x20;
{% endhint %}

### User

**Version >= 10**

```sql
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;
```

{% hint style="info" %}
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.
{% endhint %}

<details>

<summary>Version &#x3C; 10</summary>

The user must have the role superuser

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

</details>

{% hint style="warning" %}
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.&#x20;

<pre class="language-sql"><code class="lang-sql"><strong>ALTER USER datasentinel SET search_path TO "$user", public;
</strong><strong>// Connect with datasentinel user
</strong><strong>SHOW search_path;
</strong></code></pre>

{% endhint %}

### 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
```

{% hint style="info" %}
The user needs to be able to connect to **ALL** databases.
{% endhint %}

* Reload the configuration

```sql
select pg_reload_conf();
```

### Add Instance

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

{% hint style="info" %}
Replace **MyConnectionName** with a meaningful connection name in your environment.
{% endhint %}

```bash
datasentinel add connection myConnectionName -f myInstance.json
```

{% hint style="info" %}
A script is present in the **datasentinel** subdirectory as an example named **connection\_example.sh**
{% endhint %}

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.

{% content-ref url="../../features/tips-and-hints/tags" %}
[tags](https://docs.datasentinel.io/manual/features/tips-and-hints/tags)
{% endcontent-ref %}

## Useful CLI commands

{% content-ref url="../../implementation/agent-usage/cli" %}
[cli](https://docs.datasentinel.io/manual/implementation/agent-usage/cli)
{% endcontent-ref %}

* Display the agent status

```bash
datasentinel status agent
```

* Display the connections

```bash
datasentinel show connections
```

{% hint style="info" %}
For a comprehensive list of options, simply type **datasentinel** without any arguments
{% endhint %}

```bash
datasentinel
```

{% code overflow="wrap" %}

```
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
```

{% endcode %}

## API

{% hint style="info" %}
All operations are available through [Agent API](about:blank/agent/API.html#agent-apis).
{% endhint %}

{% content-ref url="../../implementation/agent-usage/api-reference" %}
[api-reference](https://docs.datasentinel.io/manual/implementation/agent-usage/api-reference)
{% endcontent-ref %}

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

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

```json
{
"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
 }
}
```

{% hint style="info" %}
Most of the operations need a token to be passed in the headers calls.
{% endhint %}

## 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`

{% hint style="info" %}
Agent properties can be directly modified through these files, except for passwords which are encrypted for security reasons.
{% endhint %}

## 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`.