Agent Installation

The following guides you to the basic installation method for using the WhaTap database monitoring service.

To use the WhaTap monitoring service, after Sign in, create a project and install the agent to the target server. For more information about registration as a member, see the following.

See the following video guide.

Creating a project

Create a project before installing the agent.

1. Log in WhaTap monitoring service.

2. To create a project, on the left of the screen, select All Projects > + Project.

3. Select a product in Select product for installation.

4. Configure the settings for Project name, Data server region, and Time zone.

   

5. In Notification language setting, select the language for alert messages.

6. After all settings are finished, select Creating a project.

Note

• A Data server region refers to a region (a bundle of data centers installed to provide cloud services). Selecting a specific region stores your data in the datacenter that belongs to that region.

• Time zone is the reference time for generating alerts and reports.

• To group multiple projects for management, select a group from Project groups or add a group. For more information about grouping, see the following.

• To add a project with an organization selected, Groups of organization must be set.

Checking the configuration diagram

The DBX agent can be installed on a separate server or on the DB server. Select a method how to install the agent and check its configuration and firewall.

Install on a separate server	Install on the DB server

Account creation

Create an account with roles required for database monitoring. Log in with the root account and then create accounts.

Note

• If you have an account with roles, skip this step and then proceed to Next Step.

• In the example code, DB_User is the DB user account name. Change it to your account name.

• Enter your password in DB_Password in the example code.

MySQL

create user DB_User identified by 'DB_PASSWORD'; # Enter the desired password.
grant process on *.* to DB_User;
grant select on performance_schema.* to DB_User;
grant show databases on *.* to DB_User;

Assign additional roles depending on the features and operation environment.

• In case of collecting all table data

  grant select on *.* to DB_User;

• In case of monitoring tables only in a specific DB

  grant select on {DB_NAME}.* to DB_User;

• In case of using replication

  grant replication client on *.* to DB_User;
  grant replication slave on *.* to DB_User;

• In case of using the kill session

  grant super on *.* to DB_User;

• In case of using the kill session in the AWS RDS environment

  grant execute on procedure mysql.rds_kill to DB_User;

MariaDB

create user DB_User identified by 'DB_PASSWORD'; # Enter the desired password.
grant process on *.* to DB_User;
grant select on performance_schema.* to DB_User;
grant show databases on *.* to DB_User;

Assign additional roles depending on the features and operation environment.

• In case of collecting all table data

  grant select on *.* to DB_User;

• In case of monitoring tables only in a specific DB

  grant select on {DB_NAME}.* to DB_User;

• In case of using replication

  below MariaDB 10.5.1

  grant replication client, replication slave on *.* to DB_User;
  MariaDB 10.5.2 ~ 10.5.8

  grant replication master admin, replication slave admin, binlog monitor on *.* to DB_User;
  MariaDB 10.5.9 or later

  grant replication master admin, replica monitor, binlog monitor on *.* to DB_User;
  Note

  In case of AWS RDS MariaDB, replication information inquiry is supported in less than the version 10.5.

• In case of using the kill session

  grant super on *.* to DB_User;

• In case of using the kill session in the AWS RDS environment

  grant execute on procedure mysql.rds_kill to DB_User;

Support features for each role

The roles other than the Default role do not need to be assigned depending on the environment. However, some functions may not work.

Role	command	Menu and feature	Details
Default role	grant process on *.* to whatap;	Active session collection / Lock Tree / Dead Lock	This role to display thread information belonging to another account performs show engine.
	grant select on performance_schema.* to whatap;	Active session collection / Lock Tree / MYSQL SQL STATISTICS	When granting individual roles, see the following table
	grant show databases on *.* to whatap;	Instance List, etc.	It displays the database name.
Role details	grant select on *.* to whatap; or grant select on {DB_NAME}.{TABLE_NAME} to whatap;	DB size / Table Size Increase / Object detail / Searching a plan	MySQL does not support DB size, Object detail, and plan query features if it has no SELECT role for the table.
replication	grant replication client on *.* to whatap;	Displaying the Instance List's S / Collecting the replication information	SHOW MASTER STATUS, SHOW SLAVE STATUS
	grant replication slave on *.* to whatap;	Displaying the Instance List's M / Collecting the replication information	SHOW SLAVE HOSTS
