Install & configure NRDOT Collector for on-host CDB monitoring

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.

Get comprehensive insights into your Oracle Container Database (CDB) performance with database monitoring, query analysis, and system health metrics using the New Relic Distribution of OpenTelemetry (NRDOT) collector. All Pluggable Databases (PDBs) under the configured CDB are monitored.

Guided installation

To install through the New Relic UI instead, go to one.newrelic.com > Integrations & Agents > Oracle (OpenTelemetry) . This page covers the CLI install path only.

Prerequisites

Before you begin, ensure you have the following:

Valid New Relic license key
Supported architecture: Linux with AMD64 and ARM64
Network connectivity to New Relic OTLP endpoint
Oracle Database 19c or later

Enroll to preview

This integration is available as part of the New Relic public preview program. Contact your Organization Manager to opt in from the Previews & Trials page.

Install NRDOT Collector

Select the appropriate installation distribution method for your Linux environment:

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

Create a monitoring user with necessary privileges for your multitenant Oracle Database. This requires creating a common user with the C## prefix.

To set your current active container context to CDB$ROOT, execute the following statement as a SYS user:
```
ALTER SESSION SET CONTAINER = CDB$ROOT;
```
For multitenant databases:
1. Log in to the root database as an administrator.
2. To create a new user, run the following CREATE USER statement:
  CREATE USER c##<YOUR_DB_USERNAME> IDENTIFIED BY "<USER_PASSWORD>" CONTAINER=ALL; GRANT CREATE SESSION TO c##<YOUR_DB_USERNAME> CONTAINER=ALL;
  Conseil
  The newly created user'll be a common user with the C## prefix. The C## prefix is required for common users by Oracle.
To allow the monitoring user to see every PDB's rows in container-data views, run the following statement as SYSDBA on the CDB root. This is required for per-PDB metrics and events.
```
ALTER USER c##<YOUR_DB_USERNAME> SET CONTAINER_DATA=ALL CONTAINER=CURRENT;
```
Conseil
Ensure your USER_PASSWORD meets Oracle new user password requirements.

Grant monitoring privileges for multitenant database

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.

GRANT SELECT ON V_$INSTANCE   TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$DATABASE   TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$CONTAINERS TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$DATAFILE   TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$SYSSTAT                    TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$CON_SYSSTAT                TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$SYSMETRIC                  TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$CON_SYSMETRIC              TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$SESSION                    TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$RESOURCE_LIMIT             TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$OSSTAT                     TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$SGAINFO                    TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$ROWCACHE                   TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$PARAMETER                  TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON CDB_TABLESPACE_USAGE_METRICS  TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON CDB_TABLESPACES               TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON DBA_DATA_FILES                TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON DBA_FREE_SPACE                TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON DBA_RECYCLEBIN                TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$SQL            TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$SQL_PLAN_STATISTICS_ALL       TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$LOCK           TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$SESSION_EVENT  TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON DBA_PROCEDURES    TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON DBA_OBJECTS       TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$PDBS           TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON CDB_SERVICES      TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$ASM_DISKGROUP_STAT TO c##<USER_NAME> CONTAINER=ALL;
GRANT SELECT ON V_$ASM_DISK_STAT      TO c##<USER_NAME> CONTAINER=ALL;

Conseil

The V_$ASM_DISKGROUP_STAT and V_$ASM_DISK_STAT grants are only required if you want to collect ASM diskgroup and disk metrics.

Configure NRDOT Collector

Configure the NRDOT Collector with your CDB-specific settings.

Create the configuration file. The filename must be oracle-config.yaml.
bash
```
$sudo nano /etc/nrdot-collector/oracle-config.yaml
```

Add the configuration content below to the oracle-config.yaml file you created in the previous step.

full configuration

This configuration focuses only on database monitoring without host infrastructure metrics. To enable full-feature monitoring, refer to the configuration reference.

Oracle CDB Hostname/IP

Oracle CDB Port

Database Username (without the C## prefix)

Database Password

CDB Service Name

New Relic OTLP Endpoint

New Relic License Key

oracle-config.yaml

1
receivers:
2
    nroracledb:
3
      endpoint: oracle.example.com:1521
4
      username: C##newrelic
5
      password: YOUR_PASSWORD
6
      service: YOUR_CDB_SERVICE_NAME
7
      collection_interval: 10s
8
      events:
9
        db.server.query_sample:
10
          enabled: true
11
        db.server.top_query:
12
          enabled: true
13
        db.server.session.wait_sample:
14
          enabled: true
15

16
      top_query_collection:
17
        max_query_sample_count: 1000
18
        top_query_count: 200
19
        collection_interval: 60s
20
        allowed_comment_keys:
21
          - nr_service_guid
22

23
      query_sample_collection:
24
        max_rows_per_query: 100
25
        allowed_comment_keys:
26
          - nr_service_guid
27

28
      session_wait_event_collection:
29
        max_rows_per_query: 100
30

31
      # Metrics configuration - organized by category
32
      metrics:
33
        # === CPU & Performance Metrics ===
34
        oracledb.cpu_time:
35
          enabled: true
36
          attributes:
37
            - oracle.db.pdb
38
        oracledb.database.cpu.utilization:
39
          enabled: true
40
          attributes:
41
            - oracle.db.pdb
42
        oracledb.host.cpu.utilization:
43
          enabled: true
44
          attributes:
45
            - oracle.db.pdb
46

47
        # === Execution & Parse Metrics ===
48
        oracledb.executions:
49
          enabled: true
50
          attributes:
51
            - oracle.db.pdb
52
        oracledb.execution.utilization:
53
          enabled: true
54
          attributes:
55
            - oracledb.parse.type
56
            - oracle.db.pdb
57
        oracledb.parse_calls:
58
          enabled: true
59
          attributes:
60
            - oracle.db.pdb
61
        oracledb.parse.rate:
62
          enabled: true
63
          attributes:
64
            - oracledb.parse.result
65
            - oracle.db.pdb
66
        oracledb.parse.utilization:
67
          enabled: true
68
          attributes:
69
            - oracle.db.pdb
70
        oracledb.hard_parses:
71
          enabled: true
72
          attributes:
73
            - oracle.db.pdb
74

75
        # === I/O & Physical Read/Write Metrics ===
76
        oracledb.logical_reads:
77
          enabled: true
78
          attributes:
79
            - oracle.db.pdb
80
        oracledb.physical_reads:
81
          enabled: true
82
          attributes:
83
            - oracle.db.pdb
84
        oracledb.physical_reads_direct:
85
          enabled: true
86
          attributes:
87
            - oracle.db.pdb
88
        oracledb.physical_writes:
89
          enabled: true
90
          attributes:
91
            - oracle.db.pdb
92
        oracledb.physical_writes_direct:
93
          enabled: true
94
          attributes:
95
            - oracle.db.pdb
96
        oracledb.physical_read_io_requests:
97
          enabled: true
98
          attributes:
99
            - oracle.db.pdb
100
        oracledb.physical_write_io_requests:
101
          enabled: true
102
          attributes:
103
            - oracle.db.pdb
104

105
        # === New Physical I/O Metrics (detailed) ===
106
        oracledb.physical_io.cache_writes:
107
          enabled: true
108
          attributes:
109
            - oracle.db.pdb
110
        oracledb.physical_io.requests:
111
          enabled: true
112
          attributes:
113
            - disk.io.direction
114
            - disk.io.block_size
115
            - oracle.db.pdb
116
        oracledb.physical_io.transferred:
117
          enabled: true
118
          attributes:
119
            - disk.io.direction
120
            - disk.io.type
121
            - oracle.db.pdb
122

123
        # === Network I/O Metrics ===
124
        oracledb.sqlnet.io.transferred:
125
          enabled: true
126
          attributes:
127
            - network.io.direction
128
            - destination.type
129
            - oracle.db.pdb
130

131
        # === Buffer & Cache Metrics ===
132
        oracledb.consistent_gets:
133
          enabled: true
134
          attributes:
135
            - oracle.db.pdb
136
        oracledb.db_block_gets:
137
          enabled: true
138
          attributes:
139
            - oracle.db.pdb
140
        oracledb.buffer_cache.utilization:
141
          enabled: true
142
          attributes:
143
            - oracle.db.pdb
144
        oracledb.library_cache.utilization:
145
          enabled: true
146
          attributes:
147
            - oracle.db.pdb
148
        oracledb.data_dictionary.hit_ratio:
149
          enabled: true
150
        oracledb.shared_pool.utilization:
151
          enabled: true
152
          attributes:
153
            - oracle.db.pdb
154

155
        # === Memory Metrics ===
156
        oracledb.pga_memory:
157
          enabled: true
158
          attributes:
159
            - oracle.db.pdb
160
        oracledb.sga.limit:
161
          enabled: true
162
        oracledb.sga.usage:
163
          enabled: true
164
          attributes:
165
            - oracledb.sga.component.name
166

167
        # === Wait & Database Time Metrics ===
168
        oracledb.database.wait.utilization:
169
          enabled: true
170
          attributes:
171
            - oracle.db.pdb
172

173
        # === Lock & Deadlock Metrics ===
174
        oracledb.dml_locks.limit:
175
          enabled: true
176
        oracledb.dml_locks.usage:
177
          enabled: true
178
        oracledb.enqueue_locks.limit:
179
          enabled: true
180
        oracledb.enqueue_locks.usage:
181
          enabled: true
182
        oracledb.enqueue_resources.limit:
183
          enabled: true
184
        oracledb.enqueue_resources.usage:
185
          enabled: true
186
        oracledb.enqueue_deadlocks:
187
          enabled: true
188
          attributes:
189
            - oracle.db.pdb
190
        oracledb.exchange_deadlocks:
191
          enabled: true
192
          attributes:
193
            - oracle.db.pdb
194

195
        # === Process & Session Metrics ===
196
        oracledb.processes.limit:
197
          enabled: true
198
        oracledb.processes.usage:
199
          enabled: true
200
        oracledb.sessions.limit:
201
          enabled: true
202
        oracledb.sessions.usage:
203
          enabled: true
204
          attributes:
205
            - session_type
206
            - session_status
207
            - oracle.db.pdb
208
        oracledb.logons:
209
          enabled: true
210
          attributes:
211
            - oracle.db.pdb
212

213
        # === Transaction Metrics ===
214
        oracledb.transactions.limit:
215
          enabled: true
216
        oracledb.transactions.usage:
217
          enabled: true
218
        oracledb.user_commits:
219
          enabled: true
220
          attributes:
221
            - oracle.db.pdb
222
        oracledb.user_rollbacks:
223
          enabled: true
224
          attributes:
225
            - oracle.db.pdb
226

227
        # === Tablespace Metrics ===
228
        oracledb.tablespace_size.limit:
229
          enabled: true
230
          attributes:
231
            - tablespace_name
232
            - oracle.db.pdb
233
        oracledb.tablespace_size.usage:
234
          enabled: true
235
          attributes:
236
            - tablespace_name
237
            - oracle.db.pdb
238

239
        # === Storage Metrics ===
240
        oracledb.storage.usage:
241
          enabled: true
242
        oracledb.storage.utilization:
243
          enabled: true
244
        oracledb.recycle_bin.limit:
245
          enabled: true
246

247
        # === Parallel Operations Metrics ===
248
        oracledb.queries_parallelized:
249
          enabled: true
250
          attributes:
251
            - oracle.db.pdb
252
        oracledb.ddl_statements_parallelized:
253
          enabled: true
254
          attributes:
255
            - oracle.db.pdb
256
        oracledb.dml_statements_parallelized:
257
          enabled: true
258
          attributes:
259
            - oracle.db.pdb
260
        oracledb.parallel_operations_not_downgraded:
261
          enabled: true
262
          attributes:
263
            - oracle.db.pdb
264
        oracledb.parallel_operations_downgraded_1_to_25_pct:
265
          enabled: true
266
          attributes:
267
            - oracle.db.pdb
268
        oracledb.parallel_operations_downgraded_25_to_50_pct:
269
          enabled: true
270
          attributes:
271
            - oracle.db.pdb
272
        oracledb.parallel_operations_downgraded_50_to_75_pct:
273
          enabled: true
274
          attributes:
275
            - oracle.db.pdb
276
        oracledb.parallel_operations_downgraded_75_to_99_pct:
277
          enabled: true
278
          attributes:
279
            - oracle.db.pdb
280
        oracledb.parallel_operations_downgraded_to_serial:
281
          enabled: true
282
          attributes:
283
            - oracle.db.pdb
284

285
        # === Redo & Sort Metrics ===
286
        oracledb.redo_allocation.utilization:
287
          enabled: true
288
          attributes:
289
            - oracle.db.pdb
290
        oracledb.sort.ratio:
291
          enabled: true
292
          attributes:
293
            - oracledb.sort.type
294
            - oracle.db.pdb
295

296
        # === Response Time Metrics ===
297
        oracledb.sql_service.response.duration:
298
          enabled: true
299
          attributes:
300
            - oracle.db.pdb
301

302
        # === ASM (Automatic Storage Management) Metrics ===
303
        # Disabled by default (opt-in). Requires the V_$ASM_DISKGROUP_STAT and
304
        # V_$ASM_DISK_STAT grants from the previous step.
305
        oracledb.asm.disk_group.free:
306
          enabled: false
307
        oracledb.asm.disk_group.capacity:
308
          enabled: false
309
        oracledb.asm.disk_group.usable_free:
310
          enabled: false
311
        oracledb.asm.disk_group.offline_disks:
312
          enabled: false
313
        oracledb.asm.disk.errors:
314
          enabled: false
315

316
      # Resource attributes attached to all metrics/logs (all enabled by default)
317
      resource_attributes:
318
        host.name:
319
          enabled: true
320
        oracle.db.hosting_type:
321
          enabled: true
322
        oracle.db.open_mode:
323
          enabled: true
324
        oracle.db.pdb:
325
          enabled: true
326
        oracle.db.role:
327
          enabled: true
328
        oracle.db.version:
329
          enabled: true
330
        oracledb.instance.name:
331
          enabled: true
332
        service.instance.id:
333
          enabled: true
334
processors:
335
    batch:
336
    resource/add_event_name:
337
      attributes:
338
        - key: host.address
339
          value: YOUR_DB_HOST
340
          action: upsert
341
exporters:
342
    otlp/newrelic:
343
      endpoint: https://otlp.nr-data.net:4318
344
      headers:
345
        api-key: YOUR_LICENSE_KEY
346
      compression: gzip
347
      retry_on_failure:
348
        enabled: true
349
        initial_interval: 5s
350
        max_interval: 30s
351
        max_elapsed_time: 300s
352
service:
353
    pipelines:
354
      metrics/oracledb:
355
        receivers: [nroracledb]
356
        processors: [resource/add_event_name, batch]
357
        exporters: [otlp/newrelic]
358
      logs/oracledb:
359
        receivers: [nroracledb]
360
        processors: [resource/add_event_name, batch]
361
        exporters: [otlp/newrelic]

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`.

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

Conseil

For more detailed information about New Relic OTLP endpoint configuration and OpenTelemetry best practices, refer to the OpenTelemetry OTLP documentation.

Update NRDOT Collector configuration

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

Conseil

You can also:

Configure multiple receivers: To monitor multiple Oracle Database instances from one collector.
Configure SQL Query Receiver: To collect custom metrics from your Oracle Database.
Link your Oracle Database with APM: To correlate your application performance with database operations. This allows you to see exactly which applications are generating specific database workloads.
Set up secret management: 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.

Restart NRDOT Collector

After updating your configuration, restart the NRDOT Collector:

bash

$sudo systemctl restart nrdot-collector.service
$sudo systemctl status nrdot-collector.service

Conseil

Always restart the NRDOT Collector after making configuration changes so the new settings take effect.

Find and use your data

Once your data is being collected, you can access comprehensive Oracle Database monitoring through New Relic's UI.

To find your Oracle Database entity in New Relic:

Go to https://one.newrelic.com > All Capabilities > Databases.
Set the search criteria as instrumentation.provider = opentelemetry.
Select your Oracle Database from the list of entities.

Troubleshooting

Learn how to troubleshoot your Oracle CDB monitoring setup in New Relic.

Metrics reference

Learn about the available metrics collected by the NRDOT Collector.

RDS instrumentation

Learn how to set up your Oracle Database for RDS monitoring in New Relic.

Install & configure NRDOT Collector for on-host CDB monitoring

Preview

Guided installation

Prerequisites

Enroll to preview

Install NRDOT Collector

For AMD64 architecture

For ARM64 architecture

Configure database user

Conseil

Conseil

Grant monitoring privileges for multitenant database

Conseil

Configure NRDOT Collector

full configuration

Conseil

Update NRDOT Collector configuration

Conseil

Restart NRDOT Collector

Conseil

Find and use your data

Troubleshooting

Metrics reference

RDS instrumentation

Install & configure NRDOT Collector for on-host CDB monitoring

Preview

Guided installation

Prerequisites .css-21sua1{background:none;border:none;width:0;padding:0;}

Enroll to preview

Install NRDOT Collector

For ARM64 architecture

Configure database user

Conseil

Conseil

Grant monitoring privileges for multitenant database

Conseil

Configure NRDOT Collector

full configuration

Conseil

Update NRDOT Collector configuration

Conseil

Restart NRDOT Collector

Conseil

Find and use your data

Related articles

Troubleshooting

Metrics reference

RDS instrumentation

Prerequisites