Install & configure NRDOT for Oracle monitoring with Self-hosted PDB

Install NRDOT Collector

Select the appropriate installation distribution method for your Linux environment:

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

   ALTER SESSION SET CONTAINER = "<YOUR_PDB>";

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

   CREATE USER <YOUR_DB_USERNAME> IDENTIFIED BY "<YOUR_DB_PASSWORD>";
   GRANT CREATE SESSION TO <YOUR_DB_USERNAME>;

   Copy

Grant monitoring privileges for your PDB

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 <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$DATABASE   TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$CONTAINERS TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$DATAFILE   TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$SYSSTAT                    TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$SYSMETRIC                  TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$SESSION                    TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$RESOURCE_LIMIT             TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$OSSTAT                     TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$SGAINFO                    TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$ROWCACHE                   TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$PARAMETER                  TO <YOUR_DB_USERNAME>;
GRANT SELECT ON DBA_TABLESPACE_USAGE_METRICS  TO <YOUR_DB_USERNAME>;
GRANT SELECT ON DBA_TABLESPACES               TO <YOUR_DB_USERNAME>;
GRANT SELECT ON DBA_DATA_FILES                TO <YOUR_DB_USERNAME>;
GRANT SELECT ON DBA_FREE_SPACE                TO <YOUR_DB_USERNAME>;
GRANT SELECT ON DBA_RECYCLEBIN                TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$SQL            TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$SQL_PLAN_STATISTICS_ALL       TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$LOCK           TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$SESSION_EVENT  TO <YOUR_DB_USERNAME>;
GRANT SELECT ON DBA_PROCEDURES    TO <YOUR_DB_USERNAME>;
GRANT SELECT ON DBA_OBJECTS       TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$PDBS      TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$PROCESS     TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$TRANSACTION TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$CON_SYSSTAT   TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$CON_SYSMETRIC TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$ASM_DISKGROUP_STAT TO <YOUR_DB_USERNAME>;
GRANT SELECT ON V_$ASM_DISK_STAT TO <YOUR_DB_USERNAME>;

Configure NRDOT Collector

Configure the NRDOT Collector with your PDB-specific settings.

1. Create the configuration file. The filename must be oracle-config.yaml.

   bash

   Copy

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

   full configuration

   This configuration captures essential baseline metrics. To see the complete metric catalog, refer to the configuration reference.

   Oracle PDB Hostname/IP

   Enter your Oracle Database hostname or IP address

   Oracle PDB Port

   Enter your Oracle Database port number. The default value is 1521.

   Database Username

   Enter your database username for authentication

   Database Password

   Enter the password you set for the monitoring user

   PDB Service Name

   Enter your Oracle PDB service name

   New Relic OTLP Endpoint

   Enter your New Relic OTLP endpoint. For more information, refer to https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/

   New Relic License Key

   Enter your New Relic license key

   oracle-config.yaml

   DownloadCopy

   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: 15s
   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
           db.server.top_procedure:
   16
             enabled: true
   17
           db.server.query_plan:
   18
             enabled: true
   19
   
   20
         top_query_collection:
   21
           max_query_sample_count: 1000
   22
           top_query_count: 200
   23
           collection_interval: 60s
   24
           allowed_comment_keys:
   25
             - nr_service_guid
   26
   
   27
         query_sample_collection:
   28
           max_rows_per_query: 100
   29
           allowed_comment_keys:
   30
             - nr_service_guid
   31
   
   32
         session_wait_event_collection:
   33
           max_rows_per_query: 100
   34
   
   35
         top_procedure_collection:
   36
           max_procedure_sample_count: 1000
   37
           top_procedure_count: 250
   38
           collection_interval: 60s
   39
   
   40
         # Metrics configuration - This baseline configuration captures essential metrics. To enable advanced monitoring and extended telemetry, refer to the full configuration documentation
   41
         metrics:
   42
           oracledb.buffer_cache.utilization:
   43
             enabled: true
   44
             attributes:
   45
               - oracle.db.pdb
   46
           oracledb.consistent_gets:
   47
             enabled: true
   48
             attributes:
   49
               - oracle.db.pdb
   50
           oracledb.cpu_time:
   51
             enabled: true
   52
             attributes:
   53
               - oracle.db.pdb
   54
           oracledb.database.cpu.utilization:
   55
             enabled: true
   56
             attributes:
   57
               - oracle.db.pdb
   58
           oracledb.database.wait.utilization:
   59
             enabled: true
   60
             attributes:
   61
               - oracle.db.pdb
   62
           oracledb.db_block_gets:
   63
             enabled: true
   64
             attributes:
   65
               - oracle.db.pdb
   66
           oracledb.enqueue_deadlocks:
   67
             enabled: true
   68
             attributes:
   69
               - oracle.db.pdb
   70
           oracledb.execution.utilization:
   71
             enabled: true
   72
             attributes:
   73
               - oracledb.parse.type
   74
               - oracle.db.pdb
   75
           oracledb.executions:
   76
             enabled: true
   77
             attributes:
   78
               - oracle.db.pdb
   79
           oracledb.hard_parses:
   80
             enabled: true
   81
             attributes:
   82
               - oracle.db.pdb
   83
           oracledb.host.cpu.utilization:
   84
             enabled: true
   85
             attributes:
   86
               - oracle.db.pdb
   87
           oracledb.library_cache.utilization:
   88
             enabled: true
   89
             attributes:
   90
               - oracle.db.pdb
   91
           oracledb.logical_reads:
   92
             enabled: true
   93
             attributes:
   94
               - oracle.db.pdb
   95
           oracledb.logons:
   96
             enabled: true
   97
             attributes:
   98
               - oracle.db.pdb
   99
           oracledb.parse.rate:
   100
             enabled: true
   101
             attributes:
   102
               - oracledb.parse.result
   103
               - oracle.db.pdb
   104
           oracledb.parse_calls:
   105
             enabled: true
   106
             attributes:
   107
               - oracle.db.pdb
   108
           oracledb.pga_memory:
   109
             enabled: true
   110
             attributes:
   111
               - oracle.db.pdb
   112
           oracledb.physical_io.requests:
   113
             enabled: true
   114
             attributes:
   115
               - disk.io.direction
   116
               - disk.io.block_size
   117
               - oracle.db.pdb
   118
           oracledb.physical_reads:
   119
             enabled: true
   120
             attributes:
   121
               - oracle.db.pdb
   122
           oracledb.physical_writes:
   123
             enabled: true
   124
             attributes:
   125
               - oracle.db.pdb
   126
           oracledb.processes.usage:
   127
             enabled: true
   128
           oracledb.sessions.usage:
   129
             enabled: true
   130
             attributes:
   131
               - session_type
   132
               - session_status
   133
               - oracle.db.pdb
   134
           oracledb.sga.usage:
   135
             enabled: true
   136
             attributes:
   137
               - oracledb.sga.component.name
   138
           oracledb.shared_pool.utilization:
   139
             enabled: true
   140
             attributes:
   141
               - oracle.db.pdb
   142
           oracledb.sql_service.response.duration:
   143
             enabled: true
   144
             attributes:
   145
               - oracle.db.pdb
   146
           oracledb.sqlnet.io.transferred:
   147
             enabled: true
   148
             attributes:
   149
               - network.io.direction
   150
               - destination.type
   151
               - oracle.db.pdb
   152
           oracledb.tablespace_size.usage:
   153
             enabled: true
   154
             attributes:
   155
               - tablespace_name
   156
               - oracle.db.pdb
   157
           oracledb.transactions.usage:
   158
             enabled: true
   159
           oracledb.user_commits:
   160
             enabled: true
   161
             attributes:
   162
               - oracle.db.pdb
   163
           oracledb.user_rollbacks:
   164
             enabled: true
   165
             attributes:
   166
               - oracle.db.pdb
   167
   
   168
         # Resource attributes attached to all metrics/logs (all enabled by default)
   169
         resource_attributes:
   170
           oracle.db.edition:
   171
             enabled: true
   172
   exporters:
   173
       otlp/newrelic:
   174
         endpoint: https://otlp.nr-data.net:4318
   175
         headers:
   176
           api-key: YOUR_LICENSE_KEY
   177
         compression: gzip
   178
         retry_on_failure:
   179
           enabled: true
   180
           initial_interval: 5s
   181
           max_interval: 30s
   182
           max_elapsed_time: 300s
   183
         sending_queue:
   184
           enabled: true
   185
           sizer: bytes
   186
           queue_size: 100_000_000
   187
           num_consumers: 10
   188
           batch:
   189
             sizer: bytes
   190
             max_size: 1_000_000
   191
             min_size: 0
   192
             flush_timeout: 5s
   193
   service:
   194
       pipelines:
   195
         metrics/oracledb:
   196
           receivers: [nroracledb]
   197
           exporters: [otlp/newrelic]
   198
         logs/oracledb:
   199
           receivers: [nroracledb]
   200
           exporters: [otlp/newrelic]

3. 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.
   db.server.top_procedure	Top N stored procedures ranked by resource usage, including execution stats.
   db.server.query_plan	Execution plan details for top and sampled queries.

4. 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
   top_procedure_collection	max_procedure_sample_count	1000
   top_procedure_collection	top_procedure_count	250
   top_procedure_collection	collection_interval	60s

   Tip

   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:

$
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

Restart NRDOT Collector

After updating your configuration, restart the NRDOT Collector:

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

Find and use your data

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

To find your Oracle Database entity in New Relic:

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