>
```
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](/manual/implementation/troubleshooting/unexpected-agent-termination.md)
This example below requires [**Agent version 3.9 or later**](/manual/implementation/agent-usage/release-notes.md), 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`
```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](/manual/getting-started/postgresql-clusters.md) for more details
{% hint style="danger" %}
The [pg\_stat\_statements](/manual/getting-started/postgresql-clusters/extensions/pg_stat_statements.md) extension must be installed in the internal database named **postgres** before monitoring a cluster.
{% 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 %}
Version < 10
The user must have the role superuser
```sql
create user datasentinel password 'myPassword';
alter user datasentinel with superuser;
```
{% 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.
ALTER USER datasentinel SET search_path TO "$user", public;
// Connect with datasentinel user
SHOW search_path;
{% 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 <
- set collection-rate
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 -f
- update connection -f
json example: {
"host": "hostname",
"port": 4587,
"user": "username",
"password": "value",
"tags": "key=value,key=value,..."
}
- update connection samples (default off)
Collect and send sample queries, with literal values if present
- update connection lock-monitoring (default on)
Scan blocking sessions (longer than lock-monitoring-delay) and send blocking reports
- update connection lock-monitoring-delay (default 30)
Minimum number of seconds before triggering a blocking scenario
- update connection table-monitoring (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 query-monitoring (default on)
Monitor pg_stat_statements query activity
- update connection query-monitoring-optimize (default on)
Group similar pg_stat_statements queries
- update connection query-monitoring-min-calls (default 2)
- update connection query-monitoring-min-time (default 1)
Retrieve pg_stat_statements queries executed n times (calls) OR with total execution time exceeding specified seconds
- update connection test-query-monitoring-optimize
Test and optimize pg_stat_statements query contents with previous parameters, display results
- delete connection
- enable connection
- disable connection
- show connections
- show connection
Dump connection in JSON format:
- dump connection
Upload server:
- set server
- show server
- test server
Token:
- set token
- show token
Proxy:
- set proxy -f
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="/pages/J9dSGVENOsIzGxqxpoKG" %}
[API Reference](/manual/implementation/agent-usage/api-reference.md)
{% 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`.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.datasentinel.io/manual/getting-started/installation/agent.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.