DBX Agent Setting

Write the settings for the DBX agent in the whatap.conf file. For the options that can be set, see the following.

Default options

license String

To install the agent, set the project access key granted from the server. The project access key includes the agent's project and the encryption key for secured communication.
whatap.server.host String

Default 127.0.0.1,127.0.0.1

Specify the IP address of the collection server to transfer the data collected by the agent. If there are multiple IP addresses for collection server redundancy, use comma (,) as the delimiter. The collection server proxy daemon must be serviced in the listening state for the set IP address.

whatap.server.port String

Default 6600

Set the port of the collection server. Because only one port can be set, use the same port set in the "whatap_server_host" option.
dbms String

db2

Caution
If other option values are entered, data collection for monitoring may not work.

db String

Database name.

db_ip String

Set the IP address of the database server to be monitored.

db_port String

Set the port used for DB communication.

Data collection

db_param_enabled Boolean

Default true

It sets whether or not to collect the DB parameters.

connect_timeout Int

Default 15 (seconds)

Sets the database connection timeout. If the connection is not established within the set time, it is treated as a connection failure. This setting is unrelated to the execution time of collection queries.
db2_opt Int

Default 0

Set the active session's collection conditions. This option works only on DB2 11 or later.
- 0: Only the sessions whose activity_state is EXECUTING are collected.
- 1: The sessions whose activity_state is EXECUTING, RECEIVING, and SUSPENDED are all collected.
tablespace Int

Default 1

Sets whether to collect tablespace information. Set it to 0 or off to disable collection.
tablespace_interval Int

Default 60 (minutes)

Sets the interval for collecting tablespace information.
db2_plan_saving Boolean DBX agent v2.64.01 or later

Default false

Saves the execution plans of queries whose execution time is equal to or longer than the value of db2_plan_elapse. When the execution plan of the same SQL changes, the change history is saved.

To save execution plans, you must grant additional permissions to the monitoring account. For details, see To view execution plans.
db2_plan_elapse Int

Default 5 (seconds)

Sets the execution time threshold for queries whose execution plans are saved.
db2_plan_max_count Int

Default 50

Sets the maximum number of execution plans saved per collection cycle.
includePrefetch Boolean DBX agent v2.59.04 or later

Default true

Sets how the buffer pool hit ratio is calculated.
- true: Divides the number of synchronous hit pages, excluding asynchronous (prefetch) hits, by the number of logical reads.
- false: Divides the number of logical reads minus physical reads by the number of logical reads.
db2pd_hadr Boolean DBX agent v2.64.06 or later

Default false

Collects HADR information with db2pd. If set to true, the agent runs db2pd -db <db> -hadr on the DB server and collects the HADR role, state, connection status, synchronization mode, log gap, and replication delay from both the Primary and the Standby. If set to false, HADR information is collected with MON_GET_HADR, which works on DB2 10.5 or later.

A Standby that does not use Reads on Standby (ROS) does not accept DB connections, so you must enable this option to collect its HADR information. In this case, the agent does not connect to the DB and collects only HADR metrics. Other metrics, such as sessions and SQL, are not collected.
Note
- The agent must be installed on the DB server.
- The account running the agent must be able to run db2pd, and db2pd must be in the PATH of the agent process.
- db2pd runs with the DB name set in the db option.
- If db2pd does not finish within 10 seconds, it is treated as a failure. On a Standby that does not use ROS, a connection failure alert occurs when failures continue for the number of times set in conn_fail_count.

conn_fail_count Int

Default 15

It sends a notification when the connection error occurs consecutively 15 times. You can adjust the notification trigger criteria by entering the desired number.

long_run_session_sec Second

Default 10 (unit: second)

A session that has been running longer than the set time is treated as a long run session.

tables Boolean

Default true

Collects table size information once a day. Set the collection time with the tables_hour option.

tables_hour Int

Default 5

Set the time to collect data for storing the table size information. The default value is 5 and collection starts at 5 am.

tables_min_size Int

Default 10 (MB)

Tables smaller than the set value are not collected. The table size is the sum of the data, index, LONG, LOB, and XML areas.
tables_min_row Int

Default 10000

