--- title: Oracle Database monitoring with NRDOT source: https://docs.newrelic.com/docs/opentelemetry/database/otel-oracledb --- > #### 💡 PREVIEW > > We're still working on this feature, but we'd love for you to try it out! > > This feature is currently provided as part of a preview pursuant to our [pre-release policies](https://docs.newrelic.com/docs/licenses/license-information/referenced-policies/new-relic-pre-release-policy/). New Relic now empowers your team to monitor your Oracle Database performance using New Relic Distribution of OpenTelemetry (NRDOT) with New Relic database monitoring capabilities. This integration provides comprehensive insights into database metrics, query performance, and system health using the NRDOT collector. This NRDOT-based approach complements our existing On-Host Integration (OHI) by leveraging OpenTelemetry standards for database monitoring, making it easier to integrate with your existing observability stack. ## Prerequisites [#prerequisites] Before you begin, ensure you have the following: - Valid New Relic [license key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#ingest-license-key) - Supported architecture: Linux with AMD64 and ARM64 - Network connectivity to New Relic OTLP endpoint - Oracle Database 19c or later - This integration is available as a part of New Relic public preview program. Check with your Organization Manager to opt in from the [Previews & Trials](https://one.newrelic.com/admin-portal/promotion-management/home) page. ## Set-up the NRDOT Collector for Oracle Database monitoring [#install-collector] You can set up Oracle Database monitoring using the NRDOT Collector in on-host (multitenant) or RDS environments. You can configure NRDOT Collector using the following methods: - [Guided install](https://docs.newrelic.com/docs/opentelemetry/database/otel-oracledb/#guided): The guided install method provides step-by-step instructions on the New Relic platform to help you install and configure the NRDOT Collector for Oracle Database monitoring. - **Manual install**: The manual install method allows you to set up the NRDOT Collector on your own by following the instructions in this documentation. You can manually configure in following environments: - [On-host (multitenant) environment](https://docs.newrelic.com/docs/opentelemetry/database/otel-oracledb/#host): Install the NRDOT Collector on the same host as your Oracle Database instance to collect both infrastructure and database telemetry data. - [RDS environment](https://docs.newrelic.com/docs/opentelemetry/database/otel-oracledb/#rds): Install the NRDOT Collector in an RDS environment to monitor your Oracle Database instances running in Amazon RDS. > #### 💡 TIP > > The NRDOT Collector collects both infrastructure and database related telemetry data, so you can have a unified observability solution for your Oracle Database environment in New Relic. ### Guided install To install the NRDOT Collector: #### Install NRDOT Collector [#guided] 1. Log in to your [New Relic account](https://one.newrelic.com/). 2. Go to **left navigation pane > + Integration & Agents > Oracle (OpenTelemetry)**. 3. On the Select an account screen, select the account you want to install the Oracle Database integration on, and click **Continue**. 4. On the Enter your credential screen, select one of the following options, then click **Continue**: - **Use an existing key**: If you already have a license key, provide the license key. For more information, refer to [User keys](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#user-key). - **Create a new key**: If you don't have a license key, click **Create a new key** to create one. 5. On the Compatibility and requirements screen, ensure that all the requirements are met, and click **Continue**. 6. On the Database user configuration screen, select your deployment type to install the integration. 7. Follow the on-screen instructions to set up the integration for the selected environment. 8. After installation, on the Test your integration screen, click **Test connection** to verify that the NRDOT Collector can connect to your Oracle Database instance and send data to New Relic. If the test's successful, you'll see a confirmation message. #### (Optional) Set up APM-database correlation [#optional-service-id] To correlate your application performance with database operations, you can set up database service identification. This feature allows you to see exactly which applications are generating specific database workloads. For more information, refer to [set up database service identification](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/db-apm) to get APM-database correlation in New Relic. > #### ⚠️ IMPORTANT > > To view database performance data in APM, both entities must be in the same New Relic account. If the entities are in different New Relic accounts, you must have access to both accounts to view the data. #### Find and use your data [#find-use-data] Once your data is being collected, you can access comprehensive Oracle Database monitoring through New Relic UI. To find your Oracle Database entity in New Relic: 1. Go to ** > All Capabilities > Databases**. 2. Set the search criteria as `instrumentation.provider = opentelemetry`. 3. Select your Oracle Database from the list of entities. ### For on-host #### CDB You can set up Oracle Database monitoring using the NRDOT Collector in on-host or multitenant environments. To install the NRDOT Collector in on-host (multitenant) environments, follow these steps: **Note:** All PDBs under this CDB will be monitored. ##### Installation method [#m-installation] Select the appropriate installation distribution method for your Linux environment: **For AMD64 architecture** - For Debian/Ubuntu system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_amd64.deb" --output nrdot-collector.deb && sudo dpkg -i nrdot-collector.deb ``` - For RHEL/CentOS/OEL system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_x86_64.rpm" --output nrdot-collector.rpm && sudo rpm -ivh nrdot-collector.rpm ``` **For ARM64 architecture** - For Debian/Ubuntu system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_arm64.deb" --output nrdot-collector.deb && sudo dpkg -i nrdot-collector.deb ``` - For RHEL/CentOS/OEL system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_arm64.rpm" --output nrdot-collector.rpm && sudo rpm -ivh nrdot-collector.rpm ``` ##### Configure database user [#mdatabase-user] Create a monitoring user with necessary privileges for your multitenant Oracle Database. This requires creating a common user with the `C##` prefix. 1. Before creating the database user or running any assignment grants, you must execute the following statement as a `SYS` user to set your current active container context to `CDB$ROOT`: ```sql ALTER SESSION SET CONTAINER = CDB$ROOT; ``` 2. For multitenant databases, log in to the root database as an administrator. Use CREATE USER to add a new user to the database. Specified username will be a 'common user' and needs to be prefixed with `c##` as recommended by Oracle. ```sql CREATE USER c## IDENTIFIED BY "" CONTAINER=ALL; GRANT CREATE SESSION TO c## CONTAINER=ALL; ``` 3. Run the following statement as SYSDBA on the CDB root. This allows the monitoring user to see every PDB's rows in container-data views, which is required for per-PDB metrics and events. ```sql ALTER USER c## SET CONTAINER_DATA=ALL CONTAINER=CURRENT; ``` > #### 💡 TIP > > Ensure your `USER_PASSWORD` meets Oracle [new user password](https://docs.oracle.com/en/database/oracle/oracle-database/12.2/dbseg/keeping-your-oracle-database-secure.html#GUID-451679EB-8676-47E6-82A6-DF025FD65156) requirements. ##### Grant monitoring privileges for multitenant database [#mgrant-privileges] Run the following `GRANT` statements as `SYSDBA` on the CDB root. These cover instance detection, metrics collection, per-PDB monitoring, and events collection. You can execute them together as a single script or run each statement individually. ```sql GRANT SELECT ON V_$INSTANCE TO c## CONTAINER=ALL; GRANT SELECT ON V_$DATABASE TO c## CONTAINER=ALL; GRANT SELECT ON V_$CONTAINERS TO c## CONTAINER=ALL; GRANT SELECT ON V_$DATAFILE TO c## CONTAINER=ALL; GRANT SELECT ON V_$SYSSTAT TO c## CONTAINER=ALL; GRANT SELECT ON V_$CON_SYSSTAT TO c## CONTAINER=ALL; GRANT SELECT ON V_$SYSMETRIC TO c## CONTAINER=ALL; GRANT SELECT ON V_$CON_SYSMETRIC TO c## CONTAINER=ALL; GRANT SELECT ON V_$SESSION TO c## CONTAINER=ALL; GRANT SELECT ON V_$RESOURCE_LIMIT TO c## CONTAINER=ALL; GRANT SELECT ON V_$OSSTAT TO c## CONTAINER=ALL; GRANT SELECT ON V_$SGAINFO TO c## CONTAINER=ALL; GRANT SELECT ON V_$ROWCACHE TO c## CONTAINER=ALL; GRANT SELECT ON V_$PARAMETER TO c## CONTAINER=ALL; GRANT SELECT ON CDB_TABLESPACE_USAGE_METRICS TO c## CONTAINER=ALL; GRANT SELECT ON CDB_TABLESPACES TO c## CONTAINER=ALL; GRANT SELECT ON DBA_DATA_FILES TO c## CONTAINER=ALL; GRANT SELECT ON DBA_FREE_SPACE TO c## CONTAINER=ALL; GRANT SELECT ON DBA_RECYCLEBIN TO c## CONTAINER=ALL; GRANT SELECT ON V_$SQL TO c## CONTAINER=ALL; GRANT SELECT ON V_$SQL_PLAN_STATISTICS_ALL TO c## CONTAINER=ALL; GRANT SELECT ON V_$LOCK TO c## CONTAINER=ALL; GRANT SELECT ON V_$SESSION_EVENT TO c## CONTAINER=ALL; GRANT SELECT ON DBA_PROCEDURES TO c## CONTAINER=ALL; GRANT SELECT ON DBA_OBJECTS TO c## CONTAINER=ALL; GRANT SELECT ON V_$PDBS TO c## CONTAINER=ALL; GRANT SELECT ON CDB_SERVICES TO c## CONTAINER=ALL; ``` ##### Configure NRDOT Collector [#mconfigure-collector] 1. Create the configuration file. The filename must be `oracle-config.yaml`. ```bash sudo nano /etc/nrdot-collector/oracle-config.yaml ``` 2. Add the configuration content below to the `oracle-config.yaml` file you created in the previous step. **NRDOT host with database configuration** ```yaml extensions: health_check: receivers: otlp: protocols: grpc: http: hostmetrics: collection_interval: 60s scrapers: cpu: metrics: system.cpu.time: enabled: false system.cpu.utilization: enabled: true load: memory: metrics: system.memory.utilization: enabled: true paging: metrics: system.paging.utilization: enabled: false system.paging.faults: enabled: false filesystem: metrics: system.filesystem.utilization: enabled: true disk: metrics: system.disk.merged: enabled: false system.disk.pending_operations: enabled: false system.disk.weighted_io_time: enabled: false network: metrics: system.network.connections: enabled: false # Uncomment to enable process metrics, which can be noisy but valuable. # processes: # process: # metrics: # process.cpu.utilization: # enabled: true # process.cpu.time: # enabled: false filelog: include: - /var/log/alternatives.log - /var/log/cloud-init.log - /var/log/auth.log - /var/log/dpkg.log - /var/log/syslog - /var/log/messages - /var/log/secure - /var/log/yum.log nroracledb: endpoint: ":" username: "C##" password: "" service: "" collection_interval: 10s events: db.server.query_sample: enabled: true db.server.top_query: enabled: true db.server.session.wait_sample: enabled: true top_query_collection: max_query_sample_count: 1000 top_query_count: 200 collection_interval: 60s allowed_comment_keys: - nr_service_guid query_sample_collection: max_rows_per_query: 100 allowed_comment_keys: - nr_service_guid session_wait_event_collection: max_rows_per_query: 100 # Metrics configuration - organized by category metrics: # === CPU & Performance Metrics === oracledb.cpu_time: enabled: true attributes: - oracle.db.pdb oracledb.database.cpu.utilization: enabled: true attributes: - oracle.db.pdb oracledb.host.cpu.utilization: enabled: true attributes: - oracle.db.pdb # === Execution & Parse Metrics === oracledb.executions: enabled: true attributes: - oracle.db.pdb oracledb.execution.utilization: enabled: true attributes: - oracledb.parse.type - oracle.db.pdb oracledb.parse_calls: enabled: true attributes: - oracle.db.pdb oracledb.parse.rate: enabled: true attributes: - oracledb.parse.result - oracle.db.pdb oracledb.parse.utilization: enabled: true attributes: - oracle.db.pdb oracledb.hard_parses: enabled: true attributes: - oracle.db.pdb # === I/O & Physical Read/Write Metrics === oracledb.logical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_read_io_requests: enabled: true attributes: - oracle.db.pdb oracledb.physical_write_io_requests: enabled: true attributes: - oracle.db.pdb # === New Physical I/O Metrics (detailed) === oracledb.physical_io.cache_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_io.requests: enabled: true attributes: - disk.io.direction - disk.io.block_size - oracle.db.pdb oracledb.physical_io.transferred: enabled: true attributes: - disk.io.direction - disk.io.type - oracle.db.pdb # === Network I/O Metrics === oracledb.sqlnet.io.transferred: enabled: true attributes: - network.io.direction - destination.type - oracle.db.pdb # === Buffer & Cache Metrics === oracledb.consistent_gets: enabled: true attributes: - oracle.db.pdb oracledb.db_block_gets: enabled: true attributes: - oracle.db.pdb oracledb.buffer_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.library_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.data_dictionary.hit_ratio: enabled: true oracledb.shared_pool.utilization: enabled: true attributes: - oracle.db.pdb # === Memory Metrics === oracledb.pga_memory: enabled: true attributes: - oracle.db.pdb oracledb.sga.limit: enabled: true oracledb.sga.usage: enabled: true attributes: - oracledb.sga.component.name # === Wait & Database Time Metrics === oracledb.database.wait.utilization: enabled: true attributes: - oracle.db.pdb # === Lock & Deadlock Metrics === oracledb.dml_locks.limit: enabled: true oracledb.dml_locks.usage: enabled: true oracledb.enqueue_locks.limit: enabled: true oracledb.enqueue_locks.usage: enabled: true oracledb.enqueue_resources.limit: enabled: true oracledb.enqueue_resources.usage: enabled: true oracledb.enqueue_deadlocks: enabled: true attributes: - oracle.db.pdb oracledb.exchange_deadlocks: enabled: true attributes: - oracle.db.pdb # === Process & Session Metrics === oracledb.processes.limit: enabled: true oracledb.processes.usage: enabled: true oracledb.sessions.limit: enabled: true oracledb.sessions.usage: enabled: true attributes: - session_type - session_status - oracle.db.pdb oracledb.logons: enabled: true attributes: - oracle.db.pdb # === Transaction Metrics === oracledb.transactions.limit: enabled: true oracledb.transactions.usage: enabled: true oracledb.user_commits: enabled: true attributes: - oracle.db.pdb oracledb.user_rollbacks: enabled: true attributes: - oracle.db.pdb # === Tablespace Metrics === oracledb.tablespace_size.limit: enabled: true attributes: - tablespace_name - oracle.db.pdb oracledb.tablespace_size.usage: enabled: true attributes: - tablespace_name - oracle.db.pdb # === Storage Metrics === oracledb.storage.usage: enabled: true oracledb.storage.utilization: enabled: true oracledb.recycle_bin.limit: enabled: true # === Parallel Operations Metrics === oracledb.queries_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.ddl_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.dml_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_not_downgraded: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_1_to_25_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_25_to_50_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_50_to_75_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_75_to_99_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_to_serial: enabled: true attributes: - oracle.db.pdb # === Redo & Sort Metrics === oracledb.redo_allocation.utilization: enabled: true attributes: - oracle.db.pdb oracledb.sort.ratio: enabled: true attributes: - oracledb.sort.type - oracle.db.pdb # === Response Time Metrics === oracledb.sql_service.response.duration: enabled: true attributes: - oracle.db.pdb # Resource attributes attached to all metrics/logs (all enabled by default) resource_attributes: host.name: enabled: true oracle.db.hosting_type: enabled: true oracle.db.open_mode: enabled: true oracle.db.pdb: enabled: true oracle.db.role: enabled: true oracle.db.version: enabled: true oracledb.instance.name: enabled: true service.instance.id: enabled: true processors: metricstransform: transforms: - include: system.cpu.utilization action: update operations: - action: aggregate_labels label_set: [ state ] aggregation_type: mean - include: system.paging.operations action: update operations: - action: aggregate_labels label_set: [ direction ] aggregation_type: sum filter/exclude_cpu_utilization: metrics: datapoint: - 'metric.name == "system.cpu.utilization" and attributes["state"] == "interrupt"' - 'metric.name == "system.cpu.utilization" and attributes["state"] == "nice"' - 'metric.name == "system.cpu.utilization" and attributes["state"] == "softirq"' filter/exclude_memory_utilization: metrics: datapoint: - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_unreclaimable"' - 'metric.name == "system.memory.utilization" and attributes["state"] == "inactive"' - 'metric.name == "system.memory.utilization" and attributes["state"] == "cached"' - 'metric.name == "system.memory.utilization" and attributes["state"] == "buffered"' - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_reclaimable"' filter/exclude_memory_usage: metrics: datapoint: - 'metric.name == "system.memory.usage" and attributes["state"] == "slab_unreclaimable"' - 'metric.name == "system.memory.usage" and attributes["state"] == "inactive"' filter/exclude_filesystem_utilization: metrics: datapoint: - 'metric.name == "system.filesystem.utilization" and attributes["type"] == "squashfs"' filter/exclude_filesystem_usage: metrics: datapoint: - 'metric.name == "system.filesystem.usage" and attributes["type"] == "squashfs"' - 'metric.name == "system.filesystem.usage" and attributes["state"] == "reserved"' filter/exclude_filesystem_inodes_usage: metrics: datapoint: - 'metric.name == "system.filesystem.inodes.usage" and attributes["type"] == "squashfs"' - 'metric.name == "system.filesystem.inodes.usage" and attributes["state"] == "reserved"' filter/exclude_system_disk: metrics: datapoint: - 'metric.name == "system.disk.operations" and IsMatch(attributes["device"], "^loop.*") == true' - 'metric.name == "system.disk.merged" and IsMatch(attributes["device"], "^loop.*") == true' - 'metric.name == "system.disk.io" and IsMatch(attributes["device"], "^loop.*") == true' - 'metric.name == "system.disk.io_time" and IsMatch(attributes["device"], "^loop.*") == true' - 'metric.name == "system.disk.operation_time" and IsMatch(attributes["device"], "^loop.*") == true' filter/exclude_system_paging: metrics: datapoint: - 'metric.name == "system.paging.usage" and attributes["state"] == "cached"' - 'metric.name == "system.paging.operations" and attributes["type"] == "cached"' filter/exclude_network: metrics: datapoint: - 'IsMatch(metric.name, "^system.network.*") == true and attributes["device"] == "lo"' attributes/exclude_system_paging: include: match_type: strict metric_names: - system.paging.operations actions: - key: type action: delete transform/clear_metadata: metric_statements: - context: metric statements: - set(metric.description, "") - set(metric.unit, "") transform/host: metric_statements: - context: metric statements: - set(metric.description, "") - set(metric.unit, "") transform: trace_statements: - context: span statements: - truncate_all(span.attributes, 4095) - truncate_all(resource.attributes, 4095) log_statements: - context: log statements: - truncate_all(log.attributes, 4095) - truncate_all(resource.attributes, 4095) memory_limiter: check_interval: 1s limit_mib: ${env:NEW_RELIC_MEMORY_LIMIT_MIB:-100} batch: resource/add_event_name: attributes: - key: host.address value: "" action: upsert resourcedetection: detectors: ["system"] system: hostname_sources: ["os"] resource_attributes: host.id: enabled: true resourcedetection/db_safe: detectors: ["system"] override: false system: hostname_sources: ["os"] resource_attributes: host.id: enabled: true resourcedetection/cloud: detectors: ["gcp", "ec2", "azure"] timeout: 2s override: true resourcedetection/env: detectors: ["env"] timeout: 2s override: true exporters: otlp: endpoint: "" headers: api-key: "" compression: gzip service: pipelines: metrics/host: receivers: [hostmetrics] processors: - memory_limiter - metricstransform - filter/exclude_cpu_utilization - filter/exclude_memory_utilization - filter/exclude_memory_usage - filter/exclude_filesystem_utilization - filter/exclude_filesystem_usage - filter/exclude_filesystem_inodes_usage - filter/exclude_system_disk - filter/exclude_network - attributes/exclude_system_paging - transform/host - resourcedetection - resourcedetection/cloud - resourcedetection/env - batch exporters: [otlp] traces: receivers: [otlp] processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch] exporters: [otlp] metrics: receivers: [otlp] processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch] exporters: [otlp] logs: receivers: [otlp] processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch] exporters: [otlp] metrics/oracledb: receivers: [nroracledb] processors: [resource/add_event_name, batch] exporters: [otlp] logs/oracledb: receivers: [nroracledb] processors: [resource/add_event_name, batch] exporters: [otlp] extensions: [health_check] ``` **Database configuration** ```yaml receivers: nroracledb: endpoint: ":" username: "C##" password: "" service: "" collection_interval: 10s events: db.server.query_sample: enabled: true db.server.top_query: enabled: true db.server.session.wait_sample: enabled: true top_query_collection: max_query_sample_count: 1000 top_query_count: 200 collection_interval: 60s allowed_comment_keys: - nr_service_guid query_sample_collection: max_rows_per_query: 100 allowed_comment_keys: - nr_service_guid session_wait_event_collection: max_rows_per_query: 100 # Metrics configuration - organized by category metrics: # === CPU & Performance Metrics === oracledb.cpu_time: enabled: true attributes: - oracle.db.pdb oracledb.database.cpu.utilization: enabled: true attributes: - oracle.db.pdb oracledb.host.cpu.utilization: enabled: true attributes: - oracle.db.pdb # === Execution & Parse Metrics === oracledb.executions: enabled: true attributes: - oracle.db.pdb oracledb.execution.utilization: enabled: true attributes: - oracledb.parse.type - oracle.db.pdb oracledb.parse_calls: enabled: true attributes: - oracle.db.pdb oracledb.parse.rate: enabled: true attributes: - oracledb.parse.result - oracle.db.pdb oracledb.parse.utilization: enabled: true attributes: - oracle.db.pdb oracledb.hard_parses: enabled: true attributes: - oracle.db.pdb # === I/O & Physical Read/Write Metrics === oracledb.logical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_read_io_requests: enabled: true attributes: - oracle.db.pdb oracledb.physical_write_io_requests: enabled: true attributes: - oracle.db.pdb # === New Physical I/O Metrics (detailed) === oracledb.physical_io.cache_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_io.requests: enabled: true attributes: - disk.io.direction - disk.io.block_size - oracle.db.pdb oracledb.physical_io.transferred: enabled: true attributes: - disk.io.direction - disk.io.type - oracle.db.pdb # === Network I/O Metrics === oracledb.sqlnet.io.transferred: enabled: true attributes: - network.io.direction - destination.type - oracle.db.pdb # === Buffer & Cache Metrics === oracledb.consistent_gets: enabled: true attributes: - oracle.db.pdb oracledb.db_block_gets: enabled: true attributes: - oracle.db.pdb oracledb.buffer_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.library_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.data_dictionary.hit_ratio: enabled: true oracledb.shared_pool.utilization: enabled: true attributes: - oracle.db.pdb # === Memory Metrics === oracledb.pga_memory: enabled: true attributes: - oracle.db.pdb oracledb.sga.limit: enabled: true oracledb.sga.usage: enabled: true attributes: - oracledb.sga.component.name # === Wait & Database Time Metrics === oracledb.database.wait.utilization: enabled: true attributes: - oracle.db.pdb # === Lock & Deadlock Metrics === oracledb.dml_locks.limit: enabled: true oracledb.dml_locks.usage: enabled: true oracledb.enqueue_locks.limit: enabled: true oracledb.enqueue_locks.usage: enabled: true oracledb.enqueue_resources.limit: enabled: true oracledb.enqueue_resources.usage: enabled: true oracledb.enqueue_deadlocks: enabled: true attributes: - oracle.db.pdb oracledb.exchange_deadlocks: enabled: true attributes: - oracle.db.pdb # === Process & Session Metrics === oracledb.processes.limit: enabled: true oracledb.processes.usage: enabled: true oracledb.sessions.limit: enabled: true oracledb.sessions.usage: enabled: true attributes: - session_type - session_status - oracle.db.pdb oracledb.logons: enabled: true attributes: - oracle.db.pdb # === Transaction Metrics === oracledb.transactions.limit: enabled: true oracledb.transactions.usage: enabled: true oracledb.user_commits: enabled: true attributes: - oracle.db.pdb oracledb.user_rollbacks: enabled: true attributes: - oracle.db.pdb # === Tablespace Metrics === oracledb.tablespace_size.limit: enabled: true attributes: - tablespace_name - oracle.db.pdb oracledb.tablespace_size.usage: enabled: true attributes: - tablespace_name - oracle.db.pdb # === Storage Metrics === oracledb.storage.usage: enabled: true oracledb.storage.utilization: enabled: true oracledb.recycle_bin.limit: enabled: true # === Parallel Operations Metrics === oracledb.queries_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.ddl_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.dml_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_not_downgraded: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_1_to_25_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_25_to_50_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_50_to_75_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_75_to_99_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_to_serial: enabled: true attributes: - oracle.db.pdb # === Redo & Sort Metrics === oracledb.redo_allocation.utilization: enabled: true attributes: - oracle.db.pdb oracledb.sort.ratio: enabled: true attributes: - oracledb.sort.type - oracle.db.pdb # === Response Time Metrics === oracledb.sql_service.response.duration: enabled: true attributes: - oracle.db.pdb # Resource attributes attached to all metrics/logs (all enabled by default) resource_attributes: host.name: enabled: true oracle.db.hosting_type: enabled: true oracle.db.open_mode: enabled: true oracle.db.pdb: enabled: true oracle.db.role: enabled: true oracle.db.version: enabled: true oracledb.instance.name: enabled: true service.instance.id: enabled: true processors: batch: resource/add_event_name: attributes: - key: host.address value: "" action: upsert exporters: otlp/newrelic: endpoint: "" headers: api-key: "" compression: gzip retry_on_failure: enabled: true initial_interval: 5s max_interval: 30s max_elapsed_time: 300s service: pipelines: metrics/oracledb: receivers: [nroracledb] processors: [resource/add_event_name, batch] exporters: [otlp/newrelic] logs/oracledb: receivers: [nroracledb] processors: [resource/add_event_name, batch] exporters: [otlp/newrelic] ``` 3. Update the NRDOT collector configuration to use your `oracle-config.yaml` file. ```bash sudo sed -i 's|OTELCOL_OPTIONS="--config=/etc/nrdot-collector/config.yaml"|OTELCOL_OPTIONS="--config=/etc/nrdot-collector/oracle-config.yaml"|' /etc/nrdot-collector/nrdot-collector.conf ``` 4. Set the following required parameters in the configuration file: | Parameter | Description | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | Enter your Oracle Database hostname. | | `` | Enter your Oracle Database port. | | `` | Enter your database username. | | `` | Enter your database password. | | `` | Enter your Oracle service name. | | `` | Enter the New Relic OTLP endpoint. For more information, refer to [New Relic OTLP endpoints documentation](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/). | | `` | Enter your New Relic API key. | 5. Under the Events section, enable these event types to collect their metrics: | Event | Description | | ------------------------------- | ----------------------------------------------------------------------------------------- | | `db.server.query_sample` | Per-session active query samples capturing current SQL, wait state, and blocking details. | | `db.server.top_query` | Top N SQL statements by CPU or elapsed time, including execution stats and query plans. | | `db.server.session.wait_sample` | Per-session cumulative wait counts and durations from `v$session_event`. | 6. Configure the collection settings for each event type: | Configuration Section | Parameter | Default Value | | ------------------------------- | ------------------------ | ------------- | | `top_query_collection` | `max_query_sample_count` | 1000 | | `top_query_collection` | `top_query_count` | 200 | | `top_query_collection` | `collection_interval` | 60s | | `query_sample_collection` | `max_rows_per_query` | 100 | | `session_wait_event_collection` | `max_rows_per_query` | 100 | > #### 💡 TIP > > For more detailed information about New Relic OTLP endpoint configuration and OpenTelemetry best practices, refer to the [OpenTelemetry OTLP documentation](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/). ##### (Optional) Set up SQL query receiver [#query-receiver] You can configure [SQL query receiver](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/sql-query-receiver/) to collect custom metrics from your Oracle Database. For more information, refer to the [SQL query receiver documentation](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/sql-query-receiver/). ##### Restart NRDOT collector [#restart-collector] After updating your configuration, restart the NRDOT collector: ```bash sudo systemctl restart nrdot-collector.service sudo systemctl status nrdot-collector.service ``` > #### 💡 TIP > > Always restart the NRDOT Collector after making configuration changes so the new settings take effect. ##### (Optional) Multi-receiver configuration [#multi-receiver] The `nrdot-collector` binary supports a multi-receiver configuration within a single `oracle-config.yaml` to monitor multiple Oracle Database instances using unique credentials. **Multi-receiver configuration** The `config.yaml` below demonstrates how to set up multiple receivers for different on-host (multitenant) instances while sharing common processors and exporters. ```yaml receivers: # First CDB configuration (anchor — pdb1/cdb2/pdb2 inherit via merge key) nroracledb/cdb1: &nroracledb-common endpoint: ":" username: "C##" password: "" service: "" collection_interval: 30s events: db.server.query_sample: enabled: true db.server.top_query: enabled: true db.server.session.wait_sample: enabled: true top_query_collection: max_query_sample_count: 1000 top_query_count: 200 collection_interval: 60s allowed_comment_keys: - nr_service_guid query_sample_collection: max_rows_per_query: 100 allowed_comment_keys: - nr_service_guid session_wait_event_collection: max_rows_per_query: 100 # Metrics configuration - organized by category metrics: # === CPU & Performance Metrics === oracledb.cpu_time: enabled: true attributes: - oracle.db.pdb oracledb.database.cpu.utilization: enabled: true attributes: - oracle.db.pdb oracledb.host.cpu.utilization: enabled: true attributes: - oracle.db.pdb # === Execution & Parse Metrics === oracledb.executions: enabled: true attributes: - oracle.db.pdb oracledb.execution.utilization: enabled: true attributes: - oracledb.parse.type - oracle.db.pdb oracledb.parse_calls: enabled: true attributes: - oracle.db.pdb oracledb.parse.rate: enabled: true attributes: - oracledb.parse.result - oracle.db.pdb oracledb.parse.utilization: enabled: true attributes: - oracle.db.pdb oracledb.hard_parses: enabled: true attributes: - oracle.db.pdb # === I/O & Physical Read/Write Metrics === oracledb.logical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_read_io_requests: enabled: true attributes: - oracle.db.pdb oracledb.physical_write_io_requests: enabled: true attributes: - oracle.db.pdb # === New Physical I/O Metrics (detailed) === oracledb.physical_io.cache_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_io.requests: enabled: true attributes: - disk.io.direction - disk.io.block_size - oracle.db.pdb oracledb.physical_io.transferred: enabled: true attributes: - disk.io.direction - disk.io.type - oracle.db.pdb # === Network I/O Metrics === oracledb.sqlnet.io.transferred: enabled: true attributes: - network.io.direction - destination.type - oracle.db.pdb # === Buffer & Cache Metrics === oracledb.consistent_gets: enabled: true attributes: - oracle.db.pdb oracledb.db_block_gets: enabled: true attributes: - oracle.db.pdb oracledb.buffer_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.library_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.data_dictionary.hit_ratio: enabled: true oracledb.shared_pool.utilization: enabled: true attributes: - oracle.db.pdb # === Memory Metrics === oracledb.pga_memory: enabled: true attributes: - oracle.db.pdb oracledb.sga.limit: enabled: true oracledb.sga.usage: enabled: true attributes: - oracledb.sga.component.name # === Wait & Database Time Metrics === oracledb.database.wait.utilization: enabled: true attributes: - oracle.db.pdb # === Lock & Deadlock Metrics === oracledb.dml_locks.limit: enabled: true oracledb.dml_locks.usage: enabled: true oracledb.enqueue_locks.limit: enabled: true oracledb.enqueue_locks.usage: enabled: true oracledb.enqueue_resources.limit: enabled: true oracledb.enqueue_resources.usage: enabled: true oracledb.enqueue_deadlocks: enabled: true attributes: - oracle.db.pdb oracledb.exchange_deadlocks: enabled: true attributes: - oracle.db.pdb # === Process & Session Metrics === oracledb.processes.limit: enabled: true oracledb.processes.usage: enabled: true oracledb.sessions.limit: enabled: true oracledb.sessions.usage: enabled: true attributes: - session_type - session_status - oracle.db.pdb oracledb.logons: enabled: true attributes: - oracle.db.pdb # === Transaction Metrics === oracledb.transactions.limit: enabled: true oracledb.transactions.usage: enabled: true oracledb.user_commits: enabled: true attributes: - oracle.db.pdb oracledb.user_rollbacks: enabled: true attributes: - oracle.db.pdb # === Tablespace Metrics === oracledb.tablespace_size.limit: enabled: true attributes: - tablespace_name - oracle.db.pdb oracledb.tablespace_size.usage: enabled: true attributes: - tablespace_name - oracle.db.pdb # === Storage Metrics === oracledb.storage.usage: enabled: true oracledb.storage.utilization: enabled: true oracledb.recycle_bin.limit: enabled: true # === Parallel Operations Metrics === oracledb.queries_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.ddl_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.dml_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_not_downgraded: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_1_to_25_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_25_to_50_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_50_to_75_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_75_to_99_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_to_serial: enabled: true attributes: - oracle.db.pdb # === Redo & Sort Metrics === oracledb.redo_allocation.utilization: enabled: true attributes: - oracle.db.pdb oracledb.sort.ratio: enabled: true attributes: - oracledb.sort.type - oracle.db.pdb # === Response Time Metrics === oracledb.sql_service.response.duration: enabled: true attributes: - oracle.db.pdb # Resource attributes attached to all metrics/logs resource_attributes: host.name: enabled: true oracle.db.hosting_type: enabled: true oracle.db.open_mode: enabled: true oracle.db.pdb: enabled: true oracle.db.role: enabled: true oracle.db.version: enabled: true oracledb.instance.name: enabled: true service.instance.id: enabled: true # First CDB's PDB configuration nroracledb/pdb1: <<: *nroracledb-common service: "" # Second CDB configuration nroracledb/cdb2: <<: *nroracledb-common endpoint: ":" service: "" # Second CDB's PDB configuration nroracledb/pdb2: <<: *nroracledb-common endpoint: ":" service: "" processors: batch: resource/add_event_name: attributes: - key: host.address value: "" action: upsert exporters: otlp/newrelic: endpoint: "" headers: api-key: "" compression: gzip retry_on_failure: enabled: true initial_interval: 5s max_interval: 30s max_elapsed_time: 300s service: pipelines: metrics/oracledb: receivers: [nroracledb/cdb1, nroracledb/pdb1, nroracledb/cdb2, nroracledb/pdb2] processors: [resource/add_event_name, batch] exporters: [otlp/newrelic] logs/oracledb: receivers: [nroracledb/cdb1, nroracledb/pdb1, nroracledb/cdb2, nroracledb/pdb2] processors: [resource/add_event_name, batch] exporters: [otlp/newrelic] ``` > #### 💡 TIP > > - This configuration allows you to monitor multiple Oracle databases instances simultaneously. Each instance gets its own receiver configuration with unique credentials, while sharing common processors and exporters. Adjust the `collection_interval` and other parameters based on your monitoring requirements. > > - Restart the NRDOT collector after updating the configuration to apply changes. ##### (Optional) Set up APM-database correlation [#moptional-service-id] To correlate your application performance with database operations, you can set up database service identification. This feature allows you to see exactly which applications are generating specific database workloads. For more information, refer to [set up database service identification](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/db-apm) to get APM-database correlation in New Relic. > #### ⚠️ IMPORTANT > > To view database performance data in APM, both entities must be in the same New Relic account. If the entities are in different New Relic accounts, you must have access to both accounts to view the data. ##### (Optional) Configure secret management [#rds-secret-management] The secret management feature allows you to securely manage sensitive information, such as database credentials. This helps to enhance the security of your monitoring setup by avoiding hardcoding sensitive data in configuration files. For more information, refer to [secret management](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/db-apm/#secret-management). ##### Find and use your data [#mfind-use-data] Once your data is being collected, you can access comprehensive Oracle Database monitoring through New Relic UI. To find your Oracle Database entity in New Relic: 1. Go to ** > All Capabilities > Databases**. 2. Set the search criteria as `instrumentation.provider = opentelemetry`. 3. Select your Oracle Database from the list of entities. #### PDB To install the NRDOT Collector for PDB environments, follow these steps: ##### Installation method [#pdb-installation] Select the appropriate installation distribution method for your Linux environment: **For AMD64 architecture** - For Debian/Ubuntu system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_amd64.deb" --output nrdot-collector.deb && sudo dpkg -i nrdot-collector.deb ``` - For RHEL/CentOS/OEL system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_x86_64.rpm" --output nrdot-collector.rpm && sudo rpm -ivh nrdot-collector.rpm ``` **For ARM64 architecture** - For Debian/Ubuntu system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_arm64.deb" --output nrdot-collector.deb && sudo dpkg -i nrdot-collector.deb ``` - For RHEL/CentOS/OEL system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_arm64.rpm" --output nrdot-collector.rpm && sudo rpm -ivh nrdot-collector.rpm ``` ##### Configure database user [#pdb-database-user] Create a monitoring user with the necessary privileges for your PDB Oracle Database instance. 1. Run the following statement as SYS before creating the user or running any grants: ```sql ALTER SESSION SET CONTAINER = ""; ``` 2. Run the following statements as SYS inside your target PDB to create a local monitoring user: ```sql CREATE USER IDENTIFIED BY ""; GRANT CREATE SESSION TO ; ``` ##### Grant monitoring privileges for multitenant database [#database-grants] Run these commands as the SYS user inside your PDB. This gives the monitoring tool the basic access it needs to collect metrics, track events, and find your database instances. ````sql GRANT SELECT ON V_$INSTANCE TO ; GRANT SELECT ON V_$DATABASE TO ; GRANT SELECT ON V_$CONTAINERS TO ; GRANT SELECT ON V_$DATAFILE TO ; GRANT SELECT ON V_$SYSSTAT TO ; GRANT SELECT ON V_$SYSMETRIC TO ; GRANT SELECT ON V_$SESSION TO ; GRANT SELECT ON V_$RESOURCE_LIMIT TO ; GRANT SELECT ON V_$OSSTAT TO ; GRANT SELECT ON V_$SGAINFO TO ; GRANT SELECT ON V_$ROWCACHE TO ; GRANT SELECT ON V_$PARAMETER TO ; GRANT SELECT ON DBA_TABLESPACE_USAGE_METRICS TO ; GRANT SELECT ON DBA_TABLESPACES TO ; GRANT SELECT ON DBA_DATA_FILES TO ; GRANT SELECT ON DBA_FREE_SPACE TO ; GRANT SELECT ON DBA_RECYCLEBIN TO ; GRANT SELECT ON V_$SQL TO ; GRANT SELECT ON V_$SQL_PLAN_STATISTICS_ALL TO ; GRANT SELECT ON V_$LOCK TO ; GRANT SELECT ON V_$SESSION_EVENT TO ; GRANT SELECT ON DBA_PROCEDURES TO ; GRANT SELECT ON DBA_OBJECTS TO ; GRANT SELECT ON V_$PDBS TO ; GRANT SELECT ON CDB_SERVICES TO ; ``` ```` ##### Configure NRDOT Collector [#pdb-configure-collector] Configure the NRDOT Collector with your PDB-specific settings. 1. Create the configuration file. The filename must be `oracle-config.yaml`. ```bash sudo nano /etc/nrdot-collector/oracle-config.yaml ``` 2. Add the configuration content below to the `oracle-config.yaml` file you created in the previous step. **NRDOT host with database configuration** ```yaml extensions: health_check: receivers: otlp: protocols: grpc: http: hostmetrics: collection_interval: 60s scrapers: cpu: metrics: system.cpu.time: enabled: false system.cpu.utilization: enabled: true load: memory: metrics: system.memory.utilization: enabled: true paging: metrics: system.paging.utilization: enabled: false system.paging.faults: enabled: false filesystem: metrics: system.filesystem.utilization: enabled: true disk: metrics: system.disk.merged: enabled: false system.disk.pending_operations: enabled: false system.disk.weighted_io_time: enabled: false network: metrics: system.network.connections: enabled: false # Uncomment to enable process metrics, which can be noisy but valuable. # processes: # process: # metrics: # process.cpu.utilization: # enabled: true # process.cpu.time: # enabled: false filelog: include: - /var/log/alternatives.log - /var/log/cloud-init.log - /var/log/auth.log - /var/log/dpkg.log - /var/log/syslog - /var/log/messages - /var/log/secure - /var/log/yum.log nroracledb: endpoint: ":" username: "" password: "" service: "" collection_interval: 10s events: db.server.query_sample: enabled: true db.server.top_query: enabled: true db.server.session.wait_sample: enabled: true top_query_collection: max_query_sample_count: 1000 top_query_count: 200 collection_interval: 60s allowed_comment_keys: - nr_service_guid query_sample_collection: max_rows_per_query: 100 allowed_comment_keys: - nr_service_guid session_wait_event_collection: max_rows_per_query: 100 # Metrics configuration - organized by category metrics: # === CPU & Performance Metrics === oracledb.cpu_time: enabled: true attributes: - oracle.db.pdb oracledb.database.cpu.utilization: enabled: true attributes: - oracle.db.pdb oracledb.host.cpu.utilization: enabled: true attributes: - oracle.db.pdb # === Execution & Parse Metrics === oracledb.executions: enabled: true attributes: - oracle.db.pdb oracledb.execution.utilization: enabled: true attributes: - oracledb.parse.type - oracle.db.pdb oracledb.parse_calls: enabled: true attributes: - oracle.db.pdb oracledb.parse.rate: enabled: true attributes: - oracledb.parse.result - oracle.db.pdb oracledb.parse.utilization: enabled: true attributes: - oracle.db.pdb oracledb.hard_parses: enabled: true attributes: - oracle.db.pdb # === I/O & Physical Read/Write Metrics === oracledb.logical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_read_io_requests: enabled: true attributes: - oracle.db.pdb oracledb.physical_write_io_requests: enabled: true attributes: - oracle.db.pdb # === New Physical I/O Metrics (detailed) === oracledb.physical_io.cache_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_io.requests: enabled: true attributes: - disk.io.direction - disk.io.block_size - oracle.db.pdb oracledb.physical_io.transferred: enabled: true attributes: - disk.io.direction - disk.io.type - oracle.db.pdb # === Network I/O Metrics === oracledb.sqlnet.io.transferred: enabled: true attributes: - network.io.direction - destination.type - oracle.db.pdb # === Buffer & Cache Metrics === oracledb.consistent_gets: enabled: true attributes: - oracle.db.pdb oracledb.db_block_gets: enabled: true attributes: - oracle.db.pdb oracledb.buffer_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.library_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.data_dictionary.hit_ratio: enabled: true oracledb.shared_pool.utilization: enabled: true attributes: - oracle.db.pdb # === Memory Metrics === oracledb.pga_memory: enabled: true attributes: - oracle.db.pdb oracledb.sga.limit: enabled: true oracledb.sga.usage: enabled: true attributes: - oracledb.sga.component.name # === Wait & Database Time Metrics === oracledb.database.wait.utilization: enabled: true attributes: - oracle.db.pdb # === Lock & Deadlock Metrics === oracledb.dml_locks.limit: enabled: true oracledb.dml_locks.usage: enabled: true oracledb.enqueue_locks.limit: enabled: true oracledb.enqueue_locks.usage: enabled: true oracledb.enqueue_resources.limit: enabled: true oracledb.enqueue_resources.usage: enabled: true oracledb.enqueue_deadlocks: enabled: true attributes: - oracle.db.pdb oracledb.exchange_deadlocks: enabled: true attributes: - oracle.db.pdb # === Process & Session Metrics === oracledb.processes.limit: enabled: true oracledb.processes.usage: enabled: true oracledb.sessions.limit: enabled: true oracledb.sessions.usage: enabled: true attributes: - session_type - session_status - oracle.db.pdb oracledb.logons: enabled: true attributes: - oracle.db.pdb # === Transaction Metrics === oracledb.transactions.limit: enabled: true oracledb.transactions.usage: enabled: true oracledb.user_commits: enabled: true attributes: - oracle.db.pdb oracledb.user_rollbacks: enabled: true attributes: - oracle.db.pdb # === Tablespace Metrics === oracledb.tablespace_size.limit: enabled: true attributes: - tablespace_name - oracle.db.pdb oracledb.tablespace_size.usage: enabled: true attributes: - tablespace_name - oracle.db.pdb # === Storage Metrics === oracledb.storage.usage: enabled: true oracledb.storage.utilization: enabled: true oracledb.recycle_bin.limit: enabled: true # === Parallel Operations Metrics === oracledb.queries_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.ddl_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.dml_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_not_downgraded: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_1_to_25_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_25_to_50_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_50_to_75_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_75_to_99_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_to_serial: enabled: true attributes: - oracle.db.pdb # === Redo & Sort Metrics === oracledb.redo_allocation.utilization: enabled: true attributes: - oracle.db.pdb oracledb.sort.ratio: enabled: true attributes: - oracledb.sort.type - oracle.db.pdb # === Response Time Metrics === oracledb.sql_service.response.duration: enabled: true attributes: - oracle.db.pdb # Resource attributes attached to all metrics/logs (all enabled by default) resource_attributes: host.name: enabled: true oracle.db.hosting_type: enabled: true oracle.db.open_mode: enabled: true oracle.db.pdb: enabled: true oracle.db.role: enabled: true oracle.db.version: enabled: true oracledb.instance.name: enabled: true service.instance.id: enabled: true processors: metricstransform: transforms: - include: system.cpu.utilization action: update operations: - action: aggregate_labels label_set: [ state ] aggregation_type: mean - include: system.paging.operations action: update operations: - action: aggregate_labels label_set: [ direction ] aggregation_type: sum filter/exclude_cpu_utilization: metrics: datapoint: - 'metric.name == "system.cpu.utilization" and attributes["state"] == "interrupt"' - 'metric.name == "system.cpu.utilization" and attributes["state"] == "nice"' - 'metric.name == "system.cpu.utilization" and attributes["state"] == "softirq"' filter/exclude_memory_utilization: metrics: datapoint: - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_unreclaimable"' - 'metric.name == "system.memory.utilization" and attributes["state"] == "inactive"' - 'metric.name == "system.memory.utilization" and attributes["state"] == "cached"' - 'metric.name == "system.memory.utilization" and attributes["state"] == "buffered"' - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_reclaimable"' filter/exclude_memory_usage: metrics: datapoint: - 'metric.name == "system.memory.usage" and attributes["state"] == "slab_unreclaimable"' - 'metric.name == "system.memory.usage" and attributes["state"] == "inactive"' filter/exclude_filesystem_utilization: metrics: datapoint: - 'metric.name == "system.filesystem.utilization" and attributes["type"] == "squashfs"' filter/exclude_filesystem_usage: metrics: datapoint: - 'metric.name == "system.filesystem.usage" and attributes["type"] == "squashfs"' - 'metric.name == "system.filesystem.usage" and attributes["state"] == "reserved"' filter/exclude_filesystem_inodes_usage: metrics: datapoint: - 'metric.name == "system.filesystem.inodes.usage" and attributes["type"] == "squashfs"' - 'metric.name == "system.filesystem.inodes.usage" and attributes["state"] == "reserved"' filter/exclude_system_disk: metrics: datapoint: - 'metric.name == "system.disk.operations" and IsMatch(attributes["device"], "^loop.*") == true' - 'metric.name == "system.disk.merged" and IsMatch(attributes["device"], "^loop.*") == true' - 'metric.name == "system.disk.io" and IsMatch(attributes["device"], "^loop.*") == true' - 'metric.name == "system.disk.io_time" and IsMatch(attributes["device"], "^loop.*") == true' - 'metric.name == "system.disk.operation_time" and IsMatch(attributes["device"], "^loop.*") == true' filter/exclude_system_paging: metrics: datapoint: - 'metric.name == "system.paging.usage" and attributes["state"] == "cached"' - 'metric.name == "system.paging.operations" and attributes["type"] == "cached"' filter/exclude_network: metrics: datapoint: - 'IsMatch(metric.name, "^system.network.*") == true and attributes["device"] == "lo"' attributes/exclude_system_paging: include: match_type: strict metric_names: - system.paging.operations actions: - key: type action: delete transform/clear_metadata: metric_statements: - context: metric statements: - set(metric.description, "") - set(metric.unit, "") transform/host: metric_statements: - context: metric statements: - set(metric.description, "") - set(metric.unit, "") transform: trace_statements: - context: span statements: - truncate_all(span.attributes, 4095) - truncate_all(resource.attributes, 4095) log_statements: - context: log statements: - truncate_all(log.attributes, 4095) - truncate_all(resource.attributes, 4095) memory_limiter: check_interval: 1s limit_mib: ${env:NEW_RELIC_MEMORY_LIMIT_MIB:-100} batch: resource/add_event_name: attributes: - key: host.address value: "" action: upsert resourcedetection: detectors: ["system"] system: hostname_sources: ["os"] resource_attributes: host.id: enabled: true resourcedetection/db_safe: detectors: ["system"] override: false system: hostname_sources: ["os"] resource_attributes: host.id: enabled: true resourcedetection/cloud: detectors: ["gcp", "ec2", "azure"] timeout: 2s override: true resourcedetection/env: detectors: ["env"] timeout: 2s override: true exporters: otlp: endpoint: "" headers: api-key: "" compression: gzip service: pipelines: metrics/host: receivers: [hostmetrics] processors: - memory_limiter - metricstransform - filter/exclude_cpu_utilization - filter/exclude_memory_utilization - filter/exclude_memory_usage - filter/exclude_filesystem_utilization - filter/exclude_filesystem_usage - filter/exclude_filesystem_inodes_usage - filter/exclude_system_disk - filter/exclude_network - attributes/exclude_system_paging - transform/host - resourcedetection - resourcedetection/cloud - resourcedetection/env - batch exporters: [otlp] traces: receivers: [otlp] processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch] exporters: [otlp] metrics: receivers: [otlp] processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch] exporters: [otlp] logs: receivers: [otlp] processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch] exporters: [otlp] metrics/oracledb: receivers: [nroracledb] processors: [resource/add_event_name, batch] exporters: [otlp] logs/oracledb: receivers: [nroracledb] processors: [resource/add_event_name, batch] exporters: [otlp] extensions: [health_check] ``` **Database configuration** ```yaml receivers: nroracledb: endpoint: ":" username: "" password: "" service: "" collection_interval: 10s events: db.server.query_sample: enabled: true db.server.top_query: enabled: true db.server.session.wait_sample: enabled: true top_query_collection: max_query_sample_count: 1000 top_query_count: 200 collection_interval: 60s allowed_comment_keys: - nr_service_guid query_sample_collection: max_rows_per_query: 100 allowed_comment_keys: - nr_service_guid session_wait_event_collection: max_rows_per_query: 100 # Metrics configuration - organized by category metrics: # === CPU & Performance Metrics === oracledb.cpu_time: enabled: true attributes: - oracle.db.pdb oracledb.database.cpu.utilization: enabled: true attributes: - oracle.db.pdb oracledb.host.cpu.utilization: enabled: true attributes: - oracle.db.pdb # === Execution & Parse Metrics === oracledb.executions: enabled: true attributes: - oracle.db.pdb oracledb.execution.utilization: enabled: true attributes: - oracledb.parse.type - oracle.db.pdb oracledb.parse_calls: enabled: true attributes: - oracle.db.pdb oracledb.parse.rate: enabled: true attributes: - oracledb.parse.result - oracle.db.pdb oracledb.parse.utilization: enabled: true attributes: - oracle.db.pdb oracledb.hard_parses: enabled: true attributes: - oracle.db.pdb # === I/O & Physical Read/Write Metrics === oracledb.logical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_read_io_requests: enabled: true attributes: - oracle.db.pdb oracledb.physical_write_io_requests: enabled: true attributes: - oracle.db.pdb # === New Physical I/O Metrics (detailed) === oracledb.physical_io.cache_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_io.requests: enabled: true attributes: - disk.io.direction - disk.io.block_size - oracle.db.pdb oracledb.physical_io.transferred: enabled: true attributes: - disk.io.direction - disk.io.type - oracle.db.pdb # === Network I/O Metrics === oracledb.sqlnet.io.transferred: enabled: true attributes: - network.io.direction - destination.type - oracle.db.pdb # === Buffer & Cache Metrics === oracledb.consistent_gets: enabled: true attributes: - oracle.db.pdb oracledb.db_block_gets: enabled: true attributes: - oracle.db.pdb oracledb.buffer_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.library_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.data_dictionary.hit_ratio: enabled: true oracledb.shared_pool.utilization: enabled: true attributes: - oracle.db.pdb # === Memory Metrics === oracledb.pga_memory: enabled: true attributes: - oracle.db.pdb oracledb.sga.limit: enabled: true oracledb.sga.usage: enabled: true attributes: - oracledb.sga.component.name # === Wait & Database Time Metrics === oracledb.database.wait.utilization: enabled: true attributes: - oracle.db.pdb # === Lock & Deadlock Metrics === oracledb.dml_locks.limit: enabled: true oracledb.dml_locks.usage: enabled: true oracledb.enqueue_locks.limit: enabled: true oracledb.enqueue_locks.usage: enabled: true oracledb.enqueue_resources.limit: enabled: true oracledb.enqueue_resources.usage: enabled: true oracledb.enqueue_deadlocks: enabled: true attributes: - oracle.db.pdb oracledb.exchange_deadlocks: enabled: true attributes: - oracle.db.pdb # === Process & Session Metrics === oracledb.processes.limit: enabled: true oracledb.processes.usage: enabled: true oracledb.sessions.limit: enabled: true oracledb.sessions.usage: enabled: true attributes: - session_type - session_status - oracle.db.pdb oracledb.logons: enabled: true attributes: - oracle.db.pdb # === Transaction Metrics === oracledb.transactions.limit: enabled: true oracledb.transactions.usage: enabled: true oracledb.user_commits: enabled: true attributes: - oracle.db.pdb oracledb.user_rollbacks: enabled: true attributes: - oracle.db.pdb # === Tablespace Metrics === oracledb.tablespace_size.limit: enabled: true attributes: - tablespace_name - oracle.db.pdb oracledb.tablespace_size.usage: enabled: true attributes: - tablespace_name - oracle.db.pdb # === Storage Metrics === oracledb.storage.usage: enabled: true oracledb.storage.utilization: enabled: true oracledb.recycle_bin.limit: enabled: true # === Parallel Operations Metrics === oracledb.queries_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.ddl_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.dml_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_not_downgraded: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_1_to_25_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_25_to_50_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_50_to_75_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_75_to_99_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_to_serial: enabled: true attributes: - oracle.db.pdb # === Redo & Sort Metrics === oracledb.redo_allocation.utilization: enabled: true attributes: - oracle.db.pdb oracledb.sort.ratio: enabled: true attributes: - oracledb.sort.type - oracle.db.pdb # === Response Time Metrics === oracledb.sql_service.response.duration: enabled: true attributes: - oracle.db.pdb # Resource attributes attached to all metrics/logs (all enabled by default) resource_attributes: host.name: enabled: true oracle.db.hosting_type: enabled: true oracle.db.open_mode: enabled: true oracle.db.pdb: enabled: true oracle.db.role: enabled: true oracle.db.version: enabled: true oracledb.instance.name: enabled: true service.instance.id: enabled: true processors: batch: resource/add_event_name: attributes: - key: host.address value: "" action: upsert exporters: otlp/newrelic: endpoint: "" headers: api-key: "" compression: gzip retry_on_failure: enabled: true initial_interval: 5s max_interval: 30s max_elapsed_time: 300s service: pipelines: metrics/oracledb: receivers: [nroracledb] processors: [resource/add_event_name, batch] exporters: [otlp/newrelic] logs/oracledb: receivers: [nroracledb] processors: [resource/add_event_name, batch] exporters: [otlp/newrelic] ``` 3. Update the NRDOT collector configuration to use your `oracle-config.yaml` file. ```bash sudo sed -i 's|OTELCOL_OPTIONS="--config=/etc/nrdot-collector/config.yaml"|OTELCOL_OPTIONS="--config=/etc/nrdot-collector/oracle-config.yaml"|' /etc/nrdot-collector/nrdot-collector.conf ``` 4. Set the following required parameters in the configuration file: | Parameter | Description | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | Enter your Oracle Database hostname. | | `` | Enter your Oracle Database port. | | `` | Enter your database username. | | `` | Enter your database password. | | `` | Enter your Oracle service name. | | `` | Enter the New Relic OTLP endpoint. For more information, refer to [New Relic OTLP endpoints documentation](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/). | | `` | Enter your New Relic API key. | 5. Under the Events section, enable these event types to collect their metrics: | Event | Description | | ------------------------------- | ----------------------------------------------------------------------------------------- | | `db.server.query_sample` | Per-session active query samples capturing current SQL, wait state, and blocking details. | | `db.server.top_query` | Top N SQL statements by CPU or elapsed time, including execution stats and query plans. | | `db.server.session.wait_sample` | Per-session cumulative wait counts and durations from `v$session_event`. | 6. Configure the collection settings for each event type: | Configuration Section | Parameter | Value | | ------------------------------- | ------------------------ | ----- | | `top_query_collection` | `max_query_sample_count` | 1000 | | `top_query_collection` | `top_query_count` | 200 | | `top_query_collection` | `collection_interval` | 60s | | `query_sample_collection` | `max_rows_per_query` | 100 | | `session_wait_event_collection` | `max_rows_per_query` | 100 | > #### 💡 TIP > > For more detailed information about New Relic OTLP endpoint configuration and OpenTelemetry best practices, refer to the [OpenTelemetry OTLP documentation](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/). ##### (Optional) Set up SQL query receiver [#query-receiver] You can configure [SQL query receiver](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/sql-query-receiver/) to collect custom metrics from your Oracle Database. For more information, refer to the [SQL query receiver documentation](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/sql-query-receiver/). ##### Restart NRDOT collector [#pdb-restart-collector] After updating your configuration, restart the NRDOT collector: ```bash sudo systemctl restart nrdot-collector.service sudo systemctl status nrdot-collector.service ``` > #### 💡 TIP > > Always restart the NRDOT collector after making configuration changes to ensure the new settings take effect. ##### (Optional) Multi-receiver configuration [#multi-receiver] The `nrdot-collector` binary supports a multi-receiver configuration within a single `oracle-config.yaml` to monitor multiple Oracle Database instances using unique credentials. **Multi-receiver configuration** The `config.yaml` below demonstrates how to set up multiple receivers for different on-host (multitenant) instances while sharing common processors and exporters. ```yaml receivers: # First CDB configuration (anchor — pdb1/cdb2/pdb2 inherit via merge key) nroracledb/cdb1: &nroracledb-common endpoint: ":" username: "" password: "" service: "" collection_interval: 30s events: db.server.query_sample: enabled: true db.server.top_query: enabled: true db.server.session.wait_sample: enabled: true top_query_collection: max_query_sample_count: 1000 top_query_count: 200 collection_interval: 60s allowed_comment_keys: - nr_service_guid query_sample_collection: max_rows_per_query: 100 allowed_comment_keys: - nr_service_guid session_wait_event_collection: max_rows_per_query: 100 # Metrics configuration - organized by category metrics: # === CPU & Performance Metrics === oracledb.cpu_time: enabled: true attributes: - oracle.db.pdb oracledb.database.cpu.utilization: enabled: true attributes: - oracle.db.pdb oracledb.host.cpu.utilization: enabled: true attributes: - oracle.db.pdb # === Execution & Parse Metrics === oracledb.executions: enabled: true attributes: - oracle.db.pdb oracledb.execution.utilization: enabled: true attributes: - oracledb.parse.type - oracle.db.pdb oracledb.parse_calls: enabled: true attributes: - oracle.db.pdb oracledb.parse.rate: enabled: true attributes: - oracledb.parse.result - oracle.db.pdb oracledb.parse.utilization: enabled: true attributes: - oracle.db.pdb oracledb.hard_parses: enabled: true attributes: - oracle.db.pdb # === I/O & Physical Read/Write Metrics === oracledb.logical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_read_io_requests: enabled: true attributes: - oracle.db.pdb oracledb.physical_write_io_requests: enabled: true attributes: - oracle.db.pdb # === New Physical I/O Metrics (detailed) === oracledb.physical_io.cache_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_io.requests: enabled: true attributes: - disk.io.direction - disk.io.block_size - oracle.db.pdb oracledb.physical_io.transferred: enabled: true attributes: - disk.io.direction - disk.io.type - oracle.db.pdb # === Network I/O Metrics === oracledb.sqlnet.io.transferred: enabled: true attributes: - network.io.direction - destination.type - oracle.db.pdb # === Buffer & Cache Metrics === oracledb.consistent_gets: enabled: true attributes: - oracle.db.pdb oracledb.db_block_gets: enabled: true attributes: - oracle.db.pdb oracledb.buffer_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.library_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.data_dictionary.hit_ratio: enabled: true oracledb.shared_pool.utilization: enabled: true attributes: - oracle.db.pdb # === Memory Metrics === oracledb.pga_memory: enabled: true attributes: - oracle.db.pdb oracledb.sga.limit: enabled: true oracledb.sga.usage: enabled: true attributes: - oracledb.sga.component.name # === Wait & Database Time Metrics === oracledb.database.wait.utilization: enabled: true attributes: - oracle.db.pdb # === Lock & Deadlock Metrics === oracledb.dml_locks.limit: enabled: true oracledb.dml_locks.usage: enabled: true oracledb.enqueue_locks.limit: enabled: true oracledb.enqueue_locks.usage: enabled: true oracledb.enqueue_resources.limit: enabled: true oracledb.enqueue_resources.usage: enabled: true oracledb.enqueue_deadlocks: enabled: true attributes: - oracle.db.pdb oracledb.exchange_deadlocks: enabled: true attributes: - oracle.db.pdb # === Process & Session Metrics === oracledb.processes.limit: enabled: true oracledb.processes.usage: enabled: true oracledb.sessions.limit: enabled: true oracledb.sessions.usage: enabled: true attributes: - session_type - session_status - oracle.db.pdb oracledb.logons: enabled: true attributes: - oracle.db.pdb # === Transaction Metrics === oracledb.transactions.limit: enabled: true oracledb.transactions.usage: enabled: true oracledb.user_commits: enabled: true attributes: - oracle.db.pdb oracledb.user_rollbacks: enabled: true attributes: - oracle.db.pdb # === Tablespace Metrics === oracledb.tablespace_size.limit: enabled: true attributes: - tablespace_name - oracle.db.pdb oracledb.tablespace_size.usage: enabled: true attributes: - tablespace_name - oracle.db.pdb # === Storage Metrics === oracledb.storage.usage: enabled: true oracledb.storage.utilization: enabled: true oracledb.recycle_bin.limit: enabled: true # === Parallel Operations Metrics === oracledb.queries_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.ddl_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.dml_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_not_downgraded: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_1_to_25_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_25_to_50_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_50_to_75_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_75_to_99_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_to_serial: enabled: true attributes: - oracle.db.pdb # === Redo & Sort Metrics === oracledb.redo_allocation.utilization: enabled: true attributes: - oracle.db.pdb oracledb.sort.ratio: enabled: true attributes: - oracledb.sort.type - oracle.db.pdb # === Response Time Metrics === oracledb.sql_service.response.duration: enabled: true attributes: - oracle.db.pdb # Resource attributes attached to all metrics/logs resource_attributes: host.name: enabled: true oracle.db.hosting_type: enabled: true oracle.db.open_mode: enabled: true oracle.db.pdb: enabled: true oracle.db.role: enabled: true oracle.db.version: enabled: true oracledb.instance.name: enabled: true service.instance.id: enabled: true # First CDB's PDB configuration nroracledb/pdb1: <<: *nroracledb-common service: "" # Second CDB configuration nroracledb/cdb2: <<: *nroracledb-common endpoint: ":" service: "" # Second CDB's PDB configuration nroracledb/pdb2: <<: *nroracledb-common endpoint: ":" service: "" processors: batch: resource/add_event_name: attributes: - key: host.address value: "" action: upsert exporters: otlp/newrelic: endpoint: "" headers: api-key: "" compression: gzip retry_on_failure: enabled: true initial_interval: 5s max_interval: 30s max_elapsed_time: 300s service: pipelines: metrics/oracledb: receivers: [nroracledb/cdb1, nroracledb/pdb1, nroracledb/cdb2, nroracledb/pdb2] processors: [resource/add_event_name, batch] exporters: [otlp/newrelic] logs/oracledb: receivers: [nroracledb/cdb1, nroracledb/pdb1, nroracledb/cdb2, nroracledb/pdb2] processors: [resource/add_event_name, batch] exporters: [otlp/newrelic] ``` > #### 💡 TIP > > - This configuration allows you to monitor multiple Oracle databases instances simultaneously. Each instance gets its own receiver configuration with unique credentials, while sharing common processors and exporters. Adjust the `collection_interval` and other parameters based on your monitoring requirements. > > - Restart the NRDOT collector after updating the configuration to apply changes. ##### (Optional) Set up APM-database correlation [#moptional-service-id] To correlate your application performance with database operations, you can set up database service identification. This feature allows you to see exactly which applications are generating specific database workloads. For more information, refer to [set up database service identification](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/db-apm) to get APM-database correlation in New Relic. > #### ⚠️ IMPORTANT > > To view database performance data in APM, both entities must be in the same New Relic account. If the entities are in different New Relic accounts, you must have access to both accounts to view the data. ##### (Optional) Configure secret management [#rds-secret-management] The secret management feature allows you to securely manage sensitive information, such as database credentials. This helps to enhance the security of your monitoring setup by avoiding hardcoding sensitive data in configuration files. For more information, refer to [secret management](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/db-apm/#secret-management). ##### Find and use your data [#mfind-use-data] Once your data is being collected, you can access comprehensive Oracle Database monitoring through New Relic UI. To find your Oracle Database entity in New Relic: 1. Go to ** > All Capabilities > Databases**. 2. Set the search criteria as `instrumentation.provider = opentelemetry`. 3. Select your Oracle Database from the list of entities. ### For RDS To install the NRDOT Collector in RDS environments, follow these steps: #### Installation method [#rds-installation] Select the appropriate installation distribution method for your Linux environment: **For AMD64 architecture** - For Debian/Ubuntu system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_amd64.deb" --output nrdot-collector.deb && sudo dpkg -i nrdot-collector.deb ``` - For RHEL/CentOS/OEL system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_x86_64.rpm" --output nrdot-collector.rpm && sudo rpm -ivh nrdot-collector.rpm ``` **For ARM64 architecture** - For Debian/Ubuntu system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_arm64.deb" --output nrdot-collector.deb && sudo dpkg -i nrdot-collector.deb ``` - For RHEL/CentOS/OEL system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_arm64.rpm" --output nrdot-collector.rpm && sudo rpm -ivh nrdot-collector.rpm ``` #### Configure database user [#rds-database-user] Create a monitoring user with necessary privileges for your RDS Oracle Database. 1. Log in to the root database as an administrator: ```sql CREATE USER IDENTIFIED BY ""; ``` 2. Grant `CONNECT` privileges to newly created user: ```sql GRANT CONNECT TO ; ``` #### Grant monitoring privileges for RDS database [#rds-grant-privileges] Execute the following SQL statements to grant monitoring privileges. Replace `` with your username in uppercase: ```sql EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SYSMETRIC', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$CON_SYSMETRIC', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$CONTAINERS', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SESSION', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SESSION_EVENT', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SYSSTAT', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$CON_SYSSTAT', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$OSSTAT', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SGAINFO', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SQL', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SQLSTATS', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SQL_PLAN_STATISTICS_ALL', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$PARAMETER', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$ROWCACHE', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$RESOURCE_LIMIT', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$LOCK', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$DATABASE', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$INSTANCE', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$DATAFILE', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$PDBS', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_DATA_FILES', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_FREE_SPACE', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_RECYCLEBIN', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_TABLESPACES', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_TABLESPACE_USAGE_METRICS', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_PROCEDURES', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_OBJECTS', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('CDB_TABLESPACE_USAGE_METRICS', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('CDB_TABLESPACES', '', 'SELECT', false); EXEC rdsadmin.rdsadmin_util.grant_sys_object('CDB_SERVICES', '', 'SELECT', false); GRANT CREATE SESSION TO ; ``` #### Configure NRDOT Collector [#rds-configure-collector] 1. Create the configuration file. The filename must be `oracle-config.yaml`. ```bash sudo nano /etc/nrdot-collector/oracle-config.yaml ``` 2. Add the configuration content below to the `oracle-config.yaml` file you created in the previous step. **NRDOT host with database configuration** ```yaml extensions: health_check: receivers: otlp: protocols: grpc: http: hostmetrics: collection_interval: 60s scrapers: cpu: metrics: system.cpu.time: enabled: false system.cpu.utilization: enabled: true load: memory: metrics: system.memory.utilization: enabled: true paging: metrics: system.paging.utilization: enabled: false system.paging.faults: enabled: false filesystem: metrics: system.filesystem.utilization: enabled: true disk: metrics: system.disk.merged: enabled: false system.disk.pending_operations: enabled: false system.disk.weighted_io_time: enabled: false network: metrics: system.network.connections: enabled: false # Uncomment to enable process metrics, which can be noisy but valuable. # processes: # process: # metrics: # process.cpu.utilization: # enabled: true # process.cpu.time: # enabled: false filelog: include: - /var/log/alternatives.log - /var/log/cloud-init.log - /var/log/auth.log - /var/log/dpkg.log - /var/log/syslog - /var/log/messages - /var/log/secure - /var/log/yum.log nroracledb: endpoint: ":" username: "" password: "" service: "" collection_interval: 10s events: db.server.query_sample: enabled: true db.server.top_query: enabled: true db.server.session.wait_sample: enabled: true top_query_collection: max_query_sample_count: 1000 top_query_count: 200 collection_interval: 60s allowed_comment_keys: - nr_service_guid query_sample_collection: max_rows_per_query: 100 allowed_comment_keys: - nr_service_guid session_wait_event_collection: max_rows_per_query: 100 # Metrics configuration - organized by category metrics: # === CPU & Performance Metrics === oracledb.cpu_time: enabled: true attributes: - oracle.db.pdb oracledb.database.cpu.utilization: enabled: true attributes: - oracle.db.pdb oracledb.host.cpu.utilization: enabled: true attributes: - oracle.db.pdb # === Execution & Parse Metrics === oracledb.executions: enabled: true attributes: - oracle.db.pdb oracledb.execution.utilization: enabled: true attributes: - oracledb.parse.type - oracle.db.pdb oracledb.parse_calls: enabled: true attributes: - oracle.db.pdb oracledb.parse.rate: enabled: true attributes: - oracledb.parse.result - oracle.db.pdb oracledb.parse.utilization: enabled: true attributes: - oracle.db.pdb oracledb.hard_parses: enabled: true attributes: - oracle.db.pdb # === I/O & Physical Read/Write Metrics === oracledb.logical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_read_io_requests: enabled: true attributes: - oracle.db.pdb oracledb.physical_write_io_requests: enabled: true attributes: - oracle.db.pdb # === New Physical I/O Metrics (detailed) === oracledb.physical_io.cache_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_io.requests: enabled: true attributes: - disk.io.direction - disk.io.block_size - oracle.db.pdb oracledb.physical_io.transferred: enabled: true attributes: - disk.io.direction - disk.io.type - oracle.db.pdb # === Network I/O Metrics === oracledb.sqlnet.io.transferred: enabled: true attributes: - network.io.direction - destination.type - oracle.db.pdb # === Buffer & Cache Metrics === oracledb.consistent_gets: enabled: true attributes: - oracle.db.pdb oracledb.db_block_gets: enabled: true attributes: - oracle.db.pdb oracledb.buffer_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.library_cache.utilization: enabled: true attributes: - oracle.db.pdb oracledb.data_dictionary.hit_ratio: enabled: true oracledb.shared_pool.utilization: enabled: true attributes: - oracle.db.pdb # === Memory Metrics === oracledb.pga_memory: enabled: true attributes: - oracle.db.pdb oracledb.sga.limit: enabled: true oracledb.sga.usage: enabled: true attributes: - oracledb.sga.component.name # === Wait & Database Time Metrics === oracledb.database.wait.utilization: enabled: true attributes: - oracle.db.pdb # === Lock & Deadlock Metrics === oracledb.dml_locks.limit: enabled: true oracledb.dml_locks.usage: enabled: true oracledb.enqueue_locks.limit: enabled: true oracledb.enqueue_locks.usage: enabled: true oracledb.enqueue_resources.limit: enabled: true oracledb.enqueue_resources.usage: enabled: true oracledb.enqueue_deadlocks: enabled: true attributes: - oracle.db.pdb oracledb.exchange_deadlocks: enabled: true attributes: - oracle.db.pdb # === Process & Session Metrics === oracledb.processes.limit: enabled: true oracledb.processes.usage: enabled: true oracledb.sessions.limit: enabled: true oracledb.sessions.usage: enabled: true attributes: - session_type - session_status - oracle.db.pdb oracledb.logons: enabled: true attributes: - oracle.db.pdb # === Transaction Metrics === oracledb.transactions.limit: enabled: true oracledb.transactions.usage: enabled: true oracledb.user_commits: enabled: true attributes: - oracle.db.pdb oracledb.user_rollbacks: enabled: true attributes: - oracle.db.pdb # === Tablespace Metrics === oracledb.tablespace_size.limit: enabled: true attributes: - tablespace_name - oracle.db.pdb oracledb.tablespace_size.usage: enabled: true attributes: - tablespace_name - oracle.db.pdb # === Storage Metrics === oracledb.storage.usage: enabled: true oracledb.storage.utilization: enabled: true oracledb.recycle_bin.limit: enabled: true # === Parallel Operations Metrics === oracledb.queries_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.ddl_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.dml_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_not_downgraded: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_1_to_25_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_25_to_50_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_50_to_75_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_75_to_99_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_to_serial: enabled: true attributes: - oracle.db.pdb # === Redo & Sort Metrics === oracledb.redo_allocation.utilization: enabled: true attributes: - oracle.db.pdb oracledb.sort.ratio: enabled: true attributes: - oracledb.sort.type - oracle.db.pdb # === Response Time Metrics === oracledb.sql_service.response.duration: enabled: true attributes: - oracle.db.pdb # Resource attributes attached to all metrics/logs (all enabled by default) resource_attributes: host.name: enabled: true oracle.db.hosting_type: enabled: true oracle.db.open_mode: enabled: true oracle.db.pdb: enabled: true oracle.db.role: enabled: true oracle.db.version: enabled: true oracledb.instance.name: enabled: true service.instance.id: enabled: true processors: metricstransform: transforms: - include: system.cpu.utilization action: update operations: - action: aggregate_labels label_set: [ state ] aggregation_type: mean - include: system.paging.operations action: update operations: - action: aggregate_labels label_set: [ direction ] aggregation_type: sum filter/exclude_cpu_utilization: metrics: datapoint: - 'metric.name == "system.cpu.utilization" and attributes["state"] == "interrupt"' - 'metric.name == "system.cpu.utilization" and attributes["state"] == "nice"' - 'metric.name == "system.cpu.utilization" and attributes["state"] == "softirq"' filter/exclude_memory_utilization: metrics: datapoint: - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_unreclaimable"' - 'metric.name == "system.memory.utilization" and attributes["state"] == "inactive"' - 'metric.name == "system.memory.utilization" and attributes["state"] == "cached"' - 'metric.name == "system.memory.utilization" and attributes["state"] == "buffered"' - 'metric.name == "system.memory.utilization" and attributes["state"] == "slab_reclaimable"' filter/exclude_memory_usage: metrics: datapoint: - 'metric.name == "system.memory.usage" and attributes["state"] == "slab_unreclaimable"' - 'metric.name == "system.memory.usage" and attributes["state"] == "inactive"' filter/exclude_filesystem_utilization: metrics: datapoint: - 'metric.name == "system.filesystem.utilization" and attributes["type"] == "squashfs"' filter/exclude_filesystem_usage: metrics: datapoint: - 'metric.name == "system.filesystem.usage" and attributes["type"] == "squashfs"' - 'metric.name == "system.filesystem.usage" and attributes["state"] == "reserved"' filter/exclude_filesystem_inodes_usage: metrics: datapoint: - 'metric.name == "system.filesystem.inodes.usage" and attributes["type"] == "squashfs"' - 'metric.name == "system.filesystem.inodes.usage" and attributes["state"] == "reserved"' filter/exclude_system_disk: metrics: datapoint: - 'metric.name == "system.disk.operations" and IsMatch(attributes["device"], "^loop.*") == true' - 'metric.name == "system.disk.merged" and IsMatch(attributes["device"], "^loop.*") == true' - 'metric.name == "system.disk.io" and IsMatch(attributes["device"], "^loop.*") == true' - 'metric.name == "system.disk.io_time" and IsMatch(attributes["device"], "^loop.*") == true' - 'metric.name == "system.disk.operation_time" and IsMatch(attributes["device"], "^loop.*") == true' filter/exclude_system_paging: metrics: datapoint: - 'metric.name == "system.paging.usage" and attributes["state"] == "cached"' - 'metric.name == "system.paging.operations" and attributes["type"] == "cached"' filter/exclude_network: metrics: datapoint: - 'IsMatch(metric.name, "^system.network.*") == true and attributes["device"] == "lo"' attributes/exclude_system_paging: include: match_type: strict metric_names: - system.paging.operations actions: - key: type action: delete transform/clear_metadata: metric_statements: - context: metric statements: - set(metric.description, "") - set(metric.unit, "") transform/host: metric_statements: - context: metric statements: - set(metric.description, "") - set(metric.unit, "") transform: trace_statements: - context: span statements: - truncate_all(span.attributes, 4095) - truncate_all(resource.attributes, 4095) log_statements: - context: log statements: - truncate_all(log.attributes, 4095) - truncate_all(resource.attributes, 4095) memory_limiter: check_interval: 1s limit_mib: ${env:NEW_RELIC_MEMORY_LIMIT_MIB:-100} batch: resource/add_event_name: attributes: - key: host.address value: "" action: upsert resourcedetection: detectors: ["system"] system: hostname_sources: ["os"] resource_attributes: host.id: enabled: true resourcedetection/db_safe: detectors: ["system"] override: false system: hostname_sources: ["os"] resource_attributes: host.id: enabled: true resourcedetection/cloud: detectors: ["gcp", "ec2", "azure"] timeout: 2s override: true resourcedetection/env: detectors: ["env"] timeout: 2s override: true exporters: otlp: endpoint: "" headers: api-key: "" compression: gzip service: pipelines: metrics/host: receivers: [hostmetrics] processors: - memory_limiter - metricstransform - filter/exclude_cpu_utilization - filter/exclude_memory_utilization - filter/exclude_memory_usage - filter/exclude_filesystem_utilization - filter/exclude_filesystem_usage - filter/exclude_filesystem_inodes_usage - filter/exclude_system_disk - filter/exclude_network - attributes/exclude_system_paging - transform/host - resourcedetection - resourcedetection/cloud - resourcedetection/env - batch exporters: [otlp] traces: receivers: [otlp] processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch] exporters: [otlp] metrics: receivers: [otlp] processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch] exporters: [otlp] logs: receivers: [otlp] processors: [memory_limiter, transform, resourcedetection, resourcedetection/cloud, resourcedetection/env, batch] exporters: [otlp] metrics/oracledb: receivers: [nroracledb] processors: [resource/add_event_name, batch] exporters: [otlp] logs/oracledb: receivers: [nroracledb] processors: [resource/add_event_name, batch] exporters: [otlp] extensions: [health_check] ``` **Database configuration** ```yaml receivers: nroracledb/rds: endpoint: ":" username: "" password: "" service: "" collection_interval: 10s events: db.server.query_sample: enabled: true db.server.top_query: enabled: true db.server.session.wait_sample: enabled: true top_query_collection: max_query_sample_count: 1000 top_query_count: 200 collection_interval: 60s allowed_comment_keys: - nr_service_guid query_sample_collection: max_rows_per_query: 100 allowed_comment_keys: - nr_service_guid session_wait_event_collection: max_rows_per_query: 100 # Metrics configuration - organized by category metrics: # === CPU & Performance Metrics === oracledb.cpu_time: enabled: true attributes: - oracle.db.pdb # === Execution & Parse Metrics === oracledb.executions: enabled: true attributes: - oracle.db.pdb oracledb.parse_calls: enabled: true attributes: - oracle.db.pdb oracledb.hard_parses: enabled: true attributes: - oracle.db.pdb # === I/O & Physical Read/Write Metrics === oracledb.logical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_read_io_requests: enabled: true attributes: - oracle.db.pdb oracledb.physical_write_io_requests: enabled: true attributes: - oracle.db.pdb # === New Physical I/O Metrics (detailed) === oracledb.physical_io.cache_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_io.requests: enabled: true attributes: - disk.io.direction - disk.io.block_size - oracle.db.pdb oracledb.physical_io.transferred: enabled: true attributes: - disk.io.direction - disk.io.type - oracle.db.pdb # === Network I/O Metrics === oracledb.sqlnet.io.transferred: enabled: true attributes: - network.io.direction - destination.type - oracle.db.pdb # === Buffer & Cache Metrics === oracledb.consistent_gets: enabled: true attributes: - oracle.db.pdb oracledb.db_block_gets: enabled: true attributes: - oracle.db.pdb oracledb.data_dictionary.hit_ratio: enabled: true # === Memory Metrics === oracledb.pga_memory: enabled: true attributes: - oracle.db.pdb oracledb.sga.limit: enabled: true oracledb.sga.usage: enabled: true attributes: - oracledb.sga.component.name oracledb.enqueue_deadlocks: enabled: true attributes: - oracle.db.pdb oracledb.exchange_deadlocks: enabled: true attributes: - oracle.db.pdb # KEEP enabled: sessions.usage is sourced from v$session, not v$resource_limit. oracledb.sessions.usage: enabled: true attributes: - session_type - session_status - oracle.db.pdb oracledb.logons: enabled: true attributes: - oracle.db.pdb oracledb.user_commits: enabled: true attributes: - oracle.db.pdb oracledb.user_rollbacks: enabled: true attributes: - oracle.db.pdb # === Tablespace Metrics === oracledb.tablespace_size.limit: enabled: true attributes: - tablespace_name - oracle.db.pdb oracledb.tablespace_size.usage: enabled: true attributes: - tablespace_name - oracle.db.pdb # === Storage Metrics === oracledb.storage.usage: enabled: true oracledb.storage.utilization: enabled: true oracledb.recycle_bin.limit: enabled: true # === Parallel Operations Metrics === oracledb.queries_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.ddl_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.dml_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_not_downgraded: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_1_to_25_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_25_to_50_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_50_to_75_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_75_to_99_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_to_serial: enabled: true attributes: - oracle.db.pdb processors: batch: resource/add_event_name: attributes: - key: host.address value: "" action: upsert exporters: otlp/newrelic: endpoint: "" headers: api-key: "" compression: gzip retry_on_failure: enabled: true initial_interval: 5s max_interval: 30s max_elapsed_time: 300s service: pipelines: metrics/oracledb: receivers: [nroracledb/rds] processors: [resource/add_event_name, batch] exporters: [otlp/newrelic] logs/oracledb: receivers: [nroracledb/rds] processors: [resource/add_event_name, batch] exporters: [otlp/newrelic] ``` 3. Set the following required parameters in the configuration file: | Parameter | Description | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | Enter your Oracle Database hostname. | | `` | Enter your Oracle Database port. | | `` | Enter your database username. | | `` | Enter your database password. | | `` | Enter your PDB service name. | | `` | Enter the New Relic OTLP endpoint. For more information, refer to [New Relic OTLP endpoints documentation](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/). | | `` | Enter your New Relic license key. | 4. Under the Events section, enable these event types to collect their metrics: | Event | Description | | ------------------------------- | ----------------------------------------------------------------------------------------- | | `db.server.query_sample` | Per-session active query samples capturing current SQL, wait state, and blocking details. | | `db.server.top_query` | Top N SQL statements by CPU or elapsed time, including execution stats and query plans. | | `db.server.session.wait_sample` | Per-session cumulative wait counts and durations from `v$session_event`. | 5. Configure the collection settings for each event type: | Configuration Section | Parameter | Value | | ------------------------------- | ------------------------ | ----- | | `top_query_collection` | `max_query_sample_count` | 1000 | | `top_query_collection` | `top_query_count` | 200 | | `top_query_collection` | `collection_interval` | 60s | | `query_sample_collection` | `max_rows_per_query` | 100 | | `session_wait_event_collection` | `max_rows_per_query` | 100 | #### (Optional) Set up SQL query receiver [#query-receiver] You can configure [SQL query receiver](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/sql-query-receiver/) to collect custom metrics from your Oracle Database. For more information, refer to the [SQL query receiver documentation](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/sql-query-receiver/). #### (Optional) Multi-receiver configuration [#rds-multi-receiver] The `nrdot-collector` binary supports a multi-receiver configuration within a single `oracle-config.yaml` to monitor multiple Oracle Database instances using unique credentials. The sample `oracle-config.yaml` below demonstrates how to set up multiple receivers for different RDS instances while sharing common processors and exporters. **Multi-receiver configuration** The `config.yaml` below demonstrates how to set up multiple receivers for different on-host (multitenant) instances while sharing common processors and exporters. ```yaml receivers: # First RDS instance (anchor — rds2 inherits via merge key) nroracledb/rds1: &nroracledb-rds-common endpoint: ":" username: "" password: "" service: "" collection_interval: 10s events: db.server.query_sample: enabled: true db.server.top_query: enabled: true db.server.session.wait_sample: enabled: true top_query_collection: max_query_sample_count: 1000 top_query_count: 200 collection_interval: 60s allowed_comment_keys: - nr_service_guid query_sample_collection: max_rows_per_query: 100 allowed_comment_keys: - nr_service_guid session_wait_event_collection: max_rows_per_query: 100 # Metrics configuration - organized by category metrics: # === CPU & Performance Metrics === oracledb.cpu_time: enabled: true attributes: - oracle.db.pdb # DISABLED on RDS: sourced from v$sysmetric, empty inside a PDB. oracledb.database.cpu.utilization: enabled: false attributes: - oracle.db.pdb # DISABLED on RDS: v$sysmetric empty in PDB. oracledb.host.cpu.utilization: enabled: false attributes: - oracle.db.pdb # === Execution & Parse Metrics === oracledb.executions: enabled: true attributes: - oracle.db.pdb # DISABLED on RDS: v$sysmetric empty in PDB. oracledb.execution.utilization: enabled: false attributes: - oracledb.parse.type - oracle.db.pdb oracledb.parse_calls: enabled: true attributes: - oracle.db.pdb # DISABLED on RDS: v$sysmetric empty in PDB. oracledb.parse.rate: enabled: false attributes: - oracledb.parse.result - oracle.db.pdb # DISABLED on RDS: v$sysmetric empty in PDB. oracledb.parse.utilization: enabled: false attributes: - oracle.db.pdb oracledb.hard_parses: enabled: true attributes: - oracle.db.pdb # === I/O & Physical Read/Write Metrics === oracledb.logical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads: enabled: true attributes: - oracle.db.pdb oracledb.physical_reads_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_writes_direct: enabled: true attributes: - oracle.db.pdb oracledb.physical_read_io_requests: enabled: true attributes: - oracle.db.pdb oracledb.physical_write_io_requests: enabled: true attributes: - oracle.db.pdb # === New Physical I/O Metrics (detailed) === oracledb.physical_io.cache_writes: enabled: true attributes: - oracle.db.pdb oracledb.physical_io.requests: enabled: true attributes: - disk.io.direction - disk.io.block_size - oracle.db.pdb oracledb.physical_io.transferred: enabled: true attributes: - disk.io.direction - disk.io.type - oracle.db.pdb # === Network I/O Metrics === oracledb.sqlnet.io.transferred: enabled: true attributes: - network.io.direction - destination.type - oracle.db.pdb # === Buffer & Cache Metrics === oracledb.consistent_gets: enabled: true attributes: - oracle.db.pdb oracledb.db_block_gets: enabled: true attributes: - oracle.db.pdb # DISABLED on RDS: v$sysmetric empty in PDB. oracledb.buffer_cache.utilization: enabled: false attributes: - oracle.db.pdb # DISABLED on RDS: v$sysmetric empty in PDB. oracledb.library_cache.utilization: enabled: false attributes: - oracle.db.pdb oracledb.data_dictionary.hit_ratio: enabled: true # DISABLED on RDS: v$sysmetric empty in PDB. oracledb.shared_pool.utilization: enabled: false attributes: - oracle.db.pdb # === Memory Metrics === oracledb.pga_memory: enabled: true attributes: - oracle.db.pdb oracledb.sga.limit: enabled: true oracledb.sga.usage: enabled: true attributes: - oracledb.sga.component.name # === Wait & Database Time Metrics === # DISABLED on RDS: v$sysmetric empty in PDB. oracledb.database.wait.utilization: enabled: false attributes: - oracle.db.pdb # === Lock & Deadlock Metrics === # DISABLED on RDS: sourced from v$resource_limit, which returns zero rows. oracledb.dml_locks.limit: enabled: false oracledb.dml_locks.usage: enabled: false oracledb.enqueue_locks.limit: enabled: false oracledb.enqueue_locks.usage: enabled: false oracledb.enqueue_resources.limit: enabled: false oracledb.enqueue_resources.usage: enabled: false oracledb.enqueue_deadlocks: enabled: true attributes: - oracle.db.pdb oracledb.exchange_deadlocks: enabled: true attributes: - oracle.db.pdb # === Process & Session Metrics === # DISABLED on RDS: v$resource_limit empty in PDB. oracledb.processes.limit: enabled: false oracledb.processes.usage: enabled: false oracledb.sessions.limit: enabled: false # KEEP enabled: sessions.usage is sourced from v$session, not v$resource_limit. oracledb.sessions.usage: enabled: true attributes: - session_type - session_status - oracle.db.pdb oracledb.logons: enabled: true attributes: - oracle.db.pdb # === Transaction Metrics === # DISABLED on RDS: v$resource_limit empty in PDB. oracledb.transactions.limit: enabled: false oracledb.transactions.usage: enabled: false oracledb.user_commits: enabled: true attributes: - oracle.db.pdb oracledb.user_rollbacks: enabled: true attributes: - oracle.db.pdb # === Tablespace Metrics === oracledb.tablespace_size.limit: enabled: true attributes: - tablespace_name - oracle.db.pdb oracledb.tablespace_size.usage: enabled: true attributes: - tablespace_name - oracle.db.pdb # === Storage Metrics === oracledb.storage.usage: enabled: true oracledb.storage.utilization: enabled: true oracledb.recycle_bin.limit: enabled: true # === Parallel Operations Metrics === oracledb.queries_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.ddl_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.dml_statements_parallelized: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_not_downgraded: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_1_to_25_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_25_to_50_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_50_to_75_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_75_to_99_pct: enabled: true attributes: - oracle.db.pdb oracledb.parallel_operations_downgraded_to_serial: enabled: true attributes: - oracle.db.pdb # === Redo & Sort Metrics === # DISABLED on RDS: v$sysmetric empty in PDB. oracledb.redo_allocation.utilization: enabled: false attributes: - oracle.db.pdb # DISABLED on RDS: v$sysmetric empty in PDB. oracledb.sort.ratio: enabled: false attributes: - oracledb.sort.type - oracle.db.pdb # === Response Time Metrics === # DISABLED on RDS: v$sysmetric empty in PDB. oracledb.sql_service.response.duration: enabled: false attributes: - oracle.db.pdb # Resource attributes attached to all metrics/logs (all enabled by default) resource_attributes: host.name: enabled: true oracle.db.hosting_type: enabled: true oracle.db.open_mode: enabled: true oracle.db.pdb: enabled: true oracle.db.role: enabled: true oracle.db.version: enabled: true oracledb.instance.name: enabled: true service.instance.id: enabled: true # Second RDS instance (inherits all settings from rds1, overrides endpoint/credentials/service) nroracledb/rds2: <<: *nroracledb-rds-common endpoint: ":" username: "" password: "" service: "" processors: batch: resource/add_event_name: attributes: - key: host.address value: "" action: upsert exporters: otlp/newrelic: endpoint: "" headers: api-key: "" compression: gzip retry_on_failure: enabled: true initial_interval: 5s max_interval: 30s max_elapsed_time: 300s service: pipelines: metrics/oracledb: receivers: [nroracledb/rds1, nroracledb/rds2] processors: [resource/add_event_name, batch] exporters: [otlp/newrelic] logs/oracledb: receivers: [nroracledb/rds1, nroracledb/rds2] processors: [resource/add_event_name, batch] exporters: [otlp/newrelic] ``` > #### 💡 TIP > > - This configuration allows you to monitor multiple Oracle RDS instances simultaneously. Each instance gets its own receiver configuration with unique credentials, while sharing common processors and exporters. Adjust the `collection_interval` and other parameters based on your monitoring requirements. > > - Restart the NRDOT collector after updating the configuration to apply changes. #### (Optional) Set up APM-database correlation [#rds-service-id] To correlate your application performance with database operations, you can set up database service identification. This feature allows you to see exactly which applications are generating specific database workloads. For more information, refer to [set up database service identification](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/db-apm/) to get APM-database correlation in New Relic. > #### ⚠️ IMPORTANT > > To view database performance data in APM, both entities must be in the same New Relic account. If the entities are in different accounts, you must have access to both accounts to view the data. #### (Optional) Configure secret management [#rds-secret-management] The secret management feature allows you to securely manage sensitive information, such as database credentials. This helps to enhance the security of your monitoring setup by avoiding hardcoding sensitive data in configuration files. For more information, refer to [secret management](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/db-apm/#secret-management). #### Find and use your data [#rds-find-use-data] Once your data is being collected, you can access comprehensive Oracle Database monitoring through New Relic UI. To find your Oracle Database entity in New Relic: 1. Go to ** > All Capabilities > Databases**. 2. Set the search criteria as `instrumentation.provider = opentelemetry`. 3. Select your Oracle Database from the list of entities. ### For ADB To install the NRDOT Collector for Oracle Autonomous Database (ADB) environments, follow these steps: #### Installation method [#adb-installation] Select the appropriate installation distribution method for your Linux environment: **For AMD64 architecture** - For Debian/Ubuntu system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_amd64.deb" --output nrdot-collector.deb && sudo dpkg -i nrdot-collector.deb ``` - For RHEL/CentOS/OEL system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_x86_64.rpm" --output nrdot-collector.rpm && sudo rpm -ivh nrdot-collector.rpm ``` **For ARM64 architecture** - For Debian/Ubuntu system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_arm64.deb" --output nrdot-collector.deb && sudo dpkg -i nrdot-collector.deb ``` - For RHEL/CentOS/OEL system, run: ```bash NRDOT_VERSION=$(curl -s https://api.github.com/repos/newrelic/nrdot-collector-releases/releases/latest | grep '"tag_name":' | awk -F'"' '{print $4}') && curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${NRDOT_VERSION}/nrdot-collector_${NRDOT_VERSION}_linux_aarch64.rpm" --output nrdot-collector.rpm && sudo rpm -ivh nrdot-collector.rpm ``` #### Configure database user [#adb-database-user] Create a monitoring user with the necessary privileges for your ADB Oracle Database instance. Run the following statements as SYS inside your target ADB to create a local monitoring user: ````sql CREATE USER IDENTIFIED BY ""; GRANT CREATE SESSION TO ; ``` ```` #### Grant monitoring privileges for Autonomous Database [#adb-database-grants] Run these commands as an admin inside your ADB. This gives the monitoring tool the basic access it needs to collect metrics, track events, and find your database instances. ````sql GRANT SELECT ON SYS.V_$INSTANCE TO ; GRANT SELECT ON SYS.V_$DATABASE TO ; GRANT SELECT ON SYS.V_$CONTAINERS TO ; GRANT SELECT ON SYS.V_$DATAFILE TO ; GRANT SELECT ON SYS.V_$PDBS TO ; GRANT SELECT ON SYS.V_$SYSSTAT TO ; GRANT SELECT ON SYS.V_$SYSMETRIC TO ; GRANT SELECT ON SYS.V_$SESSION TO ; GRANT SELECT ON SYS.V_$RESOURCE_LIMIT TO ; GRANT SELECT ON SYS.V_$OSSTAT TO ; GRANT SELECT ON SYS.V_$SGAINFO TO ; GRANT SELECT ON SYS.V_$ROWCACHE TO ; GRANT SELECT ON SYS.V_$PARAMETER TO ; GRANT SELECT ON SYS.DBA_TABLESPACE_USAGE_METRICS TO ; GRANT SELECT ON SYS.DBA_TABLESPACES TO ; GRANT SELECT ON SYS.DBA_DATA_FILES TO ; GRANT SELECT ON SYS.DBA_FREE_SPACE TO ; GRANT SELECT ON SYS.DBA_RECYCLEBIN TO ; GRANT SELECT ON SYS.V_$SQL TO ; GRANT SELECT ON SYS.V_$SQL_PLAN_STATISTICS_ALL TO ; GRANT SELECT ON SYS.V_$LOCK TO ; GRANT SELECT ON SYS.V_$SESSION_EVENT TO ; GRANT SELECT ON SYS.DBA_PROCEDURES TO ; GRANT SELECT ON SYS.DBA_OBJECTS TO ; ``` ```` #### Configure NRDOT Collector [#adb-configure-collector] Configure the NRDOT Collector with your ADB-specific settings. Create a configuration file (e.g., `adb-config.yaml`) with the following content: ````yaml receivers: nroracledb/adb: datasource: "oracle://:@:/?ssl=true&ssl%20verify=true" collection_interval: 10s events: db.server.query_sample: enabled: true db.server.top_query: enabled: true db.server.session.wait_sample: enabled: true top_query_collection: max_query_sample_count: 1000 top_query_count: 200 collection_interval: 60s allowed_comment_keys: - nr_service_guid query_sample_collection: max_rows_per_query: 100 allowed_comment_keys: - nr_service_guid session_wait_event_collection: max_rows_per_query: 100 metrics: oracledb.cpu_time: enabled: true oracledb.executions: enabled: true oracledb.parse_calls: enabled: true oracledb.hard_parses: enabled: true oracledb.logical_reads: enabled: true oracledb.physical_reads: enabled: true oracledb.physical_reads_direct: enabled: true oracledb.physical_writes: enabled: true oracledb.physical_writes_direct: enabled: true oracledb.physical_read_io_requests: enabled: true oracledb.physical_write_io_requests: enabled: true oracledb.physical_io.cache_writes: enabled: true oracledb.physical_io.requests: enabled: true attributes: - disk.io.direction - disk.io.block_size oracledb.physical_io.transferred: enabled: true attributes: - disk.io.direction - disk.io.type oracledb.sqlnet.io.transferred: enabled: true attributes: - network.io.direction - destination.type oracledb.consistent_gets: enabled: true oracledb.db_block_gets: enabled: true oracledb.data_dictionary.hit_ratio: enabled: true oracledb.pga_memory: enabled: true oracledb.enqueue_deadlocks: enabled: true oracledb.exchange_deadlocks: enabled: true oracledb.sessions.usage: enabled: true attributes: - session_type - session_status oracledb.logons: enabled: true oracledb.user_commits: enabled: true oracledb.user_rollbacks: enabled: true oracledb.tablespace_size.limit: enabled: true attributes: - tablespace_name oracledb.tablespace_size.usage: enabled: true attributes: - tablespace_name oracledb.storage.usage: enabled: true oracledb.storage.utilization: enabled: true oracledb.recycle_bin.limit: enabled: true oracledb.queries_parallelized: enabled: true oracledb.ddl_statements_parallelized: enabled: true oracledb.dml_statements_parallelized: enabled: true oracledb.parallel_operations_not_downgraded: enabled: true oracledb.parallel_operations_downgraded_1_to_25_pct: enabled: true oracledb.parallel_operations_downgraded_25_to_50_pct: enabled: true oracledb.parallel_operations_downgraded_50_to_75_pct: enabled: true oracledb.parallel_operations_downgraded_75_to_99_pct: enabled: true oracledb.parallel_operations_downgraded_to_serial: enabled: true processors: batch: resource/add_event_name: attributes: - key: host.address value: "" action: upsert exporters: otlphttp/newrelic: endpoint: "" headers: api-key: "" compression: gzip retry_on_failure: enabled: true initial_interval: 5s max_interval: 30s max_elapsed_time: 300s service: telemetry: metrics: level: none pipelines: metrics/oracledb: receivers: [nroracledb/adb] processors: [resource/add_event_name, batch] exporters: [otlphttp/newrelic] logs/oracledb: receivers: [nroracledb/adb] processors: [resource/add_event_name, batch] exporters: [otlphttp/newrelic] ``` **Note**: The following metrics are **not supported in ADB**: - oracledb.database.cpu.utilization - oracledb.database.wait.utilization - oracledb.host.cpu.utilization - oracledb.execution.utilization - oracledb.parse.rate - oracledb.parse.utilization - oracledb.sort.ratio - oracledb.sql_service.response.duration - oracledb.buffer_cache.utilization - oracledb.library_cache.utilization - oracledb.shared_pool.utilization - oracledb.redo_allocation.utilization - oracledb.processes.limit - oracledb.processes.usage - oracledb.sessions.limit - oracledb.transactions.limit - oracledb.transactions.usage - oracledb.dml_locks.limit - oracledb.dml_locks.usage - oracledb.enqueue_locks.limit - oracledb.enqueue_locks.usage - oracledb.enqueue_resources.limit - oracledb.enqueue_resources.usage ```` #### (Optional) Set up SQL query receiver [#query-receiver] You can configure [SQL Query Receiver](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/sql-query-receiver/) to collect custom metrics from your Oracle Database. For more information, refer to the [SQL Query Receiver documentation](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/sql-query-receiver/). #### Restart NRDOT collector [#adb-restart-collector] After configuring the collector, restart the NRDOT collector service to apply the changes: ```bash sudo systemctl restart nrdot-collector ``` To verify that the collector is running properly, check the service status: ```bash sudo systemctl status nrdot-collector ``` > #### 💡 TIP > > Always restart the NRDOT collector after making configuration changes to ensure the new settings take effect. #### (Optional) Multi-receiver configuration [#adb-multi-receiver] If you want to monitor multiple Oracle ADB instances from the same collector, you can configure multiple receivers in your configuration file by adding additional receiver blocks with different names and connection details. #### (Optional) Set up APM-database correlation [#adb-optional-service-id] To correlate your application performance with database operations, you can set up database service identification. This feature allows you to see exactly which applications are generating specific database workloads. For more information, refer to [set up database service identification](https://docs.newrelic.com/docs/opentelemetry/database/capabilities/db-apm/) to get APM-database correlation in New Relic. > #### ⚠️ IMPORTANT > > To view database performance data in APM, both entities must be in the same New Relic account. If the entities are in different New Relic accounts, you must have access to both accounts to view the data. #### (Optional) Configure secret management [#adb-secret-management] You can configure the NRDOT Collector to retrieve sensitive information, such as passwords, from secret management systems instead of storing them in plain text in configuration files. For more information, refer to [secret management](https://docs.newrelic.com/docs/opentelemetry/database/secret-management/). #### Find and use your data [#adb-find-use-data] After you set up the Oracle ADB integration, you can start monitoring and analyzing your database performance in New Relic: 1. Go to **[one.newrelic.com](https://one.newrelic.com) > All Entities**. 2. Filter by **Oracle** to find your database entities. 3. Select your Oracle ADB entity to view dashboards, metrics, and logs. For more information about monitoring Oracle databases, refer to our [database monitoring documentation](https://docs.newrelic.com/docs/database-monitoring/oracle-monitoring/). /\* ## Troubleshooting \[#troubleshooting] \### Common issues \*\*Connection refused errors:\*\* \- Verify Oracle Database is running and accessible \- Check firewall settings and network connectivity \- Confirm connection details (host, port, service name) \*\*Authentication failures:\*\* \- Verify username and password are correct \- Ensure user has required privileges granted \- For multitenant databases, confirm \`C##\` prefix is used \*\*No data in New Relic:\*\* \- Verify New Relic API key is valid and has ingest permissions \- Check OTLP endpoint URL matches your New Relic region \- Review collector logs for error messages \*\*Query monitoring not working:\*\* \- Ensure \`enable_query_monitoring: true\` in configuration \- Verify user has SELECT privileges on \`gv\_$sqlarea\` or \`v\_$sqlarea\` views \- Check query monitoring thresholds are appropriate for your workload \*/ ## NRDOT collector supported commands [#commands] This section provides a list of common commands for managing the NRDOT Collector service on your system. **NRDOT Collector commands** - To validate installation status: - For Debian/Ubuntu-based distributions: ```bash dpkg -l | grep nrdot-collector ``` - For RHEL/CentOS-based distributions: ```bash rpm -q nrdot-collector || ls /etc/nrdot-collector ``` - To restart NRDOT Collector: ```bash sudo systemctl restart nrdot-collector.service ``` - To check NRDOT Collector status: ```bash sudo systemctl status nrdot-collector.service ``` - To view NRDOT Collector logs: ```bash sudo journalctl -u nrdot-collector -n 50 --no-pager ``` - To delete NRDOT Collector service: - For Debian/Ubuntu-based distributions: ```bash sudo apt purge nrdot-collector ``` - For RHEL/CentOS-based distributions: ```bash sudo yum erase nrdot-collector ``` - To clean up configuration files: ```bash # Clean up configuration and reload systemd sudo rm -rf /etc/nrdot-collector/ sudo systemctl daemon-reload ``` ## Available metrics [#otel-metrics] The following metrics are available for Oracle Database monitoring with NRDOT. Enable the relevant scrapers in your configuration to collect them. **Core metrics** | Metric name | Description | | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `oracledb.cpu_time` | Cumulative CPU time, in seconds | | `oracledb.exchange_deadlocks` | Number of times that a process detected a potential deadlock when exchanging two buffers and raised an internal, restartable error | | `oracledb.executions` | Total number of calls (user and recursive) that executed SQL statements | | `oracledb.hard_parses` | Number of hard parses | | `oracledb.logical_reads` | Number of logical reads | | `oracledb.parse_calls` | Total number of parse calls | | `oracledb.pga_memory` | Session PGA (Program Global Area) memory | | `oracledb.physical_reads` | Number of physical reads | | `oracledb.sessions.usage` | Count of active sessions | | `oracledb.tablespace_size.limit` | Maximum size of tablespace in bytes, -1 if unlimited | | `oracledb.tablespace_size.usage` | Used tablespace in bytes | | `oracledb.user_commits` | Number of user commits. When a user commits a transaction, the redo generated that reflects the changes made to database blocks must be written to disk | | `oracledb.user_rollbacks` | Number of times users manually issue the ROLLBACK statement or an error occurs during a user's transactions | | `oracledb.consistent_gets` | Number of times a consistent read was requested for a block from the buffer cache | | `oracledb.data_dictionary.hit_ratio` | Data dictionary cache hit ratio from v$rowcache | | `oracledb.db_block_gets` | Number of times a current block was requested from the buffer cache | | `oracledb.ddl_statements_parallelized` | Number of DDL statements that were executed in parallel | | `oracledb.dml_statements_parallelized` | Number of DML statements that were executed in parallel | | `oracledb.logons` | Number of logon operations | | `oracledb.parallel_operations_downgraded_1_to_25_pct` | Number of times parallel execution was requested and the degree of parallelism was reduced down to 1-25% because of insufficient parallel execution servers | | `oracledb.parallel_operations_downgraded_25_to_50_pct` | Number of times parallel execution was requested and the degree of parallelism was reduced down to 25-50% because of insufficient parallel execution servers | | `oracledb.parallel_operations_downgraded_50_to_75_pct` | Number of times parallel execution was requested and the degree of parallelism was reduced down to 50-75% because of insufficient parallel execution servers | | `oracledb.parallel_operations_downgraded_75_to_99_pct` | Number of times parallel execution was requested and the degree of parallelism was reduced down to 75-99% because of insufficient parallel execution servers | | `oracledb.parallel_operations_downgraded_to_serial` | Number of times parallel execution was requested but execution was serial because of insufficient parallel execution servers | | `oracledb.parallel_operations_not_downgraded` | Number of times parallel execution was executed at the requested degree of parallelism | | `oracledb.physical_io.cache_writes` | Number of physical writes from the buffer cache to disk by DBWR. Sourced from v$sysstat name physical writes from cache | | `oracledb.physical_io.requests` | Number of physical I/O requests issued to storage. Sourced from v$sysstat names physical read/write total IO requests and physical read/write total multi block requests | | `oracledb.physical_io.transferred` | Total physical I/O bytes transferred between Oracle and storage. Sums across all data files. Sourced from v$sysstat names physical read/write bytes and physical read/write total bytes | | `oracledb.physical_read_io_requests` | Number of read requests for application activity | | `oracledb.physical_reads_direct` | Number of reads directly from disk, bypassing the buffer cache | | `oracledb.physical_write_io_requests` | Number of write requests for application activity | | `oracledb.physical_writes` | Number of physical writes | | `oracledb.physical_writes_direct` | Number of writes directly to disk, bypassing the buffer cache | | `oracledb.queries_parallelized` | Number of SELECT statements executed in parallel | | `oracledb.recycle_bin.limit` | Total size of the recycle bin | | `oracledb.sga.limit` | Maximum size of the System Global Area (SGA) in bytes as reported by `V$SGAINFO` (Maximum SGA Size) | | `oracledb.sga.usage` | Size in bytes of each component of the System Global Area (SGA) as reported by `V$SGAINFO` | | `oracledb.sqlnet.io.transferred` | Bytes transferred via SQLNet between Oracle and clients/dblinks. Sourced from `v$sysstat` names bytes `received/sent` via SQLNet from/to client/dblink | | `oracledb.storage.usage` | Used database storage size from dba_data_files and dba_free_space | | `oracledb.storage.utilization` | Fraction of allocated database storage that is used | | `oracledb.dml_locks.limit` | Maximum limit of active DML (Data Manipulation Language) locks, -1 if unlimited. **Not supported in RDS.** | | `oracledb.dml_locks.usage` | Current count of active DML (Data Manipulation Language) locks. **Not supported in RDS.** | | `oracledb.enqueue_deadlocks` | Total number of deadlocks between table or row locks in different sessions | | `oracledb.enqueue_locks.limit` | Maximum limit of active enqueue locks, -1 if unlimited. **Not supported in RDS.** | | `oracledb.enqueue_locks.usage` | Current count of active enqueue locks. **Not supported in RDS.** | | `oracledb.enqueue_resources.limit` | Maximum limit of active enqueue resources, -1 if unlimited. **Not supported in RDS.** | | `oracledb.enqueue_resources.usage` | Current count of active enqueue resources. **Not supported in RDS.** | | `oracledb.processes.limit` | Maximum limit of active processes, -1 if unlimited. **Not supported in RDS.** | | `oracledb.processes.usage` | Current count of active processes. **Not supported in RDS.** | | `oracledb.sessions.limit` | Maximum limit of active sessions, -1 if unlimited. **Not supported in RDS.** | | `oracledb.shared_pool.utilization` | Fraction of the shared pool that is currently free, as computed by Oracle `V$SYSMETRIC` `(% Free/Total)`. Low values indicate shared pool pressure. **Not supported in RDS.** | | `oracledb.sort.ratio` | Fraction of sorts performed in memory vs disk, as computed by Oracle `V$SYSMETRIC` (% MemSort/(MemSort + DiskSort)). Low values indicate PGA memory pressure. **Not supported in RDS.** | | `oracledb.sql_service.response.duration` | Average SQL service response time in seconds, converted from centiseconds as reported by Oracle `V$SYSMETRIC` `(CentiSeconds Per Call)`. **Not supported in RDS.** | | `oracledb.redo_allocation.utilization` | Fraction of redo allocations that succeeded without space contention, as computed by Oracle `V$SYSMETRIC` `(% (#Redo - RedoSpaceReq)/#Redo)`. **Not supported in RDS.** | | `oracledb.parse.rate` | Rate of parse operations per second broken down by result, as computed by Oracle `V$SYSMETRIC` (e.g., Parse Failure Count Per Sec). **Not supported in RDS.** | | `oracledb.parse.utilization` | Fraction of parse calls that were soft parses, as computed by Oracle `V$SYSMETRIC` (% SoftParses/TotalParses). High values indicate good cursor reuse. **Not supported in RDS.** | | `oracledb.execution.utilization` | Fraction of executions that did not require a parse, as computed by Oracle `V$SYSMETRIC (% (ExecWOParse/TotalExec))`. High values indicate good cursor reuse. **Not supported in RDS.** | | `oracledb.host.cpu.utilization` | Fraction of host CPU time in use, as computed by Oracle `V$SYSMETRIC` `(% Busy/(Idle+Busy))`. **Not supported in RDS.** | | `oracledb.library_cache.utilization` | Fraction of library cache pin requests that found the object already cached, as computed by Oracle `V$SYSMETRIC` `(% Hits/Pins)`. **Not supported in RDS.** | | `oracledb.database.cpu.utilization` | Fraction of total database time spent on CPU, as computed by Oracle `V$SYSMETRIC` `(% Cpu/DB_Time)`. **Not supported in RDS.** | | `oracledb.database.wait.utilization` | Fraction of total database time spent waiting on I/O, locks, or latches, as computed by Oracle `V$SYSMETRIC` `(% Wait/DB_Time)`. **Not supported in RDS.** | | `oracledb.transactions.limit` | Maximum limit of active transactions, -1 if unlimited. **Not supported in RDS.** | | `oracledb.transactions.usage` | Current count of active transactions. **Not supported in RDS.** | | `oracledb.buffer_cache.utilization` | Fraction of logical reads served from the buffer cache without physical I/O, as computed by Oracle `V$SYSMETRIC` `(% (LogRead - PhyRead)/LogRead)`. **Not supported in RDS.** | **db.server.query_sample** Per-session active query samples. Captures the current execution state of active Oracle sessions at collection time. | Attribute name | Description | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `db.query.text` | The text of the database query being executed | | `db.system.name` | The database management system (DBMS) product as identified by the client instrumentation | | `user.name` | Database user name under which a session is connected to | | `db.namespace` | The database name | | `oracle.db.service` | The Oracle service name associated with the database connection | | `client.address` | Hostname or address of the client | | `client.port` | TCP port used by the client | | `network.peer.address` | IP address of the peer client | | `network.peer.port` | TCP port used by the peer client | | `oracledb.plan_hash_value` | Binary hash value calculated on the query execution plan, reported in HEX format | | `oracledb.sql_id` | The SQL ID of the query | | `oracledb.child_number` | The child number of the query | | `oracledb.child_address` | Address of the child cursor | | `oracledb.sid` | ID of the Oracle Server session | | `oracledb.serial` | Serial number associated with a session | | `oracledb.process` | The operating system process ID (PID) associated with a session | | `oracledb.schemaname` | Oracle schema under which SQL statements are being executed | | `oracledb.program` | Name of the client program or tool that initiated the Oracle database session | | `oracledb.module` | Logical module name of the client application that initiated a query or session | | `oracledb.status` | Execution state or result of a database query or session | | `oracledb.state` | Current state of the query or the session executing it | | `oracledb.wait_class` | The category of wait events a query or session is currently experiencing in Oracle Database | | `oracledb.event` | The specific wait event that a query or session is currently experiencing | | `oracledb.query.wait_time` | The wait time in seconds. Returns 0 if the session is not currently waiting | | `oracledb.procedure_id` | The identifier of the stored procedure or function being executed by the query | | `oracledb.procedure_name` | Name of the database object that a query is accessing | | `oracledb.procedure_type` | Type of the database object that a query is accessing | | `oracledb.osuser` | Name of the operating system user that initiated or is running the Oracle database session | | `oracledb.duration_sec` | Total time taken by a database query to execute | | `db.query.comment_tags` | Filtered SQL query comments extracted from leading block comments. Contains comma-separated key=value pairs for correlation with APM traces | | `db.query.comment_tags.nr_service_guid` | New Relic service GUID extracted from db.query.comment_tags. Used for correlation with APM traces | | `oracledb.query.started` | The timestamp when the SQL statement started execution, in ISO 8601 format (UTC) | | `oracledb.session.started` | The timestamp when the session logged on, in ISO 8601 format (UTC) | | `oracledb.session.duration` | The total time in seconds that the session has been connected | | `oracledb.blocking.blocker.sid` | The session ID (SID) of the immediate blocker of this session. Empty when not blocked | | `oracledb.blocking.blocker.root_sid` | The session ID (SID) of the root/head blocker at the top of the blocking chain | | `oracledb.blocking.blocker.state` | The status of the blocking session relationship (e.g. VALID, NOT IN WAIT, GLOBAL, NO HOLDER, UNKNOWN) | | `oracledb.blocking.start_time` | Estimated UTC timestamp of when the blocking wait began. RFC3339 format | | `oracledb.blocking.wait_duration` | The number of seconds this session has been waiting for the current wait event | | `oracledb.blocking.lock.mode` | The lock mode being requested by the blocked session (e.g., ROW SHARE, ROW EXCLUSIVE, SHARE, EXCLUSIVE) | | `oracledb.blocking.lock.type` | The type of enqueue lock the session is waiting on (e.g., TX for row lock, TM for table lock) | | `oracledb.blocking.object.owner` | The owner (schema) of the database object the session is waiting to lock | | `oracledb.blocking.object.name` | The name of the database object the session is waiting to lock | | `db.query.text.normalized.hash` | MD5 hash of normalized SQL query | **db.server.session.wait_sample** Per-session wait event statistics. Captures wait duration counts and durations per session. | Attribute name | Description | | ------------------------ | ------------------------------------------------------------------------------------------- | | `oracledb.sid` | ID of the Oracle Server session | | `oracledb.serial` | Serial number associated with a session | | `oracledb.event` | The specific wait event that a query or session is currently experiencing | | `oracledb.wait_class` | The category of wait events a query or session is currently experiencing in Oracle Database | | `oracledb.wait.count` | Total number of waits for the wait event across all sessions | | `oracledb.wait.duration` | Total time waited in seconds for the wait event | **db.server.top_query** Collection of event metrics for top N queries, filtered based on the highest elapsed time consumed in the collection interval. | Attribute name | Description | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `db.system.name` | The database management system (DBMS) product as identified by the client instrumentation | | `db.server.name` | The name of the server hosting the database | | `db.namespace` | The database name | | `oracle.db.service` | The Oracle service name associated with the database connection | | `db.query.text` | The text of the database query being executed | | `oracledb.query_plan` | The query execution plan used by the SQL Server | | `oracledb.sql_id` | The SQL ID of the query | | `oracledb.child_number` | The child number of the query | | `oracledb.child_address` | Address of the child cursor | | `oracledb.application_wait_time` | Total time (in seconds) a query spent waiting on the application before it could proceed | | `oracledb.buffer_gets` | Number of logical reads (buffer cache accesses) performed by a query | | `oracledb.cluster_wait_time` | Total time (in seconds) that a query waited due to Oracle RAC coordination | | `oracledb.command_type` | Command type of the query | | `oracledb.concurrency_wait_time` | Total time (in seconds) a query spent waiting on concurrency-related events | | `oracledb.cpu_time` | Total time (in seconds) that the CPU spent actively processing a query, excluding wait time | | `oracledb.direct_reads` | Number of direct path reads performed by a query — data blocks read directly from disk into session memory | | `oracledb.direct_writes` | Number of direct path write operations, where data is written directly to disk from user memory | | `oracledb.disk_reads` | Number of physical reads a query performs — data blocks read from disk | | `oracledb.elapsed_time` | Total time (in seconds) taken by a query from start to finish, including CPU time and all types of waits | | `oracledb.executions` | Number of times a specific SQL query has been executed | | `oracledb.physical_read_bytes` | Total number of bytes read from disk by a query | | `oracledb.physical_read_requests` | Number of physical I/O read operations performed by a query | | `oracledb.physical_write_bytes` | Total number of bytes written to disk by a query | | `oracledb.physical_write_requests` | Number of times a query requested to write data to disk | | `oracledb.rows_processed` | Total number of rows that a query has read, returned, or affected during execution | | `oracledb.user_io_wait_time` | Total time (in seconds) a query spent waiting for user I/O operations | | `oracledb.procedure_execution_count` | Number of times the stored procedure has been executed (reporting delta, best effort) | | `oracledb.procedure_id` | The identifier of the stored procedure or function being executed by the query | | `oracledb.procedure_name` | Name of the database object that a query is accessing | | `oracledb.procedure_type` | Type of the database object that a query is accessing | | `db.query.comment_tags` | Filtered SQL query comments extracted from leading block comments. Contains comma-separated key=value pairs for correlation with APM traces | | `db.query.comment_tags.nr_service_guid` | New Relic service GUID extracted from db.query.comment_tags. Used for correlation with APM traces | | `oracledb.plan_hash_value` | Binary hash value calculated on the query execution plan, reported in HEX format | | `oracledb.plan.first_load` | Time at which the plan was first loaded into the library cache, in server's local timezone. Format: YYYY-MM-DD/HH:MM:SS | | `oracledb.plan.last_load` | Plan load time in server's local timezone. Format: YYYY-MM-DD/HH:MM:SS | | `db.query.text.normalized.hash` | MD5 hash of normalized SQL query following New Relic Java agent normalization logic. Used for correlation with APM slow query traces | ## Troubleshooting [#troubleshoot] If you encounter issues during setup, use this troubleshooting guide to diagnose and resolve common problems. **Test network connectivity** Run the following command to verify the Oracle Database port is reachable from this host. ````bash (timeout 3 bash -c '/' && echo "PORT OPEN - Network connection successful!") || echo "CONNECTION FAILED - Port closed or firewall blocking" ``` **Expected output:** `PORT OPEN - Network connection successful!` ```` **Test OTLP endpoint connectivity** Run the following command to verify your host can reach the selected New Relic OTLP endpoint. ````bash ENDPOINT="" HOST=$(echo "$ENDPOINT" | sed 's|https://||' | cut -d: -f1) PORT=$(echo "$ENDPOINT" | awk -F: '{print $NF}') (timeout 2 bash -c "