Skip to main content

DMX Agent Setting

Enter the settings required for the DMX 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.

  • ipckey String

    It can be obtained through the ipcs -m command. This is the key value (hexadecimal) of the Oracle to be monitored.

    Note

    The ipcs command provides information about inter-process communication (IPC). The -m option queries shared memory resources.

  • rac_name String RAC

    This option sets the group name of the instances grouped in Oracle's Real Application Clusters (RAC). This option allows you to change complex RAC cluster group names to concise and easy ones to identify. The RAC cluster group name set using this option can be checked on the WhaTap Monitoring Service screen.

    For example, if the RAC cluster group name is too long, such as 'my_long_rac_cluster_group_name', you can set a concise name as follows:

    whatap.conf
    rac_name=my_rac_cluster_group

    It is displayed as 'my_rac_cluster_group' in the WhaTap Monitoring Service, allowing users to quickly identify and monitor the RAC cluster group.

Database data collection options​

  • bind_elapse Int

    Default 3

    It sets to collect bind values ​​if SQL runs longer than the specified time (seconds). If the setting is 0, this option does not work.

    Even if the bind_interval is not set, the bind values are collected when the SQL execution time is greater than the set value.

  • bind_interval Int

    Default 0

    It sets the bind capture interval in seconds. Setting the default value (0) disables the bind capture.

    Collection is made at the interval set in v$sql_bind_capture.

    Because there can be a lot of data, collection is performed by bind_max_count since the last collection time.

  • bind_max_count Int

    Default 1000

    It sets how many bind capture values ​​to collect. Only the bind capture values after the last collection time can be collected.

  • codefrom / codeto String

    This option changes the character encoding when there is a problem with Korean characters broken in the SQL text. The value can be selected from the list in iconv -l.

    e.g. codefrom=EUC-KR, codeto=UTF-8

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

  • event String

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

    It enables collecting event-related metrics. Write the name of the metric to collect by referencing the EVENT column such as v$system_event, and v$event_name. You can collect additional metrics along with the basic metrics by writing them in a way like event+=. You can enter multiple items using the comma (,) as the delimiter without spaces.

    For each event, the following three values are collected.

      - time waited: Total waiting time in the event (unit: 1/100 sec). e.g. db file sequential read time waited

      - timeouts: Number of waits that exceeded the timeout. e.g. db file sequential read total timeouts

      - total waits: Total number of events. e.g. db file sequential read total waits

  • interval Int

    Default 3

    It sets the data collection cycle in seconds.

    Note

    Oracle Pro collects active sessions and SQL data at an interval of 1/20 second through memory access. Because the stats are generated based on the data collected in this manner, data loss is minimized. When transmitting the current DB status according to the interval option, the stat, event, SQL stat, xview, lock, and PQ are read directly from memory for quick processing. On the other hand, the binds, DB parameters, plans, tables, table spaces, and wait classes are collected through queries.

  • multi_db_stat Boolean

    Default true

    When using the Multi DB, set whether to collect metrics by database or by summing them for all instances.

  • ora_hidden_param Boolean

    Default false

    It sets whether to collect hidden parameter values. Set the option value to true to collect hidden parameters.

  • plan_change Int

    Default 1

    It sets whether to collect the change history for the plan.

    • 1: Excludes sys
    • 2: Includes sys

  • plan_elapse Int

    Default 3

    It collects the plans that take more than 5 seconds to run.

  • segments Boolean

    Default true

    It collects the segment size information. You can check the size by selecting the database or tablespace in the Statistics/Report > Tablespace size menu.

  • segments_exclude_sys Int

    Default 1

    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. Segments less than the set value are not collected.

  • segments_sys String

    Default:

    Details
      <summary>Viewing 18 accounts</summary>

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

    It is the list of accounts corresponding to sys. To add to the above accounts, you can add with segments_sys+='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:

    Details
      <summary>Viewing 20 metrics</summary>

      `CPU used by this session`, `data blocks consistent reads - undo records applied`, `db block changes`,  
      `db time`, `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`

    It enables collecting statistics-related metrics. Write the name of the metric to collect by referencing the NAME column such as v$sysstat, and v$statname. You can collect additional metrics along with the basic metrics by writing them in a way like stat+=. You can enter multiple items using the comma (,) as the delimiter without spaces.

  • tablespace Int

    Default 1

    Selects the view used to query tablespace free space. If a query timeout occurs when querying dba_free_space, you can switch to another view depending on your environment.

    • 1: Query dba_free_space
    • 2: Query dba_lmt_free_space
    • 3: Query usage_metrics

    Supported version: dmx 1.0.1x or later

  • tablespace_interval Int

    Default 60

    Sets the collection interval for tablespace information in minutes. The minimum value is 5; if you set a value smaller than 5, it is automatically corrected to 5 minutes and a log noting the correction is recorded. You can also set a value greater than 60.

    Supported version: dmx 1.0.8c or later

  • tablespace_send_opt Int

    Default 0

    Sets the transmission method for tablespace information. This can mitigate errors caused by duplicate transmission of the same data in environments with many tablespaces.

    • 0: Split transmission
    • 1: Batch transmission

    Supported version: dmx 1.0.8c or later

  • topevent Int

    Default 50

    It collects changes in key event-related metrics according to the values set in descending order. The data having the stat_top and event_top categories are used.

    Note

    If no value is set for this option, it operates according to the setting for topstat.

  • topstat Int

    Default 50

    It collects changes in key statistics-related metrics according to the values set in descending order. The data having the stat_top and event_top categories are used.

  • trace_tkprof_path String

    Specifies the path to the tkprof executable used when running SQL trace.

    Supported version: dmx 1.0.4y or later

  • waitclass_opt Int

    Default 1

    Sets the collection method for Wait Class metrics.

    • 1: Memory-based collection. Collected at the same interval as other metrics.
    • Values other than 1: Maintains the existing method (query-based, fixed 1-minute interval).

    Supported version: dmx 1.0.8c or later

  • xos Boolean

    Default true

    This option enables the XOS agent (xos.conf) to additionally monitor the resources of the database server.

  • xview_min Int

    Default 100 (1 second)

    The unit is centisecond (1/100 of a second). This option processes only the jobs whose elapsed time is greater than the set value.

    • -1: This option is disabled.
    • 0: It collects all jobs.

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.

Multi-row results are stored up to a maximum of 100 rows, and a result value is recognized as numeric when it is an int or float. In addition to SELECT, you can also use INSERT, UPDATE, and DELETE statements.

INSERT/UPDATE/DELETE support: dmx 1.0.8s or later · Multi-row storage (up to 100 rows): dmx 1.0.5g or later

  • sqlmon Int

    Default value: 1

    • 1: Run both dbx and sqlmon simultaneously
    • 2: Run only sqlmon

Supported version: dmx 1.0.4y 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​

WhaTap DMX agent encrypts the collected data and transmits the encrypted data to the server. 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 DMX agent was 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), it is automatically created by combining the hostname in the following way: DMX-{hostname}.

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