Tables with fewer rows than the set value are not collected. Because the row count is taken from catalog statistics, tables on which RUNSTATS has not been run may not be collected.
tables_exclude_sys Boolean

Default true

Excludes tables in the SYSIBM and SYSTOOLS schemas when collecting table information. If set to false, these tables are also collected.

skip_whatap_session Boolean

Default false

If set to true, the sessions running WhaTap collection queries do not appear in the active session list.

xview_min_sec Int

Default 0

When collecting xview, collection is performed only when the query execution time is longer than the set time. The default setting is to collect all queries whose execution time is longer than 0 seconds.

User Metric Collection (SQLMON)

SQLMON periodically collects the results of user-defined SQL queries and stores them as metrics.
It is suitable for lightweight queries that return numeric results.

sqlmon Int

Default value: 1
- 1: Run both dbx and sqlmon simultaneously
- 2: Run only sqlmon

Supported version: 2.3.5 or later

Configuration

Create a sqlmon directory under the dbx agent and create <filename>.sql files for the queries you want to collect.

dbx/
└── sqlmon/
    ├── active_sessions.sql
    └── lock_count.sql

Save the query to be collected as a <filename>.sql file.

Write the execution options on the first line and the SQL statement from the second line onward.

Option format
interval(min);run_time;tag_name
SQL statement

Item	Description	Example
Interval	Execution interval in minutes, minimum `1`	`1` → runs every 1 minute
Run time	`HHMM-HHMM` format, multiple ranges separated by comma (`,`). Set `0` to run at all times	`0900-1100` → runs only 09:00–11:00
Tag name	Tag name stored in metrics. If omitted, the file name is used as the tag name	`whatap`

Example: 1 min interval, 09:00–11:00, tag name whatap
1;0900-1100;whatap
SELECT count(*) FROM active_sessions

Example: 1 min interval, always running, file name as tag
1;0
SELECT count(*) FROM active_sessions

Note

Run time can span across dates. (e.g., 2300-0100 → 23:00 to 01:00 the next day)
When omitting the tag name, do not add a semicolon (;) after the run time.
Do not add a semicolon (;) at the end of the SQL statement.

Enable SQLMON in whatap.conf.
Restart the agent.
In the Sitemap > Metrics Search menu, check the sqlmon category.

# whatap.conf
sqlmon=1

Applying the AES 256 encryption

The WhaTap DBX agent transfers the collected data to the server after encryption. You can change this depending on the importance of the data or setting. Basically, the XOR operation and encryption through the AES algorithm are used, and encryption and decryption are performed by dividing the plain text into 128-bit units. It can be expanded up to 256 bits depending on the setting.

Add the following options to the whatap.conf file in the path where the WhaTap DBX agent has been installed.

whatap.conf
cypher_level=256

Add the settings and then restart the agent.

Agent name setting

Automatic configuration

If you do not set the agent name in the agent configuration (whatap.conf), the agent name is automatically determined by combining the IP address and the port number. For example, if the IP address is 10.11.12.13 and the port number is 3000, the agent name is set to DBX-12-13-3000.

The key variables that determine the agent name are as follows:

Configuration	Description
`{type}`	The DBX value is used.
`{ip0}`	The first byte of the IPv4 address is used. (e.g. 10 in 10.11.12.13)
`{ip1}`	The second byte of the IPv4 address is used. (e.g. 11 in 10.11.12.13)
`{ip2}`	The third byte of the IPv4 address is used. (e.g. 12 in 10.11.12.13)
`{ip3}`	The fourth byte of the IPv4 address is used. (e.g. 13 in 10.11.12.13)
`{port}`	Database server port

Note

If the IP address is not numeric like RDS, the name is set in the following format: DBX-{ip0}-{hash}-{port}, where the {hash} value is the IP address that has been converted to 4-digit hexadecimal number.

Manual configuration

To set the agent name manually, enter a desired name for the whatap.name or object_name option in the whatap.conf file. The entered name is assigned to the agent name.

whatap.conf
whatap.name=agent-1234
# or
object_name=agent-1234

Default options​

Data collection​

User Metric Collection (SQLMON)​

Configuration​

Applying the AES 256 encryption​

Agent name setting​

Automatic configuration​

Manual configuration​