Skip to main content

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

    oracle

    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.

Collecting data​

  • conn_fail_count Int

    Default 15

    It sends a notification when 15 consecutive connection errors occur. You can adjust the notification occurrence criteria by entering the desired number.

  • db_param_enabled Boolean

    Default true

    It sets whether or not to collect the DB parameters.

  • event String

    Default:

    Viewing all 8 events

    db file scattered read, db file sequential read, direct path read, direct path write,
    enq: TX - row lock contention, latch free, library cache lock, library cache pin

    In the RAC environment, two additional metrics are collected by default: gc cr block receive time and gc current block receive time.

    The values for the above metrics are collected from v$system_event. You can check it in the db_oracle_counter category, which collects the following three values ​​for a single event.

    • time waited: Total time (1/100 seconds) waited for the event e.g. db file sequential read time waited
    • timeouts: Number of waits that ended in timeout e.g. db file sequential read total timeouts
    • total waits: Total number of the events occurred e.g. db file sequential read total waits

    cf.) In Oracle Pro, you can set additional metrics other than the defaults by writing in the manner of event+=. However, this product does not support it.

  • interval_sec Boolean DBX agent v1.7.3 or later

    Default true

    This option is used to convert the data collected from the agent every 5 seconds in seconds (delta value for 1 second) and report it.

  • ora_bind_saving Boolean

    Default true

    If the SQL execution time is more than 5 seconds, the bind value of the SQL is collected by v$sql_bind_capture. (excluding the sys account)

    cf.) In Oracle Pro, the options are divided into bind_interval, bind_max_count, and bind_elapse.

  • ora_plan_saving Boolean

    Default true

    If the SQL plan has changed or the SQL execution time is more than 5 seconds, the plan information is collected from v$sql_plan. (excluding the sys account)

    cf.) In Oracle Pro, the options are divided into plan_change and plan_elapse.

  • ora_ratio Boolean DBX agent v1.6.11 or later

    Default false

    You can additionally collect various ratio metrics. The metrics to collect are as follows:

    • buffer cache hit ratio
    • soft parse ratio
    • hard parse ratio
    • library cache hit ratio
    • library cache pin hit ratio
    • library cache get hit ratio
    • latch hit ratio
    • shared pool free mem ratio

  • segments Boolean

    Default true

    It collects the segment size information. In Stat/Report > Tablespace Size, you can see the size by selecting the database or tablespace.

  • segments_exclude_sys Boolean

    Default true

    The sizes are collected except for accounts corresponding to sys.

  • segments_hour Int

    Default 5

    It sets the time to collect segment sizes. The default value is 5 and collection starts at 5 AM.

  • segments_max_count Int

    Default 50

    Only 50 large segments are collected and stored for each tablespace.

  • segments_min_size Int

    Default 10

    The minimum unit for collecting segment sizes is 10 MB by default. When collecting the segment sizes, the segment sizes less than the set value are not collected.

  • segments_sys String

    Default:

    Viewing all 18 accounts

    SYS, OUTLN, SYSTEM, AUDSYS, DBSNMP, GSMADMIN_INTERNAL,
    XDB, WMSYS, OJVMSYS, CTXSYS, ORDSYS, ORDDATA,
    MDSYS, LBACSYS, DVSYS, DBSFWUSER, APPQOSSYS, OLAPSYS

    It is the list of accounts corresponding to sys. To add to the above account, write additionally including the above content with segments_sys='xxx','xxx','xxx'.

  • sqlstat_send_interval Int

    Default: 1 minutes

    Sets the interval, in minutes, for generating and sending SQL statistics data. You can specify any integer value of 1 or higher. For more precise statistical analysis, set it to 1. This setting enables detailed 1-minute analysis in the Top SQL screen.

  • stat String

    Default:

    Viewing all 22 metrics

    consistent gets, cpu used by this session, db block changes, db block gets, db time,
    data blocks consistent reads - undo records applied, enqueue waits, execute count,
    logons current, opened cursors current, parse count (hard), parse count (total),
    physical reads, physical writes, redo entries, rollback changes - undo records applied,
    session logical reads, sorts (disk), sorts (memory), transaction tables consistent reads - undo records applied, user commits, user rollbacks

    The values for the above metrics are collected from v$sysstat. You can check it in the db_oracle_counter category.

    cf.) In Oracle Pro, you can set additional metrics other than the defaults by writing in the manner of stat+=. However, this product does not support it.

  • xview_min_sec Int

    Default 0

    When collecting xview, it is collected only when the query execution time takes longer than the specified time. By default, it collects all queries whose execution time takes more 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​

  1. 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
  1. 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
ItemDescriptionExample
IntervalExecution interval in minutes, minimum 11 → runs every 1 minute
Run timeHHMM-HHMM format, multiple ranges separated by comma (,). Set 0 to run at all times0900-1100 → runs only 09:00–11:00
Tag nameTag name stored in metrics. If omitted, the file name is used as the tag namewhatap
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.

  1. Enable SQLMON in whatap.conf.

  2. Restart the agent.

  3. In the Icon 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:

ConfigurationDescription
{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
Last updated on