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:
A value of
YESmeans 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 theoracle.db.pdbattribute. If the integration connects 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
SYSDBAand run the following statements to create a common user that can read every container’s statistics. For more information aboutCONTAINER_DATA, seeALTER USERin the Oracle Database documentation.For a database that isn’t a container database, connect asSYSDBAand run the following statements instead:ReplacePASSWORDwith a password for the user. To reuse an existing monitoring user, run every statement exceptCREATE USERfor 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 theTCPSprotocol, Oracle wallets, or net service names from atnsnames.orafile.
Configure
The integration is enabled by default. You can configure targets either by annotating pods and Services in your Kubernetes cluster or by listing static endpoints in your Helm values. To configure the Oracle Database integration, follow these steps:-
To collect from Oracle Database pods in Kubernetes, add a CXDOT integration
annotation to the pod template. The annotation key must end with the container name,
and its value specifies the database service name and references credentials stored in
a Kubernetes Secret in the same namespace. For example, add the following annotation
to your Oracle Database workload:
The Collector replaces
${target.host}with the pod IP address,${target.port.listener}with the container port namedlistener, and${k8s_secret:oracle-credentials/password}with thepasswordkey of theoracle-credentialsSecret. To allow the Collector to read the Secret, add the pod’s namespace toapiServer.metadataServer.secretAllowlistin the Helm values for your CXDOT Collector. -
Optional: To collect from Oracle Database instances outside your Kubernetes cluster,
configure static targets instead of annotated targets. 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 thevalues.yamlfile for the CXDOT Collector Helm chart:This integration instance collects only the listed instances and disables autodiscovery. Every instance uses the sameusernameandpassword. Use a separate integration instance for different credentials. One elected cluster-tier CXDOT Collector replica collects static targets. For more information, see architecture. -
Optional: Report SQL query results as metrics. Add
custom_queriesto a static instance or to an instance in a CXDOT integration annotation. The following query reports free space for each Automatic Storage Management (ASM) disk group asoracle.asm_diskgroup.free_mb. Theasm_diskgroup_nameattribute identifies the disk group:Grant the database userSELECTon each view or table that a query reads. This example requiresSELECTonv_$asm_diskgroup. For a query in a pluggable database, also grantSET CONTAINERin that database. -
Optional: Configure separate integration instances to collect from both annotated
and static targets. For example, add the following to the
values.yamlfile for the CXDOT Collector Helm chart:Theoracle/externalkey holds the static targets. A named instance replaces the implicit default, so the emptyoracle: {}entry keeps autodiscovery enabled. -
Optional: Disable the integration. For example, add the following to the
values.yamlfile for the CXDOT Collector Helm chart:
Validate
To validate the Oracle Database integration, follow these steps:-
In the
Live Telemetry Analyzer,
add the following filters:
__name__=cxdot.integration.target.healthcxdot.integration.name=oracle
1, identified by itsserver.addressandserver.portattributes. Thecxdot.integration.checkattribute separates the connection status,oracle, from the query status,oracle_query. -
In
Metrics Explorer,
run the following query:
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$ROOTand for each open pluggable database.
Troubleshooting
- Metrics report only
CDB$ROOTin theoracle.db.pdbattribute: the database user can’t read the statistics of other containers. Run theALTER USERstatement from the Prerequisites section, which sets the user’sCONTAINER_DATAtoALL. - 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 metricswithORA-00942. Theoracle_queryhealth check can report1while these metrics are missing because it doesn’t cover every query. If you reuse a monitoring user from another tool, confirm grants onv_$sysstat,v_$con_sysstat, andv_$resource_limit, and for a pluggable database also onv_$parameter,v_$transaction, andv_$lock. - Average active sessions, CPU usage, physical reads and writes, session counts by type
and status, and total Program Global Area (PGA) memory carry no
oracle.db.pdbattribute 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 logsfailed to detect Oracle version,failed to detect CDB status, orper-PDB grants probe failedand retries each collection until the database answers. Those first two messages also mean the user lacksSELECTonv_$instanceorv_$database. Grant access, and the next collection detects the database without a restart. When the user lacksSELECTonv_$con_sysstat, the Collector logsper-PDB grants not availableand stops retrying. Grant access and restart the CXDOT Collector. - Custom query metrics are missing and the
oracle_queryhealth check reports0: a custom query failed. The CXDOT Collector logsError scraping metricswithcustom query. A query fails if its result has a different number of columns than itscolumnslist, or if a metric column contains aNULLor a value that isn’t numeric. UseNVLorCOALESCEfor columns that can containNULL. - 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. Raisetimeoutin your Helm values or in a CXDOT integration annotation.
Configuration reference
Configure one Oracle Database integration instance with the following settings. In Helm values, place these settings undercollection.cxdot.integrations.oracle. In a Collector configuration
file, place them under cxdot.integrations.oracle.
Optional settings
-
enabledType:boolean. Optional. Default:true. If true, the Collector collects Oracle Database metrics from the instances listed ininstances, or from targets discovered through annotations when the list is empty. If false, the Collector doesn’t collect Oracle Database metrics. -
usernameType:string. Optional. Oracle Database user for the configured instances. The Collector requires it wheninstancescontains entries. For a container database, use a common user that can read every container’s statistics. -
passwordType:string. Optional. Password forusername. The Collector requires it to start collecting frominstancesentries, and masks the value in diagnostic output, logs, and errors. -
collection_intervalType:duration. Optional. Default:60s. How often to collect metrics from each configured 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. -
timeoutType:duration. Optional. Default:20s. Maximum time to collect metrics from an Oracle Database instance during one interval. Each tablespace query gets this limit. All custom queries share one additional limit. An interval that runs both tablespace queries and custom queries can take up to four times this value. A value of0sdisables 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_intervalType:duration. Optional. Default:600s. How often the integration collects tablespace metrics from each 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 everycollection_interval. Targets discovered through annotations use the tablespace interval in their annotation instead. -
collect_system_metricsType:boolean. Optional. Default:true. Whether to collect the core system metrics Oracle Database computes inV$SYSMETRIC: cache hit ratios, session counts and utilization, the wait time ratio, logon, transaction, scan, and sort rates, SQL service latency, and temporary space usage. If false, the Collector reports none of them. Applies to the configured targets. Annotation-discovered targets use thesysmetricssetting of their own annotation instance instead. -
collect_extended_system_metricsType:boolean. Optional. Default:true. Whether to collect the extended system metrics fromV$SYSMETRIC: CPU usage and host load, logical and physical I/O rates, data file and network I/O, parse rates and ratios, redo generation, checkpoint and block change rates, cache hit ratios, and process utilization. If false, the Collector reports none of them. Applies to the configured targets. Annotation-discovered targets collect them only when their annotation instance enables Database Monitoring withdbm: trueand leavessysmetricson. -
collect_process_memoryType:boolean. Optional. Default:true. Whether to collect the Program Global Area (PGA) memory each Oracle Database process has allocated, is using, and can free, with its maximum. The Collector reports one time series per process, so this family grows with the number of processes on the instance. If false, the Collector doesn’t readV$PROCESSmemory. Applies to the configured targets. Annotation-discovered targets use theprocess_memorysetting of their own annotation instance instead. -
collect_inactive_sessionsType:boolean. Optional. Default:true. Whether to collect the time since each inactive session’s last call, one time series per session. If false, the Collector doesn’t reportoracledb.session.last_call.age. Applies to the configured targets. Annotation-discovered targets use theinactive_sessionssetting of their own annotation instance instead. -
collect_session_countsType:boolean. Optional. Default:true. Whether to collectoracledb.sessions.usage, the number of sessions by session type and status. If false, the Collector doesn’t report it. Applies to the configured targets. Annotation-discovered targets count sessions when their annotation instance leavesuser_sessions_counton and at least one ofprocess_memoryandinactive_sessionson. -
collect_tablespacesType:boolean. Optional. Default:true. Whether to collect tablespace metrics: the size, limit, utilization, and status of every tablespace, read everytablespace_collection_interval. If false, the Collector doesn’t run the tablespace queries. Applies to the configured targets. Annotation-discovered targets use thetablespacessetting of their own annotation instance instead. -
collect_shared_memoryType:boolean. Optional. Default:true. Whether to collectoracledb.sga.size, the size of each System Global Area component. If false, the Collector doesn’t readV$SGAINFO. Applies to the configured targets. Annotation-discovered targets collect it only when their annotation instance enables Database Monitoring withdbm: trueand leavesshared_memoryon. -
collect_resource_managerType:boolean. Optional. Default:true. Whether to collect the CPU time each Resource Manager consumer group consumed and waited for. If false, the Collector doesn’t readV$RSRCMGRMETRIC. Applies to the configured targets. Annotation-discovered targets collect it only when their annotation instance enables Database Monitoring withdbm: trueand leavesresource_manageron. -
collect_asmType:boolean. Optional. Default:true. Whether to collect the space and offline disks of each Automatic Storage Management disk group. If false, the Collector doesn’t readV$ASM_DISKGROUP_STAT. A database without Automatic Storage Management reports none. Applies to the configured targets. Annotation-discovered targets use theasmsetting of their own annotation instance instead. -
instancesType:array of object. Optional. Default:[]. Oracle Database instances to monitor. Each discovered target uses the credentials in its annotation. -
instances[].endpointType:string. Required.host:portof the database listener, such asoracle.default.svc:1521. -
instances[].serviceType: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. -
instances[].tagsType:array of string. Optional. Default:[]. Resource attributes inkey:valueformat to add to every time series from this instance. For example,dbname:billingaddsdbnamewith the valuebilling. Values can contain colons. The integration ignores entries without a colon and keeps the last value for repeated keys. A tag can’t replace an attribute set by the integration or by the collector-wideresource_attributes. Discovered targets applytagsfrom their annotation instance in the same way. -
instances[].custom_queriesType:array of object. Optional. Default:[]. SQL queries that report results as metrics for this instance. Each query runs every collection interval unless it setscollection_interval. A query failure reports no metrics for that collection and sets theoracle_queryhealth check to0. Other metrics and queries continue. Grant the database userSELECTon every view and table that the queries read. -
instances[].custom_queries[].queryType:string. Required. Minimum length:1. SQL statement to run. Each result row produces one data point for each metric column. Tag columns become attributes on those data points. -
instances[].custom_queries[].metric_prefixType:string. Optional. Default:oracle. Prefix of every metric name the query reports. A metric name is the prefix, a period, and the column’sname, such asoracle.asm_diskgroup.free_mb. -
instances[].custom_queries[].columnsType:array of object. Required. Minimum items:1. One entry for each column the query returns, in the order the query returns them. The query fails when it returns a different number of columns. An entry without aname, such as{}, skips its column. -
instances[].custom_queries[].columns[].nameType:string. Optional. Metric name suffix for a metric column, or attribute name for atagcolumn. -
instances[].custom_queries[].columns[].typeType:string. Optional. How the integration reports the column.tagadds the value as an attribute on each of the row’s data points and leaves it off when the value isNULL.gaugereports the value as a gauge.countadds up a non-negative column across rows with the same attribute values and adds that total to a cumulative counter on every run.monotonic_countandratereport the value as a cumulative counter, for a column that only increases until the database restarts. Use theincreaseorratefunction to query a counter’s change. Allowed values:tag,gauge,count,monotonic_count,rate. -
instances[].custom_queries[].tagsType:array of string. Optional. Default:[]. Attributes to add to every data point of the query, each in the formkey:value. The value can contain colons. The integration ignores an entry without a colon. A tag here replaces atagcolumn of the same name. -
instances[].custom_queries[].collection_intervalType:number. Optional. Minimum:1. Seconds between query runs, truncated to whole seconds. The query runs during the first collection that falls no earlier than half a collection interval before the interval passes, so collection timing jitter doesn’t skip runs. Between runs, each collection reports the metrics from the last run, or none if that run failed. When unset, the query runs every collection interval. The Datadog Agent’s Oracle check accepts this setting but runs every query during each collection. A query carried over from the Agent with this setting runs less often here. -
instances[].custom_queries[].pdbType:string. Optional. Default:CDB$ROOT. Oracle Database container in which to run the query. This setting applies whenservicenames a container database’s root container. The integration adds the container name to every data point as theoracle.db.pdbattribute. A connection to a pluggable database or a database without containers ignores this setting and runs the query where it connects. A query in a pluggable database requires the database user to have theSET CONTAINERprivilege in that pluggable database.