Skip to main content

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.

Creating a project​

Create a project before installing the agent.

  1. Log in to the WhaTap Monitoring Service.

  2. In the left side menu, click All Projects > + Project.

  3. On the Select product screen, select the product you want to install.

  4. Enter or select the following items:

    • Project name: Enter the project name.

    • Data server region: Select the data server region. A region is a group of data centers that provide cloud services. Your data will be stored in the selected region.

    • Time zone: Set the time zone to be used for alerts and report generation.

    • Notification language setting: Set the language for alert notifications. (Supports Korean and English)

    • Project groups: Group multiple projects for easier management. Select a group if applicable.

    • Project description: Add additional details or a description for your project.

  5. After completing all settings, click the Creating a project button.

Note

If you add a project while an organization is selected, you must set the Groups of organization field.

For more information about groups, see the related document.

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

  • In general cases

    SQL
    create user {DB_User} identified by {DB_Password};
    grant create session to {DB_User};
    grant select any dictionary to {DB_User};

  • In case the basic monitoring is used in the multi-tenant DB (Oracle 12c or later): The c## account is created.

    SQL
    create user c##{DB_User} identified by "{DB_Password}";
    grant create session to c##{DB_User};
    grant select any dictionary to c##{DB_User};
    alter user c##{DB_User} set container_data = ALL container = CURRENT;

  • in case of using the kill session

    SQL
    grant alter system to {DB_User}

  • In case the kill session feature is used in the multi-tenant DB: It is run with the c## account.

    SQL
    grant alter system to c##whatap container=all;

  • In case of viewing the hidden parameters

    SQL
    create view sys.whatap_vw_ksppi as select * from sys.x$ksppi;
    grant select on sys.whatap_vw_ksppi to {DB_User};  
    create synonym {DB_User}.whatap_vw_ksppi for sys.whatap_vw_ksppi;

    create view sys.whatap_vw_ksppcv as select * from sys.x$ksppcv;
    grant select on sys.whatap_vw_ksppcv to {DB_User};
    create synonym {DB_User}.whatap_vw_ksppcv for sys.whatap_vw_ksppcv;

  • In case of using the connection analysis feature

    SQL
    grant select on sys.v_$session to {Appication_service_account};
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.

Rolecommand (Single DB)command (Multitenant DB)Menu and featureDetails
Default rolegrant create session to whatap;grant create session to c##whatap;Access-
grant select any dictionary to whatap;grant select any dictionary to c##whatap;Monitoring a Database Instance / Monitoring Multiple Instances / SQL StatisticsWhen granting individual roles, see the following table
-alter user c##whatap set container_data = ALL container = CURRENT;When using a multi-tenant DB (12C or higher), this is a required role to query the pdb.
Session killgrant alter system to whatap;grant alter system to c##whatap container=all;Active sessions > Session kill-
Hidden parameter querycreate view sys.whatap_vw_ksppi as select * from sys.x$ksppi;
grant select on sys.whatap_vw_ksppi to DB_User;
create synonym DB_User.whatap_vw_ksppi for sys.whatap_vw_ksppi;		Hidden parameters are included in the parameter query menu.To query hidden parameters, separate view/synonym creation and role assignment are required.
create view sys.whatap_vw_ksppcv as select * from sys.x$ksppcv;
grant select on sys.whatap_vw_ksppcv to DB_User;
create synonym DB_User.whatap_vw_ksppcv for sys.whatap_vw_ksppcv;

Instead of select any dictionary, you can grant the following roles individually.

Rolecommand (Single DB)command (Multitenant DB)
Active sessions / Lock tree / Metrics informationgrant select on v_$sqlarea to whatap;grant select on v_$sqlarea to c##whatap;
grant select on v_$transaction to whatap;grant select on v_$transaction to c##whatap;
grant select on v_$instance to whatap;grant select on v_$instance to c##whatap;
grant select on v_$sysstat to whatap;grant select on v_$sysstat to c##whatap;
grant select on v_$lock to whatap;grant select on v_$lock to c##whatap;
grant select on v_$sesstat to whatap;grant select on v_$sesstat to c##whatap;
grant select on v_$event_name to whatap;grant select on v_$event_name to c##whatap;
grant select on v_$session to whatap;grant select on v_$session to c##whatap;
grant select on v_$sql to whatap;grant select on v_$sql to c##whatap;
grant select on v_$process to whatap;grant select on v_$process to c##whatap;
grant select on v_$statname to whatap;grant select on v_$statname to c##whatap;
grant select on v_$system_event to whatap;grant select on v_$system_event to c##whatap;
grant select on v_$osstat to whatap;grant select on v_$osstat to c##whatap;
grant select on v_$px_session to whatap;grant select on v_$px_session to c##whatap;
grant select on v_$sga to whatap;grant select on v_$sga to c##whatap;
-grant select on v_$con_sysstat to c##whatap;
Parameter informationgrant select on v_$parameter to whatap;grant select on v_$parameter to c##whatap;
Wait information / Event informationgrant select on v_$event_name to whatap;grant select on v_$event_name to c##whatap;
grant select on v_$system_event to whatapgrant select on v_$con_system_event to c##whatap;
grant select on v_$system_wait_class to whatap;grant select on v_$system_wait_class to c##whatap;
-grant select on v_$con_system_wait_class to c##whatap;
Tablespace informationgrant select on dba_data_files to whatap;grant select on cdb_data_files to c##whatap;
grant select on dba_free_space to whatap;grant select on cdb_free_space to c##whatap;
grant select on dba_temp_files to whatap;grant select on v_$sort_segment to c##whatap;
grant select on v_$temp_extent_pool to whatap;grant select on v_$tempfile to c##whatap;
grant select on v_$containers to whatap; (12c 이상)grant select on v_$containers to c##whatap;
Note

  • To use the previous accounts, go to Create DB User File. If you do not have any permission, you may not be able to proceed with normal monitoring.

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

  • Enter your password in DB_Password in the example code.

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://service.whatap.io/download/dbx_agent?type=oracle&format=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
Note

For users who cannot download tar files due to security settings, ZIP files are also provided. On the installation screen, select the .zip Download button.

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.

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.

whatap.conf
license={AccessKey}
whatap.server.host=13.124.11.223/13.209.172.35 # WhaTap server information

dbms=oracle
db={DB_Name(SID)}
db_ip={DB_Server_IP}
db_port={DB_Server_Port} 

exclude_background=3

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

Oracle 10g R2 or later: https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html

Note

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

Creating DB users and changing passwords​

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

Tip

When changing the password, enter the new password and follow the same procedure.

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

Viewing the default plan​

When creating the default plan user file, you can configure the agent to automatically view the plan by using the predefined DB information.

  1. Add the plan_db option to the agent configuration (whatap.conf) file and then enter the DB name.

    whatap.conf
    plan_db=(dbname)

  2. After configuring the DB, use the planuid.sh script to set the user and password.

    ./planuid.sh user pwd
    Note

    If the user (user) and password (pwd) include special characters, add backslashes (\) before each special character.

    e.g. user$example → user\$example

Starting the monitoring​

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

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

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.
  • To additionally collect and monitor monitoring metrics provided by cloud services on the dashboard of the database project, see the following.

Configuring the whatap.conf file​

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

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

Configuring the xos.conf file​

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.

Running the XOS agent​

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.

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.

  • Cloud Settings

    To additionally collect and monitor monitoring metrics provided by cloud services on the dashboard of the database project, 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.

Last updated on