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

  mysql

  Caution

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

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

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

• deadlock_interval Int

  Default 60

  Set the interval (unit: minute) to fetch the deadlock data. For deadlock information, only the latest deadlock information that occurred during the set interval is retrieved.

• 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

  It collects the table size information. In Stat/Report > DB size, you can see the table size by selecting the database.

• table_filesize Boolean

  Default true

  When collecting the table size, the file_size of innodb_tablespaces is also collected.

• 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_row Int

  Default 10000

  When collecting the table information, table data with the number of rows smaller than the set value is not collected.

• replication_name String

  If you set the replication name, it is considered that there is a Master/Slave relationship between DBs with the same replication_name.

  As an option to define the replication set, if you set the replication_name option that has the same value for both master and slave nodes, the Monitoring a Database Instance displays a tree structure. It also provides a widget to monitor the replication status in Flex Board based on the option value.

• skip_whatap_session Int

  Default 0

  If you set 1, the session in which the query to collect from WhaTap operates, does not appear in the active session list. (Default value: 0)

• skip_sys_session Int

  Default 1

  If set to 2, the sys sessions (root, system user, event_scheduler) are not visible in the active session. The set value, 1 makes sys sessions visible, but excludes them from the total runtime.

• save_literal_param Boolean

  Default true

  It sets whether or not to collect literal parameters. If set to false, literal parameters are not collected.

• sqlstat_send_interval Int

  Default: 5 minutes

  Sets the interval for generating and sending SQL statistics data. You can set it to either 1 or 5 minutes. If you require more precise per-minute statistical analysis, set it to 1. This setting enables detailed per-minute analysis in the Top SQL screen.

• statements_min_row Int

  Default 10000 (row)

  It is the data collection criteria used in the MYSQL SQL Statistics menu. It queries performance_schema.events_statements_summary_by_digest and collects data if the following sum is greater than statements_min_row.

  sum_rows_affected + sum_rows_sent + sum_rows_examined

  Note

  For more information about the MYSQL SQL Statistics menu, see the following.

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

• trx_rseg_history_len Boolean MySQL 5.7 or later DBX agent v1.6.15 or later

  Default false

  It sets whether or not to collect the trx_rseg_history_len metric. If it is set to true, you can check it in the db_mysql_counter category.

• active_transactions Boolean MySQL 5.5 or later DBX agent v1.6.15 or later

  Default false

  It sets whether or not to collect the active_transactions metric. If it is set to true, you can check it in the db_mysql_counter category.

• collect_variables_metric Boolean DBX agent v1.6.15 or later

  Default false

  DB parameters can be collected in real time. The parameters set in the variables_metric option are collected.

• variables_metric String DBX agent v1.6.15 or later

  Set the DB parameter names such as uptime, version, and read_only. To set multiple values, use comma (,) as the delimiter. If you set the collect_variables_metric option to true and set the DB parameter names, you can check them in the db_mysql_variables category.

  whatap.conf

  collect_variables_metric=true
  variables_metric=uptime,version

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

1. Create a sqlmon directory in the agent installation path.
2. Save the query to be collected as a .sql file.
3. Enable SQLMON in whatap.conf.
4. Restart the agent.
5. In the Sitemap > Metrics Search menu, check the sqlmon category.

# whatap.conf
sqlmon=1

Lock Collection Settings

If the target DB for monitoring is MySQL 8.0 or later and the version of the DBX agent is 2.53.01 or later, you can provide various lock monitoring collection conditions.

• lock Boolean

  Default true

  Set whether to collect locks.

• skip_lock_active_limit Int

  Default 150

  When the number of active_sessions (Threads_running) is greater than the skip_lock_active_limit, locks are not collected.

• lock_interval Int

  Default 5 (s)

  Set the lock collection cycle.

• custom_lock_interval String

  Set the lock collection cycle for the specified time zone.

  Note

  e.g. custom_lock_interval=60;0000-0230 # For the time zone from 00:00 to 02:30, set the lock collection cycle to 60 seconds.

  custom_lock_interval=0;0000-0230 # For the time zone from 00:00 to 02:30, locks are not collected.

Active session exclusion settings

The DBX agent collects a list of active sessions for MySQL, but it also provides the option to exclude specific sessions. Excluded sessions are not included when calculating the total_runtime, and its SQL does not appear in the SQL Statistics menu.

• limit_active_session Int

  Default 200

  Up to the specified number of active sessions are collected. If set to 0, collection is performed without the limit.

• skip_command String

  When collecting active sessions, the sessions for the command set as an option are not collected. For example, you can exclude the sessions in Daemon and Sleep status from collection by setting the following:

  whatap.conf

  skip_command=Daemon,Sleep

  Note

  For more information about the command that can be set as an option value, see the following link.

• skip_sys_session Int

  Default 1

  • 0: Includes the sys sessions (root, system user) in the active session collection and total_runtime.

  • 1: Includes the sys sessions in the active session collection, but excludes them from total_runtime.

  • 2: Excludes the sys sessions from active session collection and total_runtime.

• skip_user String

  User accounts set by options are excluded from the active sessions and total_runtime. For example, you can exclude the collections for root, system user, and event_scheduler accounts by setting as follows:

  whatap.conf

  skip_user=root,system user,event_scheduler

• skip_whatap_session Int

  Default 0

  If you set the option value to 1, WhaTap's collection queries are excluded from the active session collection and total_runtime.

Setting the slow query collection

To collect slow queries, first configure the database (DB). The WhaTap configuration method differs depending on the environment (on-premises or AWS RDS/Aurora).

Note

The slow query feature is supported only for MySQL and PostgreSQL.

Caution

Check the database settings

Before configuring WhaTap, set the slow query related parameters in the MySQL database (DB). Check that the slow query logging feature is enabled and proceed with the WhaTap configuration.

slow_query_log=on  
long_query_time=3  # 3 seconds 

On-premise environment

When running on your own server, use the WhaTap's DBX/XOS configuration method. In addition to the DBX agent installation, be sure to install XOS on the DB server. For the XOS agent configuration method, see the following.

1. Add the slow_query_log=on option to the DBX whatap.conf file.

   • slow_query_log Boolean
     It enables (on) or disables (off) the slow query logging feature. The default value in MySQL is on.

2. If XOS has been installed, the file name is automatically recognized. If the file name is not automatically recognized, set slow_query= in the XOS whatap.conf file.

AWS RDS/Aurora Environment

Because in the AWS RDS/Aurora environment, the XOS agent cannot be installed, slow queries can be collected through DBX agent settings or Cloud settings.

• DBX Agent Setting

  To collect slow queries in the AWS RDS/Aurora environment, set the DBX whatap.conf file as follows.

  whatap.conf

  slow_query_log=on  # Cloud Settings
  cloud_watch=on
  aws_region=
  aws_arn=
  cloud_watch_metrics=
  cloud_watch_instance= 

• Cloud Settings

  Follow the guide provided in the Management > Cloud Settings menu to automatically create monitoring resources in the AWS environment and collect slow query data. No additional configuration is required. For more details, see the following.

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