Install & configure NRDOT Collector for on-host PDB 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 Pluggable Database (PDB) performance with database monitoring, query analysis, and system health metrics using the New Relic Distribution of OpenTelemetry (NRDOT) collector.

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.

Conseil

If you need to monitor the entire container database rather than an individual pluggable database, refer to CDB instrumentation.

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 the necessary privileges for your PDB Oracle Database instance.

Run the following statement as SYS before creating the user or running any grants:
```
ALTER SESSION SET CONTAINER = "<YOUR_PDB>";
```

Run the following statements as SYS inside your target PDB to create a local monitoring user:

CREATE USER <USER_NAME> IDENTIFIED BY "<YOUR_PASSWORD>";
GRANT CREATE SESSION TO <USER_NAME>;

Grant monitoring privileges for multitenant database

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.

GRANT SELECT ON V_$INSTANCE   TO <USER_NAME>;
GRANT SELECT ON V_$DATABASE   TO <USER_NAME>;
GRANT SELECT ON V_$CONTAINERS TO <USER_NAME>;
GRANT SELECT ON V_$DATAFILE   TO <USER_NAME>;
GRANT SELECT ON V_$SYSSTAT                    TO <USER_NAME>;
GRANT SELECT ON V_$SYSMETRIC                  TO <USER_NAME>;
GRANT SELECT ON V_$SESSION                    TO <USER_NAME>;
GRANT SELECT ON V_$RESOURCE_LIMIT             TO <USER_NAME>;
GRANT SELECT ON V_$OSSTAT                     TO <USER_NAME>;
GRANT SELECT ON V_$SGAINFO                    TO <USER_NAME>;
GRANT SELECT ON V_$ROWCACHE                   TO <USER_NAME>;
GRANT SELECT ON V_$PARAMETER                  TO <USER_NAME>;
GRANT SELECT ON DBA_TABLESPACE_USAGE_METRICS  TO <USER_NAME>;
GRANT SELECT ON DBA_TABLESPACES               TO <USER_NAME>;
GRANT SELECT ON DBA_DATA_FILES                TO <USER_NAME>;
GRANT SELECT ON DBA_FREE_SPACE                TO <USER_NAME>;
GRANT SELECT ON DBA_RECYCLEBIN                TO <USER_NAME>;
GRANT SELECT ON V_$SQL            TO <USER_NAME>;
GRANT SELECT ON V_$SQL_PLAN_STATISTICS_ALL       TO <USER_NAME>;
GRANT SELECT ON V_$LOCK           TO <USER_NAME>;
GRANT SELECT ON V_$SESSION_EVENT  TO <USER_NAME>;
GRANT SELECT ON DBA_PROCEDURES    TO <USER_NAME>;
GRANT SELECT ON DBA_OBJECTS       TO <USER_NAME>;
GRANT SELECT ON V_$PDBS      TO <USER_NAME>;
GRANT SELECT ON CDB_SERVICES TO <USER_NAME>;

Configure NRDOT Collector

Configure the NRDOT Collector with your PDB-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 PDB Hostname/IP

Oracle PDB Port

Database Username

Database Password

PDB 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: newrelic
5
      password: YOUR_PASSWORD
6
      service: YOUR_PDB_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
      # Resource attributes attached to all metrics/logs (all enabled by default)
303
      resource_attributes:
304
        host.name:
305
          enabled: true
306
        oracle.db.hosting_type:
307
          enabled: true
308
        oracle.db.open_mode:
309
          enabled: true
310
        oracle.db.pdb:
311
          enabled: true
312
        oracle.db.role:
313
          enabled: true
314
        oracle.db.version:
315
          enabled: true
316
        oracledb.instance.name:
317
          enabled: true
318
        service.instance.id:
319
          enabled: true
320
processors:
321
    batch:
322
    resource/add_event_name:
323
      attributes:
324
        - key: host.address
325
          value: YOUR_DB_HOST
326
          action: upsert
327
exporters:
328
    otlp/newrelic:
329
      endpoint: https://otlp.nr-data.net:4318
330
      headers:
331
        api-key: YOUR_LICENSE_KEY
332
      compression: gzip
333
      retry_on_failure:
334
        enabled: true
335
        initial_interval: 5s
336
        max_interval: 30s
337
        max_elapsed_time: 300s
338
service:
339
    pipelines:
340
      metrics/oracledb:
341
        receivers: [nroracledb]
342
        processors: [resource/add_event_name, batch]
343
        exporters: [otlp/newrelic]
344
      logs/oracledb:
345
        receivers: [nroracledb]
346
        processors: [resource/add_event_name, batch]
347
        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 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 to ensure 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 PDB 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 PDB monitoring

Preview

Guided installation

Conseil

Prerequisites

Enroll to preview

Install NRDOT Collector

For AMD64 architecture

For ARM64 architecture

Configure database user

Grant monitoring privileges for multitenant database

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

Preview

Guided installation

Conseil

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

Enroll to preview

Install NRDOT Collector

For ARM64 architecture

Configure database user

Grant monitoring privileges for multitenant database

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