Oracledb Receiver

Available in: contrib Maintainers: @dmitryax, @crobert-1, @atoulme Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

Getting Started

To use the Oracle DB receiver you must define how to connect to your DB. This can be done in two ways, defined in the Primary and Secondary configuration option sections. Defining one of the two configurations is required. If both are defined, the primary option will be used.

Primary Configuration Option

Required options:

datasource: Oracle database connection string. Special characters must be encoded. Refer to Oracle Go Driver go_ora documentation for full connection string options.

Example:

receivers:
  oracledb:
    datasource: "oracle://otel:password@localhost:51521/XE"

Secondary Configuration Option

Required options:

endpoint: Endpoint used to connect to the Oracle DB server. Must be in the format of host:port
password: Password for the Oracle DB connection. Special characters are allowed.
service: Oracle DB service that the receiver should connect to.
username: Username for the Oracle DB connection.

Example:

receivers:
  oracledb:
    endpoint: localhost:51521
    password: p@sswo%d
    service: XE
    username: otel

Optional Configuration Options

collection_interval (default = 10s): The interval at which metrics should be emitted by this receiver.
initial_delay (default = 1s): The initial time period this receiver waits before starting.
timeout (default = 0): Timeout for each Oracle DB request. Disabled by default.

Permissions

Depending on which metrics you collect, you will need to assign those permissions to the database user:

GRANT SELECT ON V_$SESSION TO <username>;
GRANT SELECT ON V_$SYSSTAT TO <username>;
GRANT SELECT ON V_$RESOURCE_LIMIT TO <username>;
GRANT SELECT ON DBA_TABLESPACES TO <username>;
GRANT SELECT ON DBA_DATA_FILES TO <username>;
GRANT SELECT ON DBA_TABLESPACE_USAGE_METRICS TO <username>;

Enabling metrics.

See documentation. You can enable or disable selective metrics. Example:

receivers:
  oracledb:
    datasource: "oracle://otel:password@localhost:51521/XE"
    metrics:
      oracledb.query.cpu_time:
        enabled: false
      oracledb.query.physical_read_requests:
        enabled: true

Enabling events.

The following is a generic configuration that can be used for the default logs and metrics scraped by the Oracle DB receiver.

receivers:
  oracledb:
    collection_interval: 10s                     # interval for overall collection
    datasource: "oracle://otel:password@localhost:51521/XE"
    events:
      db.server.query_sample:
        enabled: true
      db.server.top_query:
        enabled: true
    top_query_collection:                        # this collection exports the most expensive queries as logs
      max_query_sample_count: 1000               # maximum number of samples collected from db to filter the top N
      top_query_count: 200                       # The maximum number of queries (N) for which the metrics would be reported
      collection_interval: 60s                   # collection interval for top query collection specifically
    query_sample_collection:                     # this collection exports the currently (relate to the query time) executing queries as logs
      max_rows_per_query: 100                     # the maximum number of samples to bre reported.

Metrics

Metric Name	Description	Unit	Type	Attributes
❌ `oracledb.consistent_gets`	Number of times a consistent read was requested for a block from the buffer cache.	{gets}	Counter
✅ `oracledb.cpu_time`	Cumulative CPU time, in seconds	s	Counter
❌ `oracledb.db_block_gets`	Number of times a current block was requested from the buffer cache.	{gets}	Counter
❌ `oracledb.ddl_statements_parallelized`	Number of DDL statements that were executed in parallel	{statements}	Counter
✅ `oracledb.dml_locks.limit`	Maximum limit of active DML (Data Manipulation Language) locks, -1 if unlimited.	{locks}	Gauge
✅ `oracledb.dml_locks.usage`	Current count of active DML (Data Manipulation Language) locks.	{locks}	Gauge
❌ `oracledb.dml_statements_parallelized`	Number of DML statements that were executed in parallel	{statements}	Counter
✅ `oracledb.enqueue_deadlocks`	Total number of deadlocks between table or row locks in different sessions.	{deadlocks}	Counter
✅ `oracledb.enqueue_locks.limit`	Maximum limit of active enqueue locks, -1 if unlimited.	{locks}	Gauge
✅ `oracledb.enqueue_locks.usage`	Current count of active enqueue locks.	{locks}	Gauge
✅ `oracledb.enqueue_resources.limit`	Maximum limit of active enqueue resources, -1 if unlimited.	{resources}	Gauge
✅ `oracledb.enqueue_resources.usage`	Current count of active enqueue resources.	{resources}	Gauge
✅ `oracledb.exchange_deadlocks`	Number of times that a process detected a potential deadlock when exchanging two buffers and raised an internal, restartable error. Index scans are the only operations that perform exchanges.	{deadlocks}	Counter
✅ `oracledb.executions`	Total number of calls (user and recursive) that executed SQL statements	{executions}	Counter
✅ `oracledb.hard_parses`	Number of hard parses	{parses}	Counter
✅ `oracledb.logical_reads`	Number of logical reads	{reads}	Counter
❌ `oracledb.logons`	Number of logon operations	{operation}	Counter
❌ `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	{executions}	Counter
❌ `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	{executions}	Counter
❌ `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	{executions}	Counter
❌ `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	{executions}	Counter
❌ `oracledb.parallel_operations_downgraded_to_serial`	Number of times parallel execution was requested but execution was serial because of insufficient parallel execution servers	{executions}	Counter
❌ `oracledb.parallel_operations_not_downgraded`	Number of times parallel execution was executed at the requested degree of parallelism	{executions}	Counter
✅ `oracledb.parse_calls`	Total number of parse calls.	{parses}	Counter
✅ `oracledb.pga_memory`	Session PGA (Program Global Area) memory	By	Counter
❌ `oracledb.physical_read_io_requests`	Number of read requests for application activity	{requests}	Counter
✅ `oracledb.physical_reads`	Number of physical reads	{reads}	Counter
❌ `oracledb.physical_reads_direct`	Number of reads directly from disk, bypassing the buffer cache	{reads}	Counter
❌ `oracledb.physical_write_io_requests`	Number of write requests for application activity	{requests}	Counter
❌ `oracledb.physical_writes`	Number of physical writes	{writes}	Counter
❌ `oracledb.physical_writes_direct`	Number of writes directly to disk, bypassing the buffer cache	{writes}	Counter
✅ `oracledb.processes.limit`	Maximum limit of active processes, -1 if unlimited.	{processes}	Gauge
✅ `oracledb.processes.usage`	Current count of active processes.	{processes}	Gauge
❌ `oracledb.queries_parallelized`	Number of SELECT statements executed in parallel	{queries}	Counter
✅ `oracledb.sessions.limit`	Maximum limit of active sessions, -1 if unlimited.	{sessions}	Gauge
✅ `oracledb.sessions.usage`	Count of active sessions.	{sessions}	Gauge	session_type, session_status
✅ `oracledb.tablespace_size.limit`	Maximum size of tablespace in bytes, -1 if unlimited.	By	Gauge	tablespace_name
✅ `oracledb.tablespace_size.usage`	Used tablespace in bytes.	By	Gauge	tablespace_name
✅ `oracledb.transactions.limit`	Maximum limit of active transactions, -1 if unlimited.	{transactions}	Gauge
✅ `oracledb.transactions.usage`	Current count of active transactions.	{transactions}	Gauge
✅ `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. Commits often represent the closest thing to a user transaction rate.	{commits}	Counter
✅ `oracledb.user_rollbacks`	Number of times users manually issue the ROLLBACK statement or an error occurs during a user’s transactions	1	Counter

Attributes

Attribute Name	Description	Type
`client.address`	Hostname or address of the client.	string
`client.port`	TCP port used by the client.	int
`db.namespace`	The database name.	string
`db.query.text`	The text of the database query being executed.	string
`db.server.name`	The name of the server hosting the database.	string
`db.system.name`	The database management system (DBMS) product as identified by the client instrumentation.	string
`network.peer.address`	IP address of the peer client.	string
`network.peer.port`	TCP port used by the peer client.	int
`oracledb.application_wait_time`	The total time (in seconds) a query spent waiting on the application before it could proceed with execution (reporting delta).	double
`oracledb.buffer_gets`	Number of logical reads (i.e., buffer cache accesses) performed by a query (reporting delta).	int
`oracledb.child_address`	Address of the child cursor.	string
`oracledb.child_number`	The child number of the query.	string
`oracledb.cluster_wait_time`	Total time (in seconds) that a query waited due to Oracle Real Application Clusters (RAC) coordination (reporting delta).	double
`oracledb.command_type`	Command type of the query.	int
`oracledb.concurrency_wait_time`	Total time (in seconds) a query spent waiting on concurrency-related events (reporting delta).	double
`oracledb.cpu_time`	Total time (in seconds) that the CPU spent actively processing a query, excluding time spent waiting (reporting delta).	double
`oracledb.direct_reads`	The number of direct path reads performed by a query — i.e., data blocks read directly from disk into the session’s memory (reporting delta).	int
`oracledb.direct_writes`	The number of direct path write operations, where data is written directly to disk from user memory (reporting delta).	int
`oracledb.disk_reads`	The number of physical reads a query performs — that is, the number of data blocks read from disk (reporting delta).	int
`oracledb.duration_sec`	Total time taken by a database query to execute.	double
`oracledb.elapsed_time`	The total time (in seconds) taken by a query from start to finish, including CPU time and all types of waits (reporting delta).	double
`oracledb.event`	The specific wait event that a query or session is currently experiencing.	string
`oracledb.executions`	The number of times a specific SQL query has been executed (reporting delta).	int
`oracledb.module`	Logical module name of the client application that initiated a query or session.	string
`oracledb.osuser`	Name of the operating system user that initiated or is running the Oracle database session.	string
`oracledb.physical_read_bytes`	The total number of bytes read from disk by a query (reporting delta).	int
`oracledb.physical_read_requests`	The number of physical I/O read operations performed by a query (reporting delta).	int
`oracledb.physical_write_bytes`	The total number of bytes written to disk by a query (reporting delta).	int
`oracledb.physical_write_requests`	The number of times a query requested to write data to disk (reporting delta).	int
`oracledb.plan_hash_value`	Binary hash value calculated on the query execution plan and used to identify similar query execution plans, reported in the HEX format.	string
`oracledb.procedure_execution_count`	The number of times the stored procedure has been executed, derived from the minimum statement execution count across all statements in the procedure (reporting delta). Please note, this is best effort and may not be accurate in some scenarios. Use with caution.	int
`oracledb.procedure_id`	The identifier of the stored procedure or function being executed by the query.	int
`oracledb.procedure_name`	Name of the database object that a query is accessing.	string
`oracledb.procedure_type`	Type of the database object that a query is accessing.	string
`oracledb.process`	The operating system process ID (PID) associated with a session.	string
`oracledb.program`	Name of the client program or tool that initiated the Oracle database session.	string
`oracledb.query_plan`	The query execution plan used by the SQL Server.	string
`oracledb.rows_processed`	The total number of rows that a query has read, returned, or affected during its execution (reporting delta).	int
`oracledb.schemaname`	Oracle schema under which SQL statements are being executed	string
`oracledb.serial`	Serial number associated with a session.	string
`oracledb.sid`	ID of the Oracle Server session.	string
`oracledb.sql_id`	The SQL ID of the query.	string
`oracledb.state`	Current state of the query or the session executing it.	string
`oracledb.status`	Execution state or result of a database query or session.	string
`oracledb.user_io_wait_time`	The total time (in seconds) a query spent waiting for user I/O operations—such as reading or writing data to disk or network file systems (reporting delta).	double
`oracledb.wait_class`	The category of wait events a query or session is currently experiencing in Oracle Database.	string
`session_status`	Session status	string
`session_type`	Session type	string
`tablespace_name`	Tablespace name	string
`user.name`	Database user name under which a session is connected to	string

Resource Attributes

Attribute Name	Description	Type	Enabled
`host.name`	The host name of Oracle Server	string	✅
`oracledb.instance.name`	The name of the instance that data is coming from.	string	✅
`service.instance.id`	A unique identifier of the Oracle DB instance in the format host:port/serviceName. (defaults to ‘unknown:1521’, in case of error in generating this value)	string	✅

Configuration

Example Configuration

oracledb:
  # driver name: oracle
  endpoint: localhost:51521
  password: password
  service: XE
  username: otel
  # Refer to Oracle Go Driver go_ora documentation for full connection string options
  datasource: "oracle://otel:password@localhost:51521/XE"
  top_query_collection:
    max_query_sample_count: 222
    top_query_count: 200
  metrics:
    oracledb.exchange_deadlocks:
      enabled: false
    oracledb.tablespace_size.usage:
      enabled: false
  events:
    db.server.top_query:
      enabled: true
    db.server.query_sample:
      enabled: true

Last generated: 2026-04-13

Collector components

​Oracledb Receiver

​Supported Telemetry

​Overview

​Getting Started

​Primary Configuration Option

​Secondary Configuration Option

​Optional Configuration Options

​Permissions

​Enabling metrics.

​Enabling events.

​Metrics

​Attributes

​Resource Attributes

​Configuration

​Example Configuration