Session Kill	grant super on *.* to whatap;	Session kill feature in the active session list	It terminates the thread belonging to another account.
	grant execute on procedure mysql.rds_kill to DB_User;	Session kill feature in case of AWS RDS	-

Instead of performance_schema.*, you can grant the following roles individually.

Role	command	Remarks
Active sessions / Lock tree	performance_schema.data_lock_waits	Starting from MySQL 8
	performance_schema.data_locks
	performance_schema.threads	-
	performance_schema.metadata_locks	Starting from MariaDB 10.5
Wait event information	performance_schema.events_waits_summary_global_by_event_name	-
SQL statistical information	performance_schema.events_statements_summary_by_digest	-
Wait metric name	performance_schema.setup_instruments	-

Checking the access key

The access key is the unique ID to enable the WhaTap service.

In the installation guide section, select Getting the access key. After the access key has been issued automatically, proceed to the next step.

Note

After a project has been created, the Agent installation page appears automatically. If the Agent installation does not appear, select Management > Agent installation on the left of the screen.

Downloading the DBX agent

Download the DBX agent file. Use the following two methods.

• You can download it by using the 'wget' command.

  BASH

  wget -O whatap.agent.database.tar.gz https://api.whatap.io/download/agent/whata.agent.database.tar.gz

• If you cannot download it with the command, select Download on the WhaTap monitoring service screen.

Download the DBX agent file and then unzip it.

BASH

tar -zxvf whatap.agent.database.tar.gz

DBX Agent Setting

Follow the instructions on the agent installation screen to configure the agent. By entering the required items on the screen, the configuration and commands can be auto-completed.

Tip

You can quickly and easily configure the agent by running the setup.sh file among the DBX agent configuration files. For more information, see the following.

whatap.conf configuration

Go to the unzipped folder and then check the whatap.conf file. In whatap.conf, enter the project access key, WhaTap server data, and DB connection data.

Default settings

whatap.conf

license={AccessKey}
whatap.server.host=13.124.11.223/13.209.172.35 # WhaTap server information
dbms=mysql
db=mysql
db_ip={DB_Server_IP}
db_port={DB_Server_Port} 

In case the SSL is used

whatap.conf

connect_option=?useSSL=true&verifyServerCertificate=false

In case the serverTimeZone setting is required upon accessing the JDBC driver

If you use the JDBC driver version 8.x or later, you may need to set serverTimezone for the connection URL. Set the following options in the whatap.conf file:

whatap.conf

connect_option=?serverTimezone=SERVER_TIMEZONE
# connect_option=?serverTimezone=UTC

Downloading JDBC

Download the JDBC driver that matches the operating system and version of the database server to the DBX agent path where you unzipped the file. /unzipped folder/jdbc

Info

Mysql & MariaDB 5.5 or later

• Connector/J 8.0.11
• Connector/J 5.1.46

Note

• Depending on the DB configuration, the additional settings may be required in the whatap.conf file. For more information, see the following.

• To further monitor the DB server's resources, use the XOS agent. For more information, see the following.

• In /unzipped folder/jdbc/README.md, you can also see the JDBC driver installation paths for each database.

DB user file creation

Generate an encrypted UID for database connection. Enter the username and password and then run the shell script (or batch file).

The uid.sh shell scrip file (or uid.bat batch file) can be found in the path where the WhaTap database agent has been installed. Set DB_USER to if there is only a password without user.

Linux

BASH

./uid.sh {DB_USER} {DB_PASSWORD}

Note

• After setting it once, it collects data from the database server to be monitored through the encrypted UID.

• To create a DB user file, enter the project access key in the whatap.conf file. Checking the access key

• In the Azure database environment, enter DB_USER in the form of DB_USER@DB_name.

• If special characters are included in DB_USER or DB_PASSWORD, enter the escape character (\) together before any special characters.

  Example

  ./uid.sh whatap whatap\!pwd
  
  # If there are multiple special characters, add the escape character(\) for each.
  ./uid.sh whatap whatap\!\@pwd

Windows

CMD

uid.bat "DB_USER" "DB_PASSWORD"

Note

• After setting it once, it collects data from the database server to be monitored through the encrypted UID.

• To create a DB user file, enter the project access key in the whatap.conf file. Checking the access key

• In the Azure database environment, enter DB_USER in the form of DB_USER@DB_name.

• If special characters are included in DB_USER or DB_PASSWORD, enter the escape character (\) together before any special characters.

  Example

  uid.bat whatap whatap\!pwd
  
  # If there are multiple special characters, add the escape character(\) for each.
  uid.bat whatap whatap\!\@pwd

Starting the monitoring

Execute a shell script (or batch file) from the path where you have installed the agent.

Linux

./start.sh

To use it like a daemon, execute the following command. However, it works only in the environment where nohup has been installed.

./startd.sh

Windows

start.bat

You can set the service to automatically start the agent when the Windows system starts. See the following commands.

# In case of registering the service
install_WindowsService.bat create WhatapDBXAgent

# In case of deleting the service
install_WindowsService.bat delete WhatapDBXAgent

Note

In Control Panel > Windows Tools > Services (services.msc), you can start or stop the WhatapDBXAgent service. Depending on the Windows version, the service path may differ.

You completed installing the agent for database monitoring. In the following, check the post-installation checklist.

Installing the additional agent (XOS) and applying other options

To additionally monitor the resources of the database server, run a separate XOS agent process on the database server to collect data.

Note

• It can be applied to only the OS environment running on the x86 architecture.

• The additional agent installation process is optional.

• For more information about the XOS agent configuration options, see the following.

XOS

1. Set the following options in the whatap.conf file in the path where the DBX agent has been installed.

   whatap.conf

   xos=1
   xos_port=3002

2. Move the xos folder (/unzip folder/xos/) to the database server.

3. Set the following options in the xos.conf file in the xos path moved to the database server.

   xos.conf

   dbx_ip={DB_Agent_IP}
   dbx_port=3002 # default 3002
   cpu_limit=0
   mem_limit=10240
   Tip

   In Agent Installation, when you enter the DB data to DB Agent IP and DB Agent Port, the agent options are automatically generated.

4. Grant the role to run the XOS agent.

   chmod +x ./whatap.agent.xos*

5. Run the XOS agent.

   ./start.sh

Note

• To transmit monitored data to the DBX agent, the port set to dbx_port (default 3002) must have been open. (UDP Outbound)

• To run the XOS agent in the background, run the ./startd.sh file.

RDS : AWS CloudWatch

Set the following options in the whatap.conf file on the agent server. Due to the nature of CloudWatch, it is recommended to call every 60 seconds (cloud_watch_interval).

whatap.conf

aws_region={AWS_RDS_Region_Name}
aws_arn=arn:aws:iam::999999999999:role/UpdateApp
cloud_watch=on
cloud_watch_instance=RDS_DB_Instance_Name
cloud_watch_interval=60
cloud_watch_metrics=CPUUtilization,FreeableMemory,FreeStorageSpace,NetworkTransmitThroughput,NetworkReceiveThroughput

Execute the following command to view the AWS CloudWatch metrics. Change the DB_Instance_Name and then execute the following command.

aws cloudwatch list-metrics --namespace AWS/RDS --dimensions Name=DBInstanceIdentifier,Value={DB_Instance_Name}

Note

• In Agent Installation, enter values for AWS RDS Region, RDS DB Instance Name, and DB Instance Name. Then the agent options and commands are automatically generated.

• For more information about the aws_arn option for AWS authentication, see the following.

• For more information about the AWS CLI installation and update, see the following link.

• For more information about the AWS CLI configuration, see the following link.

Next steps

• Checking the installation

  If you have created a project, installed an agent, and applied all agent options, see the checklist in the following.

• Installation troubleshooting

  It provides various problems that may occur when installing the agent and specific instructions for resolving them. For more information, see the following.

• Agent setting

  It provides various features for monitoring by applying some options to the agent configuration file (whatap.conf). For more information, see the following.

  To additionally monitor the database server resources, set more options in the additional agent (XOS). For more information, see the following.

• Starting the monitoring

  After configuring all settings, the agent starts collecting metrics data from the database server. First, check whether the monitoring data has been collected in Instance List. For more information about Instance List, see the following.