Parameters and configuration

Parameters

--conf	Path to the configuration file.
--target\_databases	Path to the configuration file containing database targets.
--target\_agents	Path to the configuration file containing agent targets.
--custom\_queries	Path to the configuration file containing custom queries.

The configuration file (--conf)

agents_group_id= The ID of the group where agents will be created.
interval= The monitoring interval for agents in seconds.
user= The connection user.
password= The password for the user.
threads= The number of threads used for agent creation.
modules_prefix= The prefix for module names.
execute_custom_queries= Activate with 1 to enable the use of custom queries.
analyze_connections= Activate with 1 to enable connection monitoring.
engine_uptime= Activate with 1 to enable runtime monitoring.
query_stats= Activate with 1 to enable query statistics monitoring.
monitor_long_queries = Activate with 1 to enable query statistics long queries.
monitor_latch_requests = Activate with 1 to enable query statistics latch requests.
monitor_full_scans = Activate with 1 to enable query statistics full scans.
count_databases = Activate with 1 to enable databases count.
retrieve_memory_statistics = Activate with 1 to enable memory statistics.
retrieve_locks_statistics = Activate with 1 to enable locks statistics.
check_engine_performance = Activate with 1 to enable engine performance.
retrieve_buffer_statistics = Activate with 1 to enable buffer statistics.
retrieve_users_information = Activate with 1 to enable user information.
retrieve_cluster_state = Activate with 1 to retrieve cluster state.
retrieve_logs_statistics = Activate with 1 to enable logs statistics.
monitor_active_users = Activate with 1 to enable active users.
retrieve_transactions_statistics = Activate with 1 to transaction statistics.
monitor_filegroups_space = Activate with 1 to enable file groups space.
monitor_user_reserved_space = Activate with 1 to enable user reserved space.
monitor_backups = Activate with 1 to enable to monitor backups.
agent_per_database     = Activate with 1 to enable agents creation.
db_agent_prefix        = prefix to the databases
scan_databases         = Activate with 1 to monitor databases

[MODULE_NAMES]
database_size = < Module name, default : database_size >
database_usage = < Module name, default : database_usage >
restart_detection = < Module name, default : restart detection >
queries = < Module name, default : queries >
insert = < Module name, default : insert >
delete = < Module name, default : delete >
update = < Module name, default : update >
session_usage = < Module name, default : session usage >
database_count = < Module name, default : database_count >
server_startup = < Module name, default : server_startup >
lock_memory = < Module name, default : lock_memory >
connection_memory = < Module name, default : connection_memory >
optimizer_memory = < Module name, default : optimizer_memory >
sqlcache_memory = < Module name, default : sqlcache_memory >
total_memory = < Module name, default : total_memory >
deadlocks = < Module name, default : deadlocks >
lock_timeouts = < Module name, default : lock_timeouts >
lock_requests = < Module name, default : lock_requests >
lock_waits = < Module name, default : lock_waits >
buf_cachehit_ratio = < Module name, default : buf_cachehit_ratio >
free_connections = < Module name, default : free_connections >
page_reads = < Module name, default : page_reads >
page_writes = < Module name, default : page_writes >
latch_waits = < Module name, default : latch_waits >
full_scans = < Module name, default : full_scans >
locks_used = < Module name, default : locks_used >
workspace_memory = < Module name, default : workspace_memory >
average_waittime = < Module name, default : average_waittime >
server_cpu = < Module name, default : server_cpu >
server_io = < Module name, default : server_io >
active_connection_ratio = < Module name, default : active_connection_ratio >
locked_users = < Module name, default : locked_users >
blocked_users = < Module name, default : blocked_users >
active_users = < Module name, default : active_users >
long_queries = < Module name, default : long_queries >
long_queries_string = < Module name, default : long_queries_string >
aag_cluster_quorum_state = < Module name, default : aag_cluster_quorum_state >
aag_cluster_members_state = < Module name, default : aag_cluster_members_state >
aag_synchronization_health = < Module name, default : aag_synchronization_health >
aag_replica_synchronization_health = < Module name, default : aag_replica_synchronization_health >
aag_replica_connected_state = < Module name, default : aag_replica_connected_state >
aag_replica_recovery_health = < Module name, default : aag_replica_recovery_health >
aag_replica_operational_state = < Module name, default : aag_replica_operational_state >
aag_db_replica_synchronization_state = < Module name, default : aag_db_replica_synchronization_state >
aag_listener_state = < Module name, default : aag_listener_state >

availability = < Module name, default : availability >
state = < Module name, default : state >
db_active_users = < Module name, default : active users >
transactions = < Module name, default : transactions >
active_transactions = < Module name, default : active_transactions >
log_flush_waits = < Module name, default : log_flush_waits >
log_file_growths = < Module name, default : log_file_growths >
log_file_shrinks = < Module name, default : log_file_shrinks >
logfile_size = < Module name, default : logfile_size >
logfile_usage = < Module name, default : logfile_usage >
log_cachehit_ratio = < Module name, default : log_cachehit_ratio >
backup_status_minutes = < Module name, default : backup_status_minutes >
backup_status_last_backup = < Module name, default : backup_status_last_backup >
fg_free_space = < Module name, default : fg_free_space >

Example

agents_group_id = 10
interval = 300
user = sa 
password = HHgD85V@
threads = 1
modules_prefix = 
execute_custom_queries = 1
analyze_connections = 1
engine_uptime = 1
query_stats = 1
monitor_long_queries = 1
monitor_latch_requests = 1 
monitor_full_scans = 1
count_databases = 1
retrieve_memory_statistics = 1
retrieve_locks_statistics = 1
check_engine_performance = 1
retrieve_buffer_statistics = 1 
retrieve_users_information = 1
retrieve_cluster_state = 1
retrieve_logs_statistics = 1 
monitor_active_users = 1
retrieve_transactions_statistics = 1
monitor_filegroups_space = 1
monitor_user_reserved_space = 1
monitor_backups = 1
agent_per_database     = 1
db_agent_prefix        = PANDORA-
scan_databases         = 1

[MODULE_NAMES]
database_size = database_size
database_usage = database_usage
restart_detection = restart detection
queries = queries
insert = insert
delete = delete
update = update
session_usage = session usage
database_count = database_count
server_startup = server_startup
lock_memory = lock_memory
connection_memory = connection_memory
optimizer_memory = optimizer_memory
sqlcache_memory = sqlcache_memory
total_memory = total_memory
deadlocks = deadlocks
lock_timeouts = lock_timeouts
lock_requests = lock_requests
lock_waits = lock_waits
buf_cachehit_ratio = buf_cachehit_ratio
free_connections = free_connections
page_reads = page_reads
page_writes = page_writes
latch_waits = latch_waits
full_scans = full_scans
locks_used = locks_used
workspace_memory = workspace_memory
average_waittime = average_waittime
server_cpu = server_cpu
server_io = server_io
active_connection_ratio = active_connection_ratio
locked_users = locked_users
blocked_users = blocked_users
active_users = active_users
long_queries = long_queries
long_queries_string = long_queries_string
aag_cluster_quorum_state = aag_cluster_quorum_state
aag_cluster_members_state = aag_cluster_members_state
aag_synchronization_health = aag_synchronization_health
aag_replica_synchronization_health = aag_replica_synchronization_health
aag_replica_connected_state = aag_replica_connected_state
aag_replica_recovery_health = aag_replica_recovery_health
aag_replica_operational_state = aag_replica_operational_state
aag_db_replica_synchronization_state = aag_db_replica_synchronization_state
aag_listener_state = aag_listener_state

availability = availability
state = state
db_active_users = active users
transactions = transactions
active_transactions = active_transactions
log_flush_waits = log_flush_waits
log_file_growths = log_file_growths
log_file_shrinks = log_file_shrinks
logfile_size = logfile_size
logfile_usage = logfile_usage
log_cachehit_ratio = log_cachehit_ratio
backup_status_minutes = backup_status_minutes
backup_status_last_backup = backup_status_last_backup
fg_free_space = fg_free_space

List of target databases (--target_databases)

The file will contain a list of target instances, with each database separated by commas or lines. The format for a database can be any of the following:

ip
ip:puerto
ip\instancia

Example

172.17.0.4:1433\DEVENV
172.17.0.2:1433\PRODENV

If you want to monitor specific databases of an instance, you must specify them with "|" and separate each database with ";".

Example :

172.17.0.4:1433\DEVENV|pandora;testing;model

If you want to monitor all the databases of an instance, but discard some, you must specify “!” before the “|”.

Example:

172.17.0.4:1433\DEVENV!|pandora;testing;model

List of target agents (--target_agents)

The file will contain a list of agent names, separated by commas or lines. These agent names will be used to dump the information from each target database into the corresponding agent name, instead of letting the plugin generate the agent names automatically.

The position of each agent name in the list must match the position of the target database in its own list, i.e., the name for the first target database will be the first name in this list, bearing in mind that blank lines are ignored.

Example

agente1,,agente3
agente4
agente5,agente6,agente7,,agente9

Custom Queries (--custom_queries)

One module must be defined for each custom query to be monitored. Modules must follow this structure:

check_begin      --> Module opening tag
name             --> Module name
description      --> Module description
operation        --> Operation type: value (returns a single value) | full (returns all rows as string).
datatype         --> Module type: generic_data | generic_data_string | generic_proc.
min_warning      --> Minimum warning threshold
max_warning      --> Maximum warning threshold
str_warning      --> Warning string threshold
warning_inverse  --> Set to 1 to invert the warning threshold interval
min_critical     --> Minimum critical threshold
max_critical     --> Maximum critical threshold
str_critical     --> Critical string threshold
critical_inverse --> Set to 1 to invert the critical threshold interval
module_interval  --> This interval is calculated as a multiplier of the agent interval.
crontab          --> 5-field cron expression (minute, hour, day of month, month, day of week).
                    The query only runs when the current date/time matches the expression.
                    If not specified, the query runs on every interval.
                    Format: crontab <minute> <hour> <day_of_month> <month> <day_of_week>
                    Examples:
                      * * * * *      → every minute (always)
                      0 9 * * 1-5    → Monday to Friday at 09:00
                      */15 * * * *   → every 15 minutes
                      * 12-15 * * 1  → Mondays between 12:00 and 15:59
target           --> Custom query (only SELECT statements are allowed).
target_databases --> Instance agents where the module will be created, or database names where the module will be created.
                    To apply to all elements, specify "all" or leave it unspecified.
target_scope     --> Target element to which the custom query will be applied.
                    Can be: instances, databases, or all (default).
                    If not specified, it applies to both instances and databases.
ignore_databases --> Instance agents where the module should NOT be created, or database names to skip.
check_end        --> Module closing tag

Examples

Basic module (no crontab, runs on every interval)

check_begin
name Select 1
description Number of invalid objects
operation value
datatype generic_data
min_warning 5
target SELECT 1;
target_databases all
check_end

Module with database scope and ignore list

check_begin
name ConnectionCount
description Number of connections
operation value
datatype generic_data
min_warning 10
target SELECT COUNT(*) AS ConnectionCount FROM sys.dm_exec_sessions WHERE is_user_process = 1;
target_databases all
target_scope databases
ignore_databases master
check_end

Full operation module against a specific database

check_begin
name list_table_size_MB
description table size in MB
operation full
datatype generic_data
target SELECT SUM(reserved_page_count) * 8 / 1024.0 AS SizeMB FROM sys.dm_db_partition_stats WHERE object_id = OBJECT_ID('list');
target_databases pandora
check_end

Module with crontab (runs only Monday to Friday at 09:00)

check_begin
name daily_report
description Daily report query
operation value
datatype generic_data_string
target SELECT COUNT(*) AS today_records FROM daily_log WHERE date = CAST(GETDATE() AS DATE);
target_databases all
crontab 0 9 * * 1-5
check_end

Module with crontab (only during office hours 8:00–18:00)

check_begin
name active_office_users
description Active users during office hours
operation value
datatype generic_data
target SELECT COUNT(*) FROM users WHERE active = 1;
target_databases all
crontab * 8-17 * * 1-5
check_end

Module with crontab every 30 minutes

check_begin
name check_every_half_hour
description Check every 30 minutes
operation value
datatype generic_data
target SELECT COUNT(*) FROM sys.dm_exec_sessions;
target_databases all
crontab */30 * * * *
check_end

Crontab filter behavior

At the beginning of each plugin execution, all custom queries are evaluated.
Queries without the crontab field always run (classic behavior, backward compatible).
Queries with crontab are only included if the current date/time matches the cron expression.
Queries rejected by crontab do not generate database connections or SQL queries.
The filter runs once before spawning monitoring processes.

Cron expression format

The expression follows the standard 5-field format separated by spaces:

Field	Allowed values
Minute	0-59
Hour	0-23
Day of month	1-31
Month	1-12
Day of week	0-7 (0 and 7 = Sunday, 1 = Monday)

Each field supports the following formats:

* — any value
N — exact value (e.g. 5)
N-M — range (e.g. 9-17)
*/N — every N units (e.g. */15 = every 15 minutes)
N-M/N — range with step (e.g. 0-30/10 = 0, 10, 20, 30)
A,B,C — comma-separated list of values