Oracle Database

The Oracle Database integration requires CXDOT Collector 1.11.0 or greater. Oracle Database is a relational database management system. Use the Oracle Database integration to collect session, wait time, cache, I/O, and tablespace metrics from Oracle Database instances running in your environment. The Oracle Database integration supports Oracle Database 19c or greater.

​

Supported telemetry types

The Oracle Database integration supports these telemetry types:

​

Prerequisites

The Oracle Database integration has the following prerequisites:

• Determine whether your database is a container database. Connect to the database with a SQL client and run the following query:
  SELECT cdb FROM v$database;
  
  A value of YES means the database is a container database. Connect the integration to the root container. From there, it reports instance-wide metrics and per-container metrics for the root and each pluggable database, identified by the oracle.db.pdb attribute. Connected to a pluggable database, per-container metrics cover that database only.
• Create a database user for the CXDOT Collector. For a container database, connect to the root container as SYSDBA and run the following statements to create a common user that can read every container’s statistics. For more information about CONTAINER_DATA, see ALTER USER in the Oracle Database documentation.
  CREATE USER c##cxdot IDENTIFIED BY "PASSWORD" CONTAINER = ALL;
  ALTER USER c##cxdot SET CONTAINER_DATA = ALL CONTAINER = CURRENT;
  GRANT CREATE SESSION TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$con_sysmetric TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$con_sysstat TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$containers TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$database TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$datafile TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$instance TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$osstat TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$pdbs TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$pgastat TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$process TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$resource_limit TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$rsrcmgrmetric TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$session TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$sgainfo TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$sysmetric TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON v_$sysstat TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON cdb_data_files TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON cdb_services TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON cdb_tablespace_usage_metrics TO c##cxdot CONTAINER = ALL;
  GRANT SELECT ON cdb_tablespaces TO c##cxdot CONTAINER = ALL;
  
  For a database that isn’t a container database, connect as SYSDBA and run the following statements instead:
  CREATE USER cxdot IDENTIFIED BY "PASSWORD";
  GRANT CREATE SESSION TO cxdot;
  GRANT SELECT ON v_$con_sysmetric TO cxdot;
  GRANT SELECT ON v_$containers TO cxdot;
  GRANT SELECT ON v_$database TO cxdot;
  GRANT SELECT ON v_$datafile TO cxdot;
  GRANT SELECT ON v_$instance TO cxdot;
  GRANT SELECT ON v_$osstat TO cxdot;
  GRANT SELECT ON v_$pgastat TO cxdot;
  GRANT SELECT ON v_$process TO cxdot;
  GRANT SELECT ON v_$resource_limit TO cxdot;
  GRANT SELECT ON v_$rsrcmgrmetric TO cxdot;
  GRANT SELECT ON v_$session TO cxdot;
  GRANT SELECT ON v_$sgainfo TO cxdot;
  GRANT SELECT ON v_$sysmetric TO cxdot;
  GRANT SELECT ON v_$sysstat TO cxdot;
  GRANT SELECT ON cdb_data_files TO cxdot;
  GRANT SELECT ON cdb_tablespace_usage_metrics TO cxdot;
  GRANT SELECT ON cdb_tablespaces TO cxdot;
  
  Replace PASSWORD with a password for the user. To reuse an existing monitoring user, run every statement except CREATE USER for that user.
• Make the Oracle Database listener, typically on port 1521, reachable from the CXDOT Collector over TCP. The integration uses a user name and password. It doesn’t support the TCPS protocol, Oracle wallets, or net service names from a tnsnames.ora file.

​

Configure

The integration is enabled by default and collects metrics from autodiscovery annotations or a static target list. To configure the Oracle Database integration, follow these steps:

1. For Oracle Database pods and Services, add autodiscovery annotations that supply each target’s endpoint, service name, user, and password. Annotations can also set per-target collection options, such as turning off per-process memory metrics that report one time series per Oracle Database process. For more information, see autodiscovery. Metrics from discovered pods arrive with that pod’s Kubernetes metadata attached.
2. Optional: Configure static targets instead of discovered targets, such as Oracle Database instances outside your Kubernetes cluster. Supply the password through your deployment’s secret management and expose it on the cluster-tier CXDOT Collector through clusterCollector.extraEnv. For example, add the following to the values.yaml file for the CXDOT Collector Helm chart:
   clusterCollector:
     extraEnv:
       - name: ORACLE_PASSWORD
         valueFrom:
           secretKeyRef:
             name: oracle-credentials
             key: password
   
   config:
     integrations:
       oracle:
         username: "c##cxdot"
         password: "${env:ORACLE_PASSWORD}"
         instances:
           - endpoint: oracle.example.com:1521
             service: ORCLCDB
   
   This integration instance collects only the listed instances and disables autodiscovery. Every instance uses the same username and password; use a separate integration instance for different credentials. One elected cluster-tier CXDOT Collector replica collects static targets. For more information, see architecture.
3. Optional: Configure separate integration instances to collect from both discovered and static targets. For example, add the following to the values.yaml file for the CXDOT Collector Helm chart:
   config:
     integrations:
       oracle: {}
       oracle/external:
         username: "c##cxdot"
         password: "${env:ORACLE_PASSWORD}"
         instances:
           - endpoint: oracle.example.com:1521
             service: ORCLCDB
   
   The oracle/external key holds the static targets. A named instance replaces the implicit default, so the empty oracle: {} entry keeps autodiscovery enabled.
4. Optional: Disable the integration. For example, add the following to the values.yaml file for the CXDOT Collector Helm chart:
   config:
     integrations:
       oracle:
         enabled: false
   

​

Validate

To validate the Oracle Database integration, follow these steps:

1. In the Live Telemetry Analyzer, add the following filters:
   • __name__=cxdot.integration.target.health
   • cxdot.integration.name=oracle
   Confirm that each target reports 1, identified by its server.address and server.port attributes. The cxdot.integration.check attribute separates the connection status, oracle, from the query status, oracle_query.
2. In Metrics Explorer, run the following query:
   sum by ("server.address", "server.port", "oracle.db.pdb") ({"oracledb.session.count"})
   
   Confirm that the query returns time series for each target. For a target connected to a root container, confirm that the query returns a time series for CDB$ROOT and for each open pluggable database.

​

Troubleshooting

• Metrics report only CDB$ROOT in the oracle.db.pdb attribute: the database user can’t read the statistics of other containers. Run the ALTER USER statement from the Prerequisites section, which sets the user’s CONTAINER_DATA to ALL.
• Some metrics are missing, such as execution and commit counts or resource limits: the database user lacks a Prerequisites grant. The CXDOT Collector logs Error scraping metrics with ORA-00942. The oracle_query health check can report 1 while these metrics are missing because it doesn’t cover every query. If you reuse a monitoring user from another tool, confirm grants on v_$sysstat, v_$con_sysstat, and v_$resource_limit.
• Session counts by type and status, and total Program Global Area (PGA) memory, carry no oracle.db.pdb attribute while other per-container metrics, such as tablespace metrics, do: the integration reports instance-wide totals until it confirms it can read each container’s statistics. When the database isn’t open yet, for example right after its pod restarted, the Collector logs failed to detect Oracle version, failed to detect CDB status, or per-PDB grants probe failed and retries each collection until the database answers. Those first two messages also mean the user lacks SELECT on v_$instance or v_$database; grant access and the next collection detects the database without a restart. When the user lacks SELECT on v_$con_sysstat, the Collector logs per-PDB grants not available and stops retrying; grant access and restart the CXDOT Collector.
• Tablespace metrics are missing while other metrics arrive: the tablespace queries timed out, or the user lacks a grant on the cdb_ views. A timed-out tablespace query retries only after a full tablespace collection interval. Raise timeout for static targets, or the annotation query timeout for discovered targets. That timeout can’t exceed the target’s collection interval, which defaults to 15, 30, or 60 seconds.

​

Configuration reference

Configure one Oracle Database integration instance with the following settings. In Helm values, place these settings under config.integrations.oracle. In a Collector configuration file, place them under cxdot.integrations.oracle.

​

Optional settings

• enabled Type: boolean. Optional. Default: true. Enables Oracle Database metrics collection. The Collector uses the instances listed in instances, or targets discovered through annotations when the list is empty.
• username Type: string. Optional. Oracle Database user for static instances. The Collector requires it when instances contains entries. For a container database, use a common user that can read every container’s statistics.
• password Type: string. Optional. Password for username. The Collector requires it to start collecting from instances entries, and masks the value in diagnostic output, logs, and errors.
• collection_interval Type: duration. Optional. Default: 60s. How often to collect metrics from each static Oracle Database instance. Oracle Database recomputes system metrics, such as hit ratios and rates, every 15 or 60 seconds. Discovered targets use the collection interval in their annotation instead.
• timeout Type: duration. Optional. Default: 20s. Maximum time to collect metrics from an Oracle Database instance during one interval. Each of the two tablespace queries gets the same limit, so an interval that includes them can take up to three times this value. A value of 0s disables all time limits. Discovered targets use the query timeout in their annotation, or this default when no timeout is set, limited to their collection interval.
• tablespace_collection_interval Type: duration. Optional. Default: 600s. How often the integration collects tablespace metrics from each statically configured instance. The tablespace queries read every container’s data files, so they run less often than the other queries. Between those queries, the integration reports the most recent tablespace values every collection_interval. Targets discovered through annotations use the tablespace interval in their annotation instead.
• instances Type: array of object. Optional. Default: []. Oracle Database instances to monitor. When this list contains an instance, the integration monitors only the listed instances and disables discovery through annotations for this integration instance. When the list is empty, the integration monitors targets supplied through Oracle Database annotations. Each discovered target uses the credentials in its annotation.
• instances[].endpoint Type: string. Required. host:port of the database listener, such as oracle.default.svc:1521.
• instances[].service Type: string. Required. Minimum length: 1. Oracle Database service name. For a container database, use the root container’s service to collect from every pluggable database.