# CLI

{% hint style="info" %}
The agent stores its configuration in the hidden **.datasentinel** directory within the user's home directory, using two files: **agent.yml** and **connections.yml**. \
These files can be manually managed if necessary.
{% endhint %}

## **Prerequisites**

Enable the execution of the CLI

* Using an alias

```bash
alias datasentinel='DATASENTINEL_PATH=<<INSTALL_DIRECTORY>>/datasentinel;LD_LIBRARY_PATH=$DATASENTINEL_PATH/lib/ $DATASENTINEL_PATH/datasentinel'
```

* Using environment variables

```bash
export DATASENTINEL_PATH="<<INSTALL_DIRECTORY>>/datasentinel"
export LD_LIBRARY_PATH=$DATASENTINEL_PATH/lib:$LD_LIBRARY_PATH
export PATH=$DATASENTINEL_PATH:$PATH
```

## **Agent Management**

### Show Commands

* Simply enter the **datasentinel** command.

```bash
datasentinel
```

{% code title="Response" %}

```
Copyright 2026 (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 30000)
                The agent tracks query activity, storing unique IDs in a daily cache. Exceeding limit triggers automatic deactivation of query monitoring.
         - set use-postgres-queryid <on|off>    (default off) 
                If on, the query_md5_id tag contains PostgreSQL’s internal query identifier (queryid) instead of an MD5 hash computed from the query text (across all connections >= PostgreSQL 14).
   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

         - update connection <name> use-postgres-queryid <on|off> (default off)
                If on, the query_md5_id tag contains PostgreSQL’s internal query identifier (queryid) instead of an MD5 hash computed from the query text (for versions >= 14)
                Inherits the global agent setting if not defined at connection level
                              
         - 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 %}

### Status

```bash
datasentinel status agent
```

{% code title="Response" %}

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

               Agent
                  Version : 3.9.0                                             
                   Server : pg-crm-4743                                       
                     Port : 8282                                              
               Start time : 2026-01-29 18:06:43                               
          Collection rate : low                                               
   Table monitoring limit : 1000                                              
   Query monitoring limit : 30000                                             
     Use postgres queryid : off                                               
             Sql max size : 256000                                            

               Proxy
                     host :                                                   
                     port : 0                                                 
                     user :                                                   
                 password :                                                   

              Upload
                     host : demo.datasentinel.io                              
                     port : 443                                               

         Connections
                 declared : 1                                                 
                  running : 1                                                 
              not running : 0   
```

{% endcode %}

### Start

```bash
datasentinel start agent
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Starting the agent...


To show the status : datasentinel status agent
```

{% endcode %}

### Stop

```bash
datasentinel stop agent
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

The agent is stopped!
```

{% endcode %}

### Change Port Number

> By default, the agent is configured to listen on port 8282, enabling API or CLI calls to be made.

```bash
datasentinel set port 9121
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Agent port successfully set! The agent has been stopped, you need to restart it
```

{% endcode %}

### Change Table Monitoring Limit

```bash
datasentinel set tables-monitoring-limit <limit>
```

* Parameter:

  > The limit number.\
  > The agent tracks the activity of tables and indexes if the connection’s table count is below the set limit (default **1000**).

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Tables monitoring limit successfully set to 3000!


                Agent
                    Version : 3.2.0
                    Server : pgsentinel.localdomain
                      Port : 8282
                Start time : 2023-01-31 13:08:27
            Collection rate : low
    Table monitoring limit : 2500
    Query monitoring limit : 35000
              Sql max size : 7512453

                Proxy
                      host :
                      port : 0
                      user :
                  password :

                Upload
                      host : 163.172.135.154
                      port : 443

          Connections
                  declared : 2
                    running : 1
                not running : 1
```

{% endcode %}

### Change Query monitoring Limit

> Since agent version 3.2

```bash
datasentinel set query-monitoring-limit <limit>
```

* Parameter:

  > The limit number.\
  > The agent tracks query activity, storing unique IDs in a daily cache. Exceeding limit triggers automatic deactivation of query monitoring. (default 30000)

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Tables monitoring limit successfully set to 3000!


                Agent
                    Version : 3.2.0
                    Server : pgsentinel.localdomain
                      Port : 8282
                Start time : 2023-01-31 13:08:27
            Collection rate : low
    Table monitoring limit : 2500
    Query monitoring limit : 35000
              Sql max size : 7512453

                Proxy
                      host :
                      port : 0
                      user :
                  password :

                Upload
                      host : 163.172.135.154
                      port : 443

          Connections
                  declared : 2
                    running : 1
                not running : 1
```

{% endcode %}

### Change Use Postgres Queryid

> Since agent version 3.9

```bash
datasentinel set use-postgres-queryid on|off
```

* Parameter:

  > Enable or disable the use of `queryid` as the query identifier in the UI.\
  > Refer to the [detailed documentation](https://docs.datasentinel.io/manual/features/tips-and-hints/query-identifier) for more information.

{% code title="Response" %}

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

Usage of postgres queryid successfully set to on!


               Agent
                  Version : 3.9.0                                             
                   Server : pg-crm-4743                                       
                     Port : 8282                                              
               Start time : 2026-01-29 18:06:43                               
          Collection rate : low                                               
   Table monitoring limit : 1000                                              
   Query monitoring limit : 30000                                             
     Use postgres queryid : on                                                
             Sql max size : 256000                                            

               Proxy
                     host :                                                   
                     port : 0                                                 
                     user :                                                   
                 password :                                                   

              Upload
                     host : demo.datasentinel.io                              
                     port : 443                                               

         Connections
                 declared : 1                                                 
                  running : 1                                                 
              not running : 0                 
```

{% endcode %}

## **Upload Server**

> The Upload Server refers to the server name of the platform where metrics are transmitted.

### Set

* Change the server where metrics are sent

```bash
datasentinel set server app.datasentinel.io 443
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Server successfully set!


        Server
                host : app.datasentinel.io
                port : 443
```

{% endcode %}

### Show

> Show the platform server where metrics are sent

```bash
datasentinel show server
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

        Server
                host : app.datasentinel.io
                port : 443
```

{% endcode %}

### Test

```bash
datasentinel test server
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

TEST: The upload server is reachable and up!


        Server
                host : app.datasentinel.io
                port : 443
```

{% endcode %}

## **Token**

### Set

> Configure the authentication token used to access the platform.\
> This should only be done during initialization. The agent subsequently retrieves updated tokens from the platform.

```bash
datasentinel set token <token value>
```

{% code title="Response" %}

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

Token successfully set!


          Server
                  host : app.datasentinel.io
                  port : 443
```

{% endcode %}

### Show

> After testing the token on the platform's upload server, the validity date of the token is provided.

```bash
datasentinel show token
```

{% code title="Response" %}

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

                    Token : <token value>

            Organization : ds-data
          Expiration Date : 2023-07-22 18:09:29
```

{% endcode %}

## **Proxy**

> Under certain circumstances, an intermediary proxy server is required to establish a connection between the agent and the platform server.

### Set

* create a json file with proxy settings and update the agent

{% code title="JSON description" %}

```bash
cat > proxy.json << EOF
{
    "host": "myProxyHostName",
    "port": 4587,
    "user": "username (optional)",
    "password": "value (optional)"
}
EOF
```

{% endcode %}

```bash
datasentinel set proxy -f proxy.json
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Proxy successfully set!


          Proxy
                host : myProxyHostName
                port : 4587
                user :
            password :
```

{% endcode %}

### Show

```bash
datasentinel show proxy
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

          Proxy
                host : hostname
                port : 4587
                user :
            password :
```

{% endcode %}

### Delete

```bash
datasentinel delete proxy
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Proxy successfully deleted!


          Proxy
                host :
                port : 0
                user :
            password :
```

{% endcode %}

## **Connections**

### Show

```bash
datasentinel show connections
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

name                 status     state      host                 port   user
--------------------------------------------------------------------------------
:9342                enabled    running    pg-sales-1734          9342 datasentinel
  tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

### Enable All

```bash
datasentinel enable all
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connections enabled!


name                 status     state      host                 port   user
--------------------------------------------------------------------------------
:9342                enabled    running    pg-sales-1734          9342 datasentinel
  tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

### Disable All

```bash
datasentinel disable all
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connections disabled!


name                 status     state      host                 port   user
--------------------------------------------------------------------------------
:9342                disabled   not running pg-sales-1734          9342 datasentinel
  tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

## **Connection**

### Add

* Create a JSON file with connection settings

{% code title="JSON" %}

```bash
cat > newConnection.json << EOF
{
    "host": "pg-sales-1734",
    "port": 9342,
    "user": "datasentinel",
    "password": "sentinel",
    "tags": "application=sales,environment=production,provider=amazon,datacenter=lyon",
}
EOF
```

{% endcode %}

```bash
datasentinel add connection myNewConnection -f newConnection.json
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connection added!


                   Name : myNewConnection
                 Status : enabled
                  State : connected

                   Host : pg-sales-1734
                   Port : 9342

                   user : datasentinel
               password : sentinel

        Lock monitoring : on
  Lock monitoring delay : 30s
       Table monitoring : on

          Query samples : off

       Query monitoring : on
               Optimize : on
              Min calls : 2
               Min time : 1s
               
   Use postgres queryid : off                                               

                   tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

### Show

```bash
datasentinel show connection myNewConnection
```

* Parameter

  > The connection name

{% code title="Response" %}

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

                     Name : myNewConnection                                            
                   Status : enabled                                           
                    State : connected                                         

                     Host : pg-crm-4743                                       
                     Port : 9342                                              

                     user : datasentinel                                      
                 password : sentinel                                          

          Lock monitoring : on                                                
    Lock monitoring delay : 30s                                               
         Table monitoring : on                                                

            Query samples : off                                               

         Query monitoring : on                                                
                 Optimize : off                                               
                Min calls : 2                                                 
                 Min time : 1s                                                

     Use postgres queryid : off                                               

                     tags : application=crm,environment=production,provider=on-premises,datacenter=paris
```

{% endcode %}

### Dump

> Dump connection properties in JSON format

```bash
datasentinel dump connection myNewConnection
```

* Parameter

  > The connection name

{% code title="Response" %}

```json
{
    "name": "myNewConnection",
    "host": "pg-sales-1734",
    "port": 9342,
    "user": "datasentinel",
    "password": "sentinel",
    "tags": "application=sales,environment=production,provider=amazon,datacenter=lyon ",
    "enabled": true,
    "connected": true,
    "collection-rate": "low",
    "samples": false,
    "lock-monitoring": true,
    "lock-monitoring-delay": 30,
    "table-monitoring": true,
    "query-monitoring": true,
    "query-monitoring-optimize": true,
    "query-monitoring-min-calls": 2,
    "query-monitoring-min-time": 1,
    "use-postgres-queryid": false,
}
```

{% endcode %}

### Delete

```bash
datasentinel delete connection myNewConnection
```

* Parameter

  > The connection name

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connection successfully deleted!
```

{% endcode %}

### Enable

> Activate the connection and initiate connection attempts in order to start monitoring

```bash
datasentinel enable connection myNewConnection
```

* Parameter

  > The connection name

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connection enabled!


                  Name : myNewConnection
                Status : enabled
                State : connected

                  Host : pg-sales-1734
                  Port : 9342

                  user : datasentinel
              password : sentinel

      Lock monitoring : on
Lock monitoring delay : 30s
      Table monitoring : on

        Query samples : off

      Query monitoring : on
              Optimize : on
            Min calls : 2
              Min time : 1s

                  tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

### Disable

```bash
datasentinel disable connection myNewConnection
```

* Parameter

  > The connection name

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connection disabled!


                  Name : myNewConnection
                Status : enabled
                State : connected

                  Host : pg-sales-1734
                  Port : 9342

                  user : datasentinel
              password : sentinel

      Lock monitoring : on
Lock monitoring delay : 30s
      Table monitoring : on

        Query samples : off

      Query monitoring : on
              Optimize : on
            Min calls : 2
              Min time : 1s

                  tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

### Update

```bash
cat > updateConnection.json << EOF
{
    "host": "pg-sales-1734",
    "port": 9342,
    "user": "datasentinel",
    "password": "sentinel",
    "tags": "application=sales,environment=production,provider=microsoft,datacenter=paris",
}
EOF
```

```bash
datasentinel update connection myNewConnection -f updateConnection.json
```

* Parameter

  > The connection name

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connection updated!


                    Name : myNewConnection
                  Status : enabled
                  State : connected

                    Host : pg-sales-1734
                    Port : 9342

                    user : datasentinel
                password : sentinel

        Lock monitoring : on
  Lock monitoring delay : 30s
        Table monitoring : on

          Query samples : off

        Query monitoring : on
                Optimize : on
              Min calls : 2
                Min time : 1s

                    tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

## **Collection Level**

> The Agent Version 3.2 introduces the [Collection Level](https://docs.datasentinel.io/manual/implementation/agent-usage/collection-level) feature, which was released in February 2023 and allows you to choose the metrics to monitor.

### Query Samples

```bash
datasentinel update connection ":9342" samples on|off
```

* Parameter

  > The connection name

### Lock Monitoring

```bash
datasentinel update connection ":9342" lock-monitoring on|off
```

* Parameter

  > The connection name

### Lock Monitoring Delay

```bash
datasentinel update connection ":9342" lock-monitoring-delay <seconds>
```

* Parameters

  > The connection name\
  > Seconds

### Table Monitoring

```bash
datasentinel update connection ":9342" table-monitoring on|off
```

* Parameter

  > The connection name

### Query Monitoring

```bash
datasentinel update connection ":9342" query-monitoring on|off
```

* Parameter

  > The connection name

### Query Monitoring Optimize

```bash
datasentinel update connection ":9342" query-monitoring-optimize on|off
```

* Parameter

  > The connection name

### Query Monitoring Min Calls

```bash
datasentinel update connection ":9342" query-monitoring-min-calls <value>
```

* Parameters

  > The connection name\
  > Minimum number of calls registered in **pg\_stat\_statements**

### Query Monitoring Min Time

```bash
datasentinel update connection ":9342" query-monitoring-min-time <seconds>
```

* Parameter

  > The connection name\
  > Minimum total execution time (seconds)

## **Internals**

> Since Agent Version 3.2

### Show Metrics

> Displays internal metrics and caches for debugging purposes

```bash
datasentinel show metrics
```

{% code title="JSON output" %}

```json
{
  "version": "3.9.0",
  "port": 8282,
  "start_time": "2026-01-31 13:08:27",
  "memory": "59MB",
  "threads": 18,
  "pg_connections": 2,
  "running": 1,
  "not_running": 1,
  "connections": [
    {
      "name": "test",
      "stat_statements": 0,
      "stat_statements_cache": 0,
      "stat_plans_cache": 0,
      "query_ids_cache": 0,
      "missing_query_ids": 0,
      "plan_ids_cache": 0,
      "cache_tables": 0,
      "table_stats_cache": 0,
      "index_stats_cache": 0,
      "normal_task_runtime": 0,
      "low_task_runtime": 0,
      "tables_monitoring_limit": 2500,
      "query_monitoring": true,
      "query_monitoring_limit": 35000,
      "query_monitoring_min_calls": 2,
      "query_monitoring_min_time": 1,
      "query_monitoring_optimize": true,
      "xa_trans_optimized": 0,
      "insert_values_optimized": 0,
      "in_list_query_optimized": 0,
      "execution_plan_optimized": 0,
      "samples": false,
      "lock_monitoring": true,
      "lock_monitoring_delay": 10,
      "pool_used": 0
    },
    {
      "name": "test_connection",
      "stat_statements": 109,
      "stat_statements_cache": 109,
      "stat_plans_cache": 52,
      "query_ids_cache": 51,
      "missing_query_ids": 0,
      "plan_ids_cache": 48,
      "cache_tables": 1,
      "table_stats_cache": 148,
      "index_stats_cache": 352,
      "normal_task_runtime": 1663,
      "low_task_runtime": 12069,
      "tables_monitoring_limit": 2500,
      "query_monitoring": true,
      "query_monitoring_limit": 35000,
      "query_monitoring_min_calls": 21,
      "query_monitoring_min_time": 33,
      "query_monitoring_optimize": true,
      "xa_trans_optimized": 0,
      "insert_values_optimized": 23,
      "in_list_query_optimized": 1,
      "execution_plan_optimized": 0,
      "samples": true,
      "lock_monitoring": true,
      "lock_monitoring_delay": 10,
      "pool_used": 3
    }
  ]
}
```

{% endcode %}

### Test Query Monitoring Optimization

> The Query Optimize feature fetches queries from **pg\_stat\_statements**, filtered by minimum calls or minimum total execution time, groups similar queries, and shows the optimization gain at each level.

```bash
datasentinel update connection ":9342" test-query-monitoring-optimize
```

* Parameter

  > The connection name

{% code title="JSON output" %}

```json
{
  "pg_stat_statements": 964,
  "min_calls_filter": 21,
  "min_time_filter": "33s",
  "filtered_statements_get_time": "153ms",
  "filtered_statements_with_min_calls_or_min_time": 109,
  "filtered_ratio": "89%",
  "optimized_statements": 109,
  "optimized_ratio": "0%",
  "optimized_statements_run_time": "8ms"
}
```

{% endcode %}