> ## Documentation Index
> Fetch the complete documentation index at: https://docs-xcor.paloaltonetworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Oracle Database

> Oracle Database health and workload metrics, including sessions, wait and response time, cache hit ratios, I/O, and tablespace usage per pluggable database.

The Oracle Database integration requires CXDOT Collector 1.11.0 or greater.

[Oracle Database](https://www.oracle.com/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:

| Type | Supported |
| :-: | :-: |
| Logs | No |
| Metrics | Yes |
| Traces | No |
| Events | No |

## 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:

  ```sql theme={null}
  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`](https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/ALTER-USER.html)
  in the Oracle Database documentation.

  ```sql theme={null}
  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:

  ```sql theme={null}
  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](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/discover/kubernetes.md).

   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:

   ```yaml theme={null}
   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](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/install/kubernetes/architecture.md).

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:

   ```yaml theme={null}
   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:

   ```yaml theme={null}
   config:
     integrations:
       oracle:
         enabled: false
   ```

### Validate

To validate the Oracle Database integration, follow these steps:

1. In the
   [Live Telemetry Analyzer](https://docs-xcor.paloaltonetworks.com/investigate/analyze/telemetry-analyzer.md),
   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](https://docs-xcor.paloaltonetworks.com/investigate/querying/metrics/explorer.md),
   run the following query:

   ```text theme={null}
   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.


## Related topics

- [CXDOT Collector integrations](/ingest/xcor/integrations/collector.md)
- [SQL DB Input source plugin](/ingest/pipeline/plugins/source-plugins/sqldb.md)
- [Oracle Log Analytics destination plugin](/ingest/pipeline/plugins/destination-plugins/oracle.md)
- [Ingest Google Cloud metrics](/ingest/xcor/integrations/server/gcp.md)
- [Azure metrics available in Palo Alto Networks Cortex XCOR](/ingest/xcor/integrations/server/azure/azure-metrics.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.