1.23.1 Configuring OracleDB exporter

■ Placing metric definition files

Perform the following steps when upgrading from a version earlier than JP1/IM - Manager 13-01 in logical host operation.

1. Copy metric definition file of the following OracleDB exporter and rename it to the definition file name of the copy destination.

   • For Windows

     Source filename: JP1/IM-Manager-installation-folder\jp1imm\conf\imdd\plugin\jp1pccs\metrics_oracledb_exporter.conf.model

     Destination filename: JP1/IM-Manager-installation-folder\jp1imm\conf\imdd\plugin\jp1pccs\metrics_oracledb_exporter.conf

   • For Linux

     Source filename: JP1/IM-Manager-installation-directory/jp1imm/conf/imdd/plugin/jp1pccs/metrics_oracledb_exporter.conf.model

     Destination filename: JP1/IM-Manager-installation-directory/jp1imm/conf/imdd/plugin/jp1pccs/metrics_oracledb_exporter.conf

   For Linux, set the permissions to 600.

   For logical host operation, place this file in the following location:

   • For Windows

     shared-folder\jp1imm\conf\imdd\plugin\jp1pccs\

   • For Linux

     shared-directory/jp1imm/conf/imdd/plugin/jp1pccs/

■ Updating IM manager updatable definition file list definition file

Perform the following steps when upgrading from a version earlier than JP1/IM - Manager 13-01 in logical host operation.

1. Copy the following IM manager updatable definition file list definition file and rename it to the destination definition file.

   • For Windows

     Source filename: JP1/IM-Manager-installation-folder\jp1imm\conf\imdd\system\fileoperation\imdd_product_deffile_list.json.update

     Destination filename: JP1/IM-Manager-installation-folder\jp1imm\conf\imdd\system\fileoperation\imdd_product_deffile_list.json

   • For Linux

     Source filename: JP1/IM-Manager-installation-directory/jp1imm/conf/imdd/system/fileoperation/imdd_product_deffile_list.json.update

     Destination filename: JP1/IM-Manager-installation-directory/jp1imm/conf/imdd/system/fileoperation/imdd_product_deffile_list.json

   For logical host operation, place this file in the following location:

   • For Windows

     shared-folder\jp1imm\conf\imdd\system\fileoperation\

   • For Linux

     shared-directory/jp1imm/conf/imdd/system/fileoperation/

■ Stopping JP1/IM - Agent

Stop JP1/IM - Agent service.

For physical hosts

Stop JP1/IM - Agent servicing by running the following command.

jpc_service_stop -s all

For logical hosts

Stop from the cluster software.

■ Setting up OracleDB exporter scrape jobs

The model file of the Prometheus configuration file is updated when the version is upgraded. Write the following details of Prometheus configuration file model file (jpc_prometheus_server.yml.model) under scrape_configs of Prometheus configuration file (jpc_prometheus_server.yml).

For logical host operation, update the following files:

• For Windows

  shared-folder\jp1ima\conf\jpc_prometheus_server.yml

• For Linux

  shared-directory/jp1ima/conf/jpc_prometheus_server.yml

(Omitted)
   :
scrape_configs:
   :
  - job_name: 'jpc_oracledb'
    scrape_interval: 60s
    scrape_timeout: 30s
    metrics_path: /metrics
    file_sd_configs:
      - files:
        - 'jpc_file_sd_config_oracledb.yml'
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance
        regex: ([^:]+):([^:]+):(.*)
        replacement: ${1}:${2}
      - source_labels: [__address__]
        target_label: jp1_pc_nodelabel
        regex: ([^:]+):([^:]+):(.*)
        replacement: ${2}
      - source_labels: [__address__]
        target_label: __address__
        regex: ([^:]+):([^:]+):(.*)
        replacement: @@hostname@@#:${3}
    metric_relabel_configs:
      - source_labels: ['__name__']
        regex: 'oracledb_sessions_value|oracledb_resource_current_utilization|oracledb_resource_limit_value|oracledb_asm_diskgroup_total|oracledb_asm_diskgroup_free|oracledb_activity_execute_count|oracledb_activity_parse_count_total|oracledb_activity_user_commits|oracledb_activity_user_rollbacks|oracledb_activity_physical_reads_cache|oracledb_activity_consistent_gets_from_cache|oracledb_activity_db_block_gets_from_cache|oracledb_process_count|oracledb_wait_time_administrative|oracledb_wait_time_application|oracledb_wait_time_commit|oracledb_wait_time_concurrency|oracledb_wait_time_configuration|oracledb_wait_time_network|oracledb_wait_time_other|oracledb_wait_time_scheduler|oracledb_wait_time_system_io|oracledb_wait_time_user_io|oracledb_tablespace_bytes|oracledb_tablespace_max_bytes|oracledb_tablespace_free|oracledb_tablespace_used_percent|oracledb_exporter_last_scrape_duration_seconds|oracledb_exporter_last_scrape_error|oracledb_exporter_scrapes_total|oracledb_up'
        action: 'keep'

#

Specify the host name of JP1/IM - Agent (or logical host name for logical host operation).

■ Deploying OracleDB exporter discovery configuration file

1. Copy the model file of the definition file that defines the monitoring target of the following OracleDB exporter, and rename it to the definition file name of the copy destination.

   • For Windows

     Source filename: JP1/IM - Agent installation folder\jp1ima\conf\jpc_file_sd_config_oracledb.yml.model

     Destination filename: JP1/IM - Agent installation folder\jp1ima\conf\jpc_file_sd_config_oracledb.yml

   • For Linux

     Source filename: JP1/IM - Agent installation directory/jp1ima/conf/jpc_file_sd_config_oracledb.yml.model

     Destination filename: JP1/IM - Agent installation directory/jp1ima/conf/jpc_file_sd_config_oracledb.yml

   For Linux, set the permissions to 600.

   For logical host operation, place this file in the following location.

   • For Windows

     shared-folder\jp1ima\conf\

   • For Linux

     shared-directory/jp1ima/conf/

2. Open the jpc_file_sd_config_oracledb.yml file created in step 1 in a text editor, edit it as follows, and overwrite it.

   - targets:
   #  - <OracleDB hostname>:<an arbitrary name>:<oracledb_exporter port>
     labels:
       jp1_pc_exporter: JPC OracleDB exporter
       jp1_pc_category: database
       jp1_pc_trendname: oracledb_exporter
       jp1_pc_remote_monitor_instance: @@hostname@@#:OracleDB collector(OracleDB exporter)

   #

   Specify the host name of JP1/IM - Agent (or logical host name for logical host operation).

■ Updating integrated agent updatable definition file list definition file

The following describes the steps for updating integrated agent updatable definition file list definition file.

1. Copy the following integrated agent updatable definition file list definition file and rename it to the destination definition filename.

   • For Windows

     Source filename: JP1/IM - Agent installation folder\jp1ima\conf\jpc_product_deffile_list.json.update

     Destination filename: JP1/IM - Agent installation folder\jp1ima\conf\jpc_product_deffile_list.json

   • For Linux

     Source filename: JP1/IM - Agent installation directory/jp1ima/conf/jpc_product_deffile_list.json.update

     Destination filename: JP1/IM - Agent installation directory/jp1ima/conf/jpc_product_deffile_list.json

   For logical host operation, place this file in the following location:

   • For Windows

     shared-folder\jp1ima\conf\

   • For Linux

     shared-directory/jp1ima/conf/

■ Checking the settings

Prometheus server definition file is checked because the format can be checked by promtool command.

promtool command is stored in under /jp1ima/tools where JP1/IM-Agent is installed.

promtool check config jpc_prometheus_server.yml

If an error is displayed, review the error.

Note that there is no problem even if the following warning is displayed.

WARNING: file "../conf/jpc_file_sd_config_windows.yml" for file_sd in scrape job "jpc_windows" does not exist

■ Starting JP1/IM - Agent

Start JP1/IM - Agent servicing.

• For physical hosts

  Run the following command to start JP1/IM - Agent services.

  jpc_service_start -s all

• For logical hosts

  Start from the cluster software.

■ Preparing to add a monitoring target

1. Determine instance name of OracleDB exporter.

   OracleDB exporter must be started for each target. If you have more than one target, you need to create more than one OracleDB exporter service. The identifier used to distinguish OracleDB exporter services is called "instance name".

   • Instance name can contain only alphanumeric characters.

   • The length of instance name is 32 bytes or less.

2. Determine the listen port for OracleDB exporter.

   Determine the port number on which OracleDB exporter service listens. Use a port number that is not used by other services or other OracleDB exporter services.

3. Check the value to be set in the environment variable JP1IMADIR.

   You must set JP1IMADIR environment variable to service definition file, or unit definition file of OracleDB exporter. Depending on the type of host in the JP1/IM - Manager, the following values will occur.

   • For Windows

     Host type	Environment-variable JP1IMADIR
     For physical host operation	JP1/IM-Agent-installation-folder\jp1ima
     For logical host operation	shared-folder\jp1ima

   • For Linux

     Host type	Environment-variable JP1IMADIR
     For physical host operation	/opt/jp1ima
     For logical host operation	shared-directory/jp1ima

4. Check the value to be set in the environment variable DATA_SOURCE_NAME.

   In the environment variable DATA_SOURCE_NAME set in the service definition file of OracleDB exporter, the connection user and connection destination information must be set.

   The environment variable DATA_SOURCE_NAME is specified in the following format.

   • For Windows

     Oracle://user-name@host-name:port/service-name?connection timeout=10[&instance name=instance-name]

   • For Linux

     Oracle://user-name@host-name:port/service-name?connection timeout=10[&instance name=instance-name]

   • user-name

     Specifies the username of the user used to connect to Oracle Database.

     Allowed characters are uppercase letters, numbers, underscores, dollar signs, pound signs, periods, and at signs. Specify within 30 characters.

   • host-name

     Specifies the hostname of OracleDB hostname to monitor.

     Characters that can be specified are uppercase letters, lowercase letters, numbers, -(hyphen), _ (underscore), .( period). Specify within 253 characters.

   • port

     Specify the port number for connecting to Oracle listener.

   • service-name

     Specifies the service name of Oracle listener.

     Characters that can be specified are uppercase letters, lowercase letters, numbers, _(underscore), -(hyphen), .(period). Specify within 64 characters.

   • Option

     Specify the connection options. If you have more than one option, use "&" in Windows and "&" in Linux.

   • connection timeout=seconds

     Specifies the connection timeout in seconds. This option must be specified.

     Be sure to specify 10.

     If you specify a value other than 10 and do not specify this option, scrape of Prometheus server times out and up metric may be 0 even if OracleDB exporter is running.

   • instance name=instance-name

     Specifies instance name to connect to. Specifying this option is optional.

   The hostname, port, service name can be checked with lsnrctl service commandof Oracle Database. In the example below, the host name is "ORAHOST", the port is "1521", the service name is "orcl.local", and instance name is "orcl".

   $ lsnrctl service
    
   LSNRCTL for 64-bit Windows: Version 19.0.0.0.0 - Production on 13-Dec-2023 09:09:34
    
   Copyright (c) 1991, 2019, Oracle.  All rights reserved.
    
   Connected to (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=ORAHOST)(PORT=1521)))
   Service Summary...
     :
     :
   The service "orcl.local" has one instance.
     Instance "orcl", Status READY has one handler for this service...
       Handler:
         "DEDICATED" Established:10674 Rejected:1 Status:ready
            LOCAL SERVER
     :
     :

   In this case, the environment variable DATA_SOURCE_NAME is as follows.

   • For Windows

   Oracle://user-name@ORAHOST:1521/orcl.local?connection timeout=10&instance name=orcl

   • For Linux

   Oracle://user-name@ORAHOST:1521/orcl.local?connection timeout=10&instance name=orcl

5. Determine the name of the monitoring target to be displayed in the tree of the Intelligent Integrated Management Base.

   OracleDB exporter monitoring targets are displayed in Intelligent Integrated Management Base tree as follows.

   Since any name can be specified for the monitoring target name, please decide an appropriate monitoring target name.

   All Systems
        + Oracle-Database-host-name
           + Database
               + Monitoring-target-name-1
               + Monitoring-target-name-2

   For the length of characters and strings that can be used, see "OracleDB exporter discovery configuration file (jpc_file_sd_config_oracledb.yml)" in Chapter 2. Definition Files in the JP1/Integrated Management 3 - Manager Command, Definition File and API Reference.

6. Confirm whether to operate on a physical host or a logical host.

   OracleDB exporter is also a physical host operation if scrape of the newly added JP1/IM - Agent is a physical host operation.

   OracleDB exporter is also logical host operation if scrape of the newly added JP1/IM - Agent is logical host operation.

7. Make sure you can get the metrics you want to monitor.

   We recommend that you run SQL statement for acquiring data directly with the person you use to connect to ensure that the required metric can be retrieved.

   If you cannot get the metrics you want to monitor, contact Oracle Database support so that they can be retrieved.

■ Setting up OracleDB exporter

1. Copy the Windows serviced program and rename it to the destination program name.

   Source filename: OracleDB-exporter-location\oracledb_exporter_windows\jp1ima\bin\oracledb_exporter_@@instance@@_service.exe

   Destination file name:

   • For physical host operation

     OracleDB-exporter-location\oracledb_exporter_windows\jp1ima\bin\oracledb_exporter_intance-name^#_service.exe

   • For logical host operation

     OracleDB-exporter-location\oracledb_exporter_windows\jp1ima\bin\oracledb_exporter_intance-name^#_logical-host-name_service.exe

   #

   For instance name, specify the name determined in - Preparation for adding a monitoring target in 1.23.1(4)(a) Adding a monitoring target (Required).

2. Create a service definition file.

   Copy the source service definition file and rename it to the destination program.

   Source filename: OracleDB-exporter-location\oracledb_exporter_windows\jp1ima\bin\oracledb_exporter_@@instance@@_service.xml.model

   Destination file name:

   • For physical host operation

     OracleDB-exporter-location\oracledb_exporter_windows\jp1ima\bin\oracledb_exporter_instance-name^#_service.xml

   • For logical host operation

     OracleDB-exporter-location\oracledb_exporter_windows\jp1ima\bin\oracledb_exporter_instance-name^#_logical-host-name_service.xml

   #

   For instance name, specify the name determined in - Preparation for adding a monitoring target in 1.23.1(4)(a) Adding a monitoring target (Required).

3. Updating service definition file.

   Modify the following for service definition file you created in step 2.

   Value to be changed	Value to specify
   @@instance@@	For physical host operation Replace with the name determined in step 1 of Preparing to add a monitoring target in 1.23.1(4)(a) Adding a monitoring target (Required). For logical host operation Replace with the name determined in step 1 of Preparing to add a monitoring target in 1.23.1(4)(a) Adding a monitoring target (Required) with the name "_logical-host-name".
   @@oracledb_exporter_installdir@@	Replace with OracleDB exporter location.
   @@autostart@@	To start automatically at OS startup "Automatic" To not start automatically "Manual" For logical hosts, substitute "Manual".
   @@port@@	Replace with the port number determined in step 2 of Preparing to add a monitoring target in 1.23.1(4)(a) Adding a monitoring target (Required). For a logical host, specify the logical host name, and replace it so that --web.listen-address="logical-host-name:port-number".
   @@installdir2@@	Replace with the directory confirmed in step 3 of Preparing to add a monitoring target in 1.23.1(4)(a) Adding a monitoring target (Required).
   @@data_source_name@@	Replace with the content confirmed in step 4 of Preparing to add a monitoring target in 1.23.1(4)(a) Adding a monitoring target (Required).

4. Register the service.

   Execute the command created in step 1 as follows.

   • For physical host operation

     oracledb_exporter_instance-name^#_service.exe install

   • For logical host operation

     oracledb_exporter_instance-name^#_logical-host-name_service.exe install

     For logical host operation, execute the command on both nodes that make up the cluster.

   #

   For instance name, specify the name determined in Preparing to add a monitoring target in 1.23.1(4)(a) Adding a monitoring target (Required).

5. Register the password of the user used to connect to Oracle Database.

   Register the password of the user used to connect to Oracle Database with the jimasecret command.

   • For physical host operation

     jimasecret -add -key OracleDB.user.user-name -s password

   • For logical host operation

     jimasecret -add -key OracleDB.user.user-name -s password -l shared-folder

   If you want to register users with the same user name but different passwords, you can use a key that includes the host name and the service name.

   For details about the jimasecret command, see jimasecret in Chapter 1. Commands in the JP1/Integrated Management 3 - Manager Command, Definition File and API Reference.

6. Register the service with the cluster software.

   For a cluster configuration, register the service with the cluster software.

7. Start OracleDB exporter service.

   Start OracleDB exporter service from the command line or from Windows Service Control Manager.

   For a cluster configuration, start the service from the cluster software.

8. Confirm that OracleDB exporter can acquire the performance information.

   The following URL can be accessed by using curl commands and browsers to check whether performance information can be obtained.

   http://host-name:port/metrics

   The hostname is the host on which OracleDB exporter is booting, and the port is the listen port of OracleDB exporter.

■ Configuring Prometheus

1. Add monitoring target to OracleDB exporter discovery configuration file.

   Add a new entry under targets in the OracleDB exporter discovery configuration file (jpc_file_sd_config_oracledb.yml).

   - targets:
   #  - <OracleDB hostname>:<an arbitrary name>:<oracledb_exporter port>
     - Oracle-Database-host-name: monitoring-target-name-1:port-number-1
     - Oracle-Database-host-name: monitoring-target-name-2:port-number-2
     - Oracle-Database-host-name: monitoring-target-name-3:port-number-3
     - Oracle-Database-host-name: monitoring-target-name-4:port-number-4  <- Add here
     labels:
       jp1_pc_exporter: JPC OracleDB exporter
       jp1_pc_category: database
       jp1_pc_trendname: oracledb_exporter
       jp1_pc_remote_monitor_instance: installation-destination-host-name:OracleDB metric collector(OracleDB exporter)

   Item	Value to specify
   Oracle Database host name	Specify the hostname confirmed in step 4 of Preparing to add a monitoring target in 1.23.1(4)(a) Adding a monitoring target (Required).
   Monitoring target name	Specify the monitoring target name determined in step 5 of Preparing to add a monitoring target in 1.23.1(4)(a) Adding a monitoring target (Required).
   Port number	Specify the port number determined in step 2 of Preparing to add a monitoring target in 1.23.1(4)(a) Adding a monitoring target (Required).

2. Check the settings with promtool command.

   Verify that the settings are correct.

   promtool is located in the JP1/IM - Agent-installation-location/jp1ima/tools folder.

   promtool check config jpc_prometheus_server.yml

   If an error is displayed, review the error.

3. Restart Prometheus.

   Restart Prometheus for the changes to take effect.

■ Configuring Intelligent Integrated Management Base

1. Refresh Intelligent Integrated Management Base tree a few minutes after all services have started.

   Generate or import tree data from integrated operation viewer, or execute jddcreatetree command or jddupdatetree command to refresh the tree and check the following:

   • Oracle Database targets are displayed in Intelligent Integrated Management Base tree.

   • The monitoring target can be selected and displayed as a trend.

■ Configuring Prometheus

1. Remove monitoring targets from OracleDB exporter discovery configuration file (jpc_file_sd_config_oracledb.yml).

   Deletes the monitoring targets listed in the targets of the OracleDB exporter discovery configuration file (jpc_file_sd_config_oracledb.yml).

2. Restart Prometheus.

   Restart Prometheus for the changes to take effect.

■ Removing OracleDB exporter from Cluster Software

For logical host operation, remove OracleDB exporter from the cluster software. If necessary, stop the service, etc.

■ Setting up OracleDB exporter

1. Stop OracleDB exporter service for the monitoring target to be deleted.

   Stop OracleDB exporter service from the command line or from Windows Service Control Manager.

2. Deregister a service.

   Unregister the service by executing the following command.

   • For physical host operation

     oracledb_exporter_instance name_service.exe uninstall

   • For logical host operation

     oracledb_exporter_instance name_logical host name_service.exe uninstall

   For logical host operation, execute the command on both nodes that make up the cluster.

3. Deletes the password for the user used to connect to Oracle Database.

   If you are not using the same user in another OracleDB exporter, use jimasecret commandto remove the registered password.

   • For physical host operation

     jimasecret -rm -key OracleDB.user.user-name

   • For logical host operation

     jimasecret -rm -key OracleDB.user.user-name -s password -l shared-folder

   If you register by specifying a key that includes a host name or listener name, specify that key.

4. Delete the service definition file and the Windows servicing program.

   Delete the following files in OracleDB exporter location \oracledb_exporter_windows\jp1ima\bin folder.

   • For physical host operation

     oracledb_exporter_instance-name_service.xml

     oracledb_exporter_instance-name_service.exe

   • For logical host operation

     oracledb_exporter_instance-name_logical-host-name_service.xml

     oracledb_exporter_instance-name_logical-host-name_service.exe