search
Visit our websiteBlogRelease Notes

keyboardCLI

The agent offers a CLI for conveniently modifying attributes and connections.

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

hashtag
Prerequisites

Enable the execution of the CLI

  • Using an alias

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

  • Using environment variables

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

hashtag
Agent Management

hashtag
Show Commands

  • Simply enter the datasentinel command.

datasentinel
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

hashtag
Status

hashtag
Start

hashtag
Stop

hashtag
Change Port Number

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

hashtag
Change Table Monitoring 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).

hashtag
Change Query monitoring Limit

Since agent version 3.2

  • 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)

hashtag
Change Use Postgres Queryid

Since agent version 3.9

  • Parameter:

    Enable or disable the use of queryid as the query identifier in the UI. Refer to the detailed documentation for more information.

hashtag
Upload Server

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

hashtag
Set

  • Change the server where metrics are sent

hashtag
Show

Show the platform server where metrics are sent

hashtag
Test

hashtag
Token

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

hashtag
Show

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

hashtag
Proxy

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

hashtag
Set

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

hashtag
Show

hashtag
Delete

hashtag
Connections

hashtag
Show

hashtag
Enable All

hashtag
Disable All

hashtag
Connection

hashtag
Add

  • Create a JSON file with connection settings

hashtag
Show

  • Parameter

    The connection name

hashtag
Dump

Dump connection properties in JSON format

  • Parameter

    The connection name

hashtag
Delete

  • Parameter

    The connection name

hashtag
Enable

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

  • Parameter

    The connection name

hashtag
Disable

  • Parameter

    The connection name

hashtag
Update

  • Parameter

    The connection name

hashtag
Collection Level

The Agent Version 3.2 introduces the Collection Level feature, which was released in February 2023 and allows you to choose the metrics to monitor.

hashtag
Query Samples

  • Parameter

    The connection name

hashtag
Lock Monitoring

  • Parameter

    The connection name

hashtag
Lock Monitoring Delay

  • Parameters

    The connection name Seconds

hashtag
Table Monitoring

  • Parameter

    The connection name

hashtag
Query Monitoring

  • Parameter

    The connection name

hashtag
Query Monitoring Optimize

  • Parameter

    The connection name

hashtag
Query Monitoring Min Calls

  • Parameters

    The connection name Minimum number of calls registered in pg_stat_statements

hashtag
Query Monitoring Min Time

  • Parameter

    The connection name Minimum total execution time (seconds)

hashtag
Internals

Since Agent Version 3.2

hashtag
Show Metrics

Displays internal metrics and caches for debugging purposes

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

  • Parameter

    The connection name

PreviousRelease NotesNextAPI

Last updated