Oracle DB

Plugin: go.d.plugin Module: oracledb

Overview

This collector monitors the health and performance of Oracle DB servers and collects general statistics, replication and user metrics.

It establishes a connection to the Oracle DB instance via a TCP or UNIX socket and extracts metrics from the following database tables:

v$sysmetric
v$sysstat
v$waitclassmetric
v$system_wait_class
dba_data_files
dba_free_space
dba_segments
dba_temp_files
dba_tablespaces
v$temp_space_header

It also provides top-queries and running-queries functions using V$SQLSTATS and V$SESSION.

This collector is supported on all platforms.

This collector supports collecting metrics from multiple instances of this integration, including remote instances.

Default Behavior

Auto-Detection

The collector can automatically detect Oracle DB instances running on:

Localhost, listening on port 1521
Within Docker containers

Note: Oracle DB requires a username and password. While Netdata can automatically discover Oracle DB instances and create data collection jobs, these jobs will fail unless you provide the correct credentials.

Limits

The default configuration for this integration does not impose any limits on data collection.

Performance Impact

The default configuration for this integration is not expected to impose a significant performance impact on the system.

Setup

You can configure the oracledb collector in two ways:

Method	Best for	How to
UI	Fast setup without editing files	Go to Nodes → Configure this node → Collectors → Jobs, search for oracledb, then click + to add a job.
File	If you prefer configuring via file, or need to automate deployments (e.g., with Ansible)	Edit `go.d/oracledb.conf` and add a job.

:::important

UI configuration requires paid Netdata Cloud plan.

:::

Prerequisites

Create a read only user for netdata

Follow the official instructions for your oracle RDBMS to create a read-only user for netdata. The operation may follow this approach

Connect to your Oracle database with an administrative user and execute:

bash

CREATE USER netdata IDENTIFIED BY <PASSWORD>;

GRANT CONNECT TO netdata;
GRANT SELECT_CATALOG_ROLE TO netdata;

The top-queries and running-queries functions require access to V$SQLSTATS and V$SESSION.

Configuration

Options

The following options can be defined globally: update_every, autodetection_retry.

<details open><summary>Config options</summary>

Group	Option	Description	Default	Required
Collection	update_every	Data collection interval (seconds).	1	no
	autodetection_retry	Autodetection retry interval (seconds). Set 0 to disable.	0	no
Target	dsn	Oracle server DSN (Data Source Name). Format: `oracle://username:password@host:port/service?param1=value1&...&paramN=valueN`.		yes
	timeout	Query timeout (seconds).	1	no
Functions	functions.top_queries.disabled	Disable the top-queries function.	no	no
	functions.top_queries.timeout	Query timeout (seconds). Uses collector timeout if not set.		no
	functions.top_queries.limit	Maximum number of queries to return.	500	no
	functions.running_queries.disabled	Disable the running-queries function.	no	no
	functions.running_queries.timeout	Query timeout (seconds). Uses collector timeout if not set.		no
	functions.running_queries.limit	Maximum number of queries to return.	500	no
Virtual Node	vnode	Associates this data collection job with a Virtual Node.		no

</details>

via UI

Configure the oracledb collector from the Netdata web interface:

Go to Nodes.
Select the node where you want the oracledb data-collection job to run and click the :gear: (Configure this node). That node will run the data collection.
The Collectors → Jobs view opens by default.
In the Search box, type oracledb (or scroll the list) to locate the oracledb collector.
Click the + next to the oracledb collector to add a new job.
Fill in the job fields, then click Test to verify the configuration and Submit to save.
- Test runs the job with the provided settings and shows whether data can be collected.
- If it fails, an error message appears with details (for example, connection refused, timeout, or command execution errors), so you can adjust and retest.

via File

The configuration file name for this integration is go.d/oracledb.conf.

The file format is YAML. Generally, the structure is:

yaml

update_every: 1
autodetection_retry: 0
jobs:
  - name: some_name1
  - name: some_name2

You can edit the configuration file using the edit-config script from the Netdata config directory.

bash

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config go.d/oracledb.conf

Examples

TCP socket

An example configuration.

<details open><summary>Config</summary>

yaml

jobs:
  - name: local
    dsn: oracle://netdata:[email protected]:1521/XE

</details>

TLS connection (TCPS)

An example configuration for TLS connection.

<details open><summary>Config</summary>

yaml

jobs:
  - name: local
    dsn: 'oracle://netdata:[email protected]:1521/XE?ssl=true&ssl verify=true'

</details>

Multi-instance

Note: When you define multiple jobs, their names must be unique.

Local and remote instances.

<details open><summary>Config</summary>

yaml

jobs:
  - name: local
    dsn: oracle://netdata:[email protected]:1521/XE

  - name: remote
    dsn: oracle://netdata:[email protected]:1521/XE

</details>

Alerts

There are no alerts configured by default for this integration.

Metrics

Metrics grouped by scope.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

Per Oracle DB instance

These metrics refer to the entire monitored application.

This scope has no labels.

Metrics:

Metric	Dimensions	Unit
oracledb.sessions	session	sessions
oracledb.average_active_sessions	active	sessions
oracledb.sessions_utilization	session_limit	percent
oracledb.current_logons	logons	logons
oracledb.logons	logons	logons/s
oracledb.database_wait_time_ratio	db_wait_time	percent
oracledb.sql_service_response_time	sql_resp_time	seconds
oracledb.enqueue_timeouts	enqueue	timeouts/s
oracledb.disk_io	read, written	bytes/s
oracledb.disk_iops	read, write	operations/s
oracledb.sorts	memory, disk	sorts/s
oracledb.table_scans	short_table, long_table	scans/s
oracledb.cache_hit_ratio	buffer, cursor, library, row	percent
oracledb.global_cache_blocks	corrupted, lost	blocks/s
oracledb.activity	parse, execute, user_commits, user_rollbacks	events/s

Per tablespace

These metrics refer to the Tablespace.

Labels:

Label	Description
tablespace	Tablespace name.
autoextend_status	Autoextend status (enabled, disabled, mixed).

Metrics:

Metric	Dimensions	Unit
oracledb.tablespace_utilization	utilization	percent
oracledb.tablespace_usage	avail, used	bytes

Per wait class

These metrics refer to the Wait Class.

Labels:

Label	Description
wait_class	Wait Class name.

Metrics:

Metric	Dimensions	Unit
oracledb.wait_class_wait_time	wait_time	milliseconds

Live Data

This collector exposes real-time functions for interactive troubleshooting in the Live tab.

Top Queries

Retrieves aggregated SQL statement performance metrics from Oracle V$SQLSTATS view.

This function queries V$SQLSTATS which provides SQL execution statistics aggregated across all cursors for each SQL statement. Statistics include execution counts, timing metrics, I/O operations, and resource consumption.

Use cases:

Identify slow queries consuming the most total execution time
Find queries with high buffer gets or disk reads for I/O optimization
Analyze CPU-intensive queries for resource tuning

Query text is truncated at 4096 characters for display purposes.

Aspect	Description
Name	`Oracledb:top-queries`
Require Cloud	yes
Performance	Queries `V$SQLSTATS` which is a lightweight view optimized for statistics retrieval:
• On busy databases with many SQL statements, the query may take longer
• Default limit of 500 rows balances usefulness with performance
Security	Query text may contain unmasked literal values including potentially sensitive data:
• Personal information in WHERE clauses or INSERT values
• Business data and internal identifiers
• Access should be restricted to authorized personnel only
Availability	Available when:
• The collector has successfully connected to Oracle DB
• The user has SELECT privilege on `V$SQLSTATS`
• Returns HTTP 503 if the connection cannot be established
• Returns HTTP 500 if the query fails
• Returns HTTP 504 if the query times out

Prerequisites

Grant access to V$SQLSTATS

The monitoring user must have SELECT privilege on V$SQLSTATS and related views.

Grant the required privileges:

sql

-- Note: Use V_$ (with underscore) for GRANT - this is the base fixed view
-- Queries use the V$ public synonym
GRANT SELECT ON V_$SQLSTATS TO netdata;
-- Or grant the broader role:
GRANT SELECT_CATALOG_ROLE TO netdata;

Verify access:

sql

SELECT COUNT(*) FROM V$SQLSTATS WHERE ROWNUM <= 1;

:::info

V$SQLSTATS is available in Oracle 10g and later
The view aggregates statistics across all child cursors for each SQL statement
Some columns like MODULE and ACTION require applications to set them via DBMS_APPLICATION_INFO

:::

Parameters

Parameter	Type	Description	Required	Default	Options
Filter By	select	Select the primary sort column. Options include total time, CPU time, executions, buffer gets, disk reads, and more. Defaults to total time to focus on most resource-intensive queries.	yes	totalTime

Returns

Aggregated SQL statistics from V$SQLSTATS. Each row represents a unique SQL statement with cumulative metrics across all executions.

Column	Type	Unit	Visibility	Description
SQL ID	string		hidden	Unique identifier for the SQL statement in the shared pool. Can be used to find execution plans in `V$SQL_PLAN`.
Query	string			SQL statement text. Truncated to 4096 characters for display purposes.
Schema	string			Schema under which the SQL was parsed. Useful for identifying which application or user generated the query.
Executions	integer			Total number of times this SQL statement has been executed. High values indicate frequently run queries.
Total Time	duration	milliseconds		Cumulative elapsed time across all executions. High values indicate queries consuming significant database resources.
Avg Time	duration	milliseconds		Average elapsed time per execution. Use this to compare typical performance across different SQL statements.
CPU Time	duration	milliseconds		Cumulative CPU time consumed across all executions. Compare with total time to identify I/O-bound vs CPU-bound queries.
Buffer Gets	integer			Total number of logical reads from the buffer cache. High values relative to rows processed may indicate inefficient queries.
Disk Reads	integer			Total number of physical reads from disk. High values indicate queries that cannot be satisfied from the buffer cache.
Rows Processed	integer			Total number of rows processed across all executions. Compare with buffer gets to assess query efficiency.
Parse Calls	integer		hidden	Number of times the SQL was parsed (hard + soft parses). High values may indicate lack of bind variables.
Module	string		hidden	Application module name set via `DBMS_APPLICATION_INFO`. Useful for identifying which application component generated the query.
Action	string		hidden	Application action name set via `DBMS_APPLICATION_INFO`. Provides finer-grained identification within a module.
Last Active	string		hidden	Timestamp when this SQL statement was last executed. Helps identify recently active vs historical queries.

Running Queries

Retrieves currently executing SQL statements from Oracle V$SESSION view.

This function queries V$SESSION joined with V$SQL to provide a real-time snapshot of all active user sessions currently executing SQL statements. It shows session details, elapsed time, and the SQL being executed.

Use cases:

Identify long-running queries that may be blocking other sessions
Monitor active workload and session distribution
Debug stuck or slow queries in real-time

Query text is truncated at 4096 characters for display purposes.

Aspect	Description
Name	`Oracledb:running-queries`
Require Cloud	yes
Performance	Queries `V$SESSION` joined with `V$SQL` for currently active sessions:
• Lightweight operation as it only returns currently active user sessions
• Default limit of 500 rows (rarely reached for running queries)
Security	Query text may contain unmasked literal values including potentially sensitive data:
• Personal information in WHERE clauses or INSERT values
• Business data and credentials in query parameters
• Access should be restricted to authorized personnel only
Availability	Available when:
• The collector has successfully connected to Oracle DB
• The user has SELECT privilege on `V$SESSION` and `V$SQL`
• Returns HTTP 503 if the connection cannot be established
• Returns HTTP 500 if the query fails
• Returns HTTP 504 if the query times out

Prerequisites

Grant access to V$SESSION

The monitoring user must have SELECT privilege on V$SESSION and V$SQL.

Grant the required privileges:

sql

-- Note: Use V_$ (with underscore) for GRANT - this is the base fixed view
-- Queries use the V$ public synonym
GRANT SELECT ON V_$SESSION TO netdata;
GRANT SELECT ON V_$SQL TO netdata;
-- Or grant the broader role:
GRANT SELECT_CATALOG_ROLE TO netdata;

Verify access:

sql

SELECT COUNT(*) FROM V$SESSION WHERE ROWNUM <= 1;

:::info

Only USER sessions with ACTIVE status and a current SQL ID are returned
The elapsed time is based on LAST_CALL_ET which resets when a new SQL starts
BACKGROUND sessions (Oracle internal processes) are filtered out

:::

Parameters

Parameter	Type	Description	Required	Default	Options
Filter By	select	Select the primary sort column. Defaults to elapsed time to show longest-running queries first.	yes	lastCallMs

Returns

Real-time snapshot of currently executing SQL statements. Each row represents an active user session with its current SQL.

Column	Type	Unit	Visibility	Description
Session	string			Session identifier in format `SID,SERIAL#`. Can be used with `ALTER SYSTEM KILL SESSION` if needed.
User	string			Oracle username of the session. Useful for identifying workload by user.
Status	string			Session status (ACTIVE for currently executing). Only active sessions with SQL are shown.
Type	string		hidden	Session type (USER or BACKGROUND). This function filters to USER sessions only.
SQL ID	string		hidden	Identifier of the currently executing SQL. Can be used to find the statement in `V$SQL`.
Query	string			SQL statement text currently being executed. Truncated to 4096 characters.
Elapsed	duration	milliseconds		Time elapsed since the session's last call started. High values indicate long-running operations that may need investigation.
SQL Exec Start	string		hidden	Timestamp when the current SQL execution started.
Module	string		hidden	Application module name set via `DBMS_APPLICATION_INFO`. Identifies which application is running the query.
Action	string		hidden	Application action name set via `DBMS_APPLICATION_INFO`.
Program	string		hidden	Client program name that established the session (e.g., sqlplus, JDBC Thin Client).
Machine	string		hidden	Client machine name or IP address. Useful for identifying query sources.

Troubleshooting

Debug Mode

Important: Debug mode is not supported for data collection jobs created via the UI using the Dyncfg feature.

To troubleshoot issues with the oracledb collector, run the go.d.plugin with the debug option enabled. The output should give you clues as to why the collector isn't working.

Navigate to the plugins.d directory, usually at /usr/libexec/netdata/plugins.d/. If that's not the case on your system, open netdata.conf and look for the plugins setting under [directories].
bash
```
cd /usr/libexec/netdata/plugins.d/
```
Switch to the netdata user.
bash
```
sudo -u netdata -s
```
Run the go.d.plugin to debug the collector:
bash
```
./go.d.plugin -d -m oracledb
```
To debug a specific job:
bash
```
./go.d.plugin -d -m oracledb -j jobName
```

Getting Logs

If you're encountering problems with the oracledb collector, follow these steps to retrieve logs and identify potential issues:

Run the command specific to your system (systemd, non-systemd, or Docker container).
Examine the output for any warnings or error messages that might indicate issues. These messages should provide clues about the root cause of the problem.

System with systemd

Use the following command to view logs generated since the last Netdata service restart:

bash

journalctl _SYSTEMD_INVOCATION_ID="$(systemctl show --value --property=InvocationID netdata)" --namespace=netdata --grep oracledb

System without systemd

Locate the collector log file, typically at /var/log/netdata/collector.log, and use grep to filter for collector's name:

bash

grep oracledb /var/log/netdata/collector.log

Note: This method shows logs from all restarts. Focus on the latest entries for troubleshooting current issues.

Docker Container

If your Netdata runs in a Docker container named "netdata" (replace if different), use this command:

bash

docker logs netdata 2>&1 | grep oracledb