> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Oracledb

> OpenTelemetry receiver for Oracledb

# Oracledb Receiver

![Status](https://img.shields.io/badge/status-alpha-red)

**Available in:** `contrib`

**Maintainers:** [@dmitryax](https://github.com/dmitryax), [@crobert-1](https://github.com/crobert-1), [@atoulme](https://github.com/atoulme), [@ebrdarSplunk](https://github.com/ebrdarSplunk), [@XSAM](https://github.com/XSAM), [@akshays-19](https://github.com/akshays-19), [@sv-splunk](https://github.com/sv-splunk), [@splunk-shanu](https://github.com/splunk-shanu)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/oracledbreceiver)

## Supported Telemetry

![Logs](https://img.shields.io/badge/logs-development-blue) ![Metrics](https://img.shields.io/badge/metrics-alpha-green)

## 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](#primary-configuration-option) and [Secondary](#secondary-configuration-option) 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](https://github.com/sijms/go-ora) for full connection string options.

Example:

```yaml theme={null}
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:

```yaml theme={null}
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.

## Resource attributes

`server.address` and `server.port` identify the monitored Oracle instance and are emitted by default.
When the receiver connects over loopback (for example `datasource: oracle://otel:password@localhost:51521/XE`
or `endpoint: 127.0.0.1:51521`), `server.address` reports the host name of the machine running the
collector, because the monitored instance is co-located with it and `localhost` would otherwise be
shared by every monitored host. `server.port` defaults to `1521` when the connection string omits it.
`service.instance.id` uses the same resolution and is reported as `server.address:server.port/service`.
`host.name` is unaffected and keeps reporting the configured target.

A `datasource` that is not in `oracle://user:password@host:port/service` form — a TNS descriptor, or
an Easy Connect string without the `oracle://` prefix — carries no host the receiver can read. In
that case `server.address` is omitted rather than guessed, `server.port` falls back to `1521`, and
`service.instance.id` reports `unknown:1521`. Note that the driver does not currently connect with
those forms either, so prefer the full `oracle://` datasource or the `endpoint` option, both of
which always populate the server attributes.

To stop emitting the server attributes, disable them individually:

```yaml theme={null}
receivers:
  oracledb:
    resource_attributes:
      server.address:
        enabled: false
      server.port:
        enabled: false
```

See [documentation.md](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/oracledbreceiver/documentation.md) for the full list of resource attributes.

## Permissions

### Instance detection

These grants are required to populate the `oracle.db.version`, `oracle.db.edition`,
`oracle.db.role`, `oracle.db.open_mode`, and `oracle.db.pdb` resource attributes.
Detection is best-effort; failures are logged at warn level and the receiver continues.

```sql theme={null}
GRANT SELECT ON V_$INSTANCE TO <username>;
GRANT SELECT ON V_$DATABASE TO <username>;
```

> **Note:** `sys_context('USERENV', ...)` queries against `DUAL` require no
> additional grant and are available to all database users.

### Hosting type detection (Oracle >=19c only)

These grants are required to populate the `oracle.db.hosting_type` resource attribute.
Only applies to Oracle 19c and later. Detection is best-effort; failures are logged at
warn level and the receiver continues.

```sql theme={null}
GRANT SELECT ON V_$DATAFILE TO <username>;
GRANT SELECT ON V_$PDBS TO <username>;        -- OCI detection, connected to PDB only
GRANT SELECT ON CDB_SERVICES TO <username>;   -- OCI confirmation, connected to PDB only
```

### Metrics collection

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

```sql theme={null}
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 V_$OSSTAT 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>;
GRANT SELECT ON V_$SGAINFO TO <username>;
```

### ASM metrics

Grants required for ASM metrics.

```sql theme={null}
GRANT SELECT ON V_$ASM_DISKGROUP_STAT TO <username>;
GRANT SELECT ON V_$ASM_DISK_STAT TO <username>;
```

### Per-PDB metrics (CDB multitenant deployments)

When connected to a CDB root (Oracle 12c+), the receiver can collect per-PDB metrics
by opting in to the `oracle.db.pdb` attribute. The monitoring user needs SELECT on
these views (container-wide):

```sql theme={null}
GRANT SELECT ON V_$CON_SYSSTAT TO <username> CONTAINER=ALL;
GRANT SELECT ON V_$CON_SYSMETRIC TO <username> CONTAINER=ALL;
GRANT SELECT ON V_$CONTAINERS TO <username> CONTAINER=ALL;
GRANT SELECT ON CDB_TABLESPACE_USAGE_METRICS TO <username> CONTAINER=ALL;
GRANT SELECT ON CDB_TABLESPACES TO <username> CONTAINER=ALL;
GRANT SELECT ON CDB_DATA_FILES TO <username> CONTAINER=ALL;  -- only needed for oracledb.tablespace.limit
```

Users who already hold `SELECT_CATALOG_ROLE` (commonly granted to monitoring
accounts) inherit SELECT on these views and don't need the explicit grants above.

If the required access isn't present, the receiver detects this at startup and
falls back to the single-container query set, emitting instance-wide metrics
just as it did before per-PDB support was added. Existing CDB deployments
upgrading without adding new grants continue to work unchanged.

### Events collection

The following grants are required for event collection. All five event types
(`db.server.query_sample`, `db.server.top_query`, `db.server.session.wait_sample`,
`db.server.top_procedure`, `db.server.query_plan`) are disabled by default and must be explicitly
enabled in configuration.

#### All events (shared requirements)

These grants are used by all event types for session context and PDB namespace resolution:

```sql theme={null}
GRANT SELECT ON V_$SESSION TO <username>;
GRANT SELECT ON V_$CONTAINERS TO <username>;     -- PDB/container name (DB_NAMESPACE attribute)
```

#### `db.server.query_sample`

Captures currently executing queries and blocking/locking session information:

```sql theme={null}
GRANT SELECT ON V_$SQL TO <username>;            -- SQL text and plan hash
GRANT SELECT ON V_$LOCK TO <username>;           -- Lock type and mode for blocked sessions
GRANT SELECT ON DBA_OBJECTS TO <username>;       -- Blocked object owner and name
GRANT SELECT ON DBA_PROCEDURES TO <username>;    -- Stored procedure metadata (PL/SQL entry point)
```

#### `db.server.top_query`

Captures the most expensive queries by elapsed time with execution plan details:

```sql theme={null}
GRANT SELECT ON V_$SQL TO <username>;                    -- Query metrics and text
GRANT SELECT ON V_$SQL_PLAN_STATISTICS_ALL TO <username>; -- Execution plan details
GRANT SELECT ON DBA_PROCEDURES TO <username>;            -- Stored procedure metadata
```

> \[!NOTE]
> In the SQL query plan details, the `LAST_*`, `OUTPUT_ROWS`, and `STARTS` columns are
> populated only when Oracle is configured to collect execution plan statistics (for example,
> `STATISTICS_LEVEL=ALL` or the `GATHER_PLAN_STATISTICS` hint). Otherwise, these fields will
> be NULL or empty. Configuring this Oracle instrumentation may introduce additional runtime
> overhead. Enable it only if you need these runtime execution statistics for query
> performance analysis.

```sql theme={null}
ALTER SYSTEM SET statistics_level = ALL;
```

#### `db.server.query_plan`

By default, `db.server.top_query` carries the query's execution plan in its `oracledb.query_plan`
attribute. A plan is a JSON payload holding one entry per plan step, so it can dominate the record it
travels on. Enabling `db.server.query_plan` isolates the plan on a record of its own, where it can be
filtered, routed or dropped independently of the query statistics, and where an oversized plan does
not take those statistics with it when a batcher splits by size.

`db.server.top_query` is then emitted **without** its `oracledb.query_plan` attribute, and the plan
itself is reported on `db.server.query_plan`, joined back to its cursor via `oracledb.sql_id` +
`oracledb.child_number` + `oracledb.child_address`, with `oracledb.plan_hash_value` identifying the
plan and `db.namespace` the database it came from. A cursor with no rows in
`V$SQL_PLAN_STATISTICS_ALL` produces no `db.server.query_plan` record. Leaving
`db.server.query_plan` disabled preserves the previous behavior exactly.

`db.server.query_plan` is sourced from the same collection as `db.server.top_query` and only splits
the plan out of it, so it needs no grants of its own, and enabling it without `db.server.top_query`
is a configuration error.

#### `db.server.session.wait_sample`

Captures per-session wait event statistics from `V$SESSION_EVENT`:

```sql theme={null}
GRANT SELECT ON V_$SESSION_EVENT TO <username>;  -- Wait event names, counts, and durations
```

#### `db.server.top_procedure`

Captures aggregated performance metrics for stored procedures, derived by grouping `V$SQL` by
`PROGRAM_ID` and joining to `DBA_PROCEDURES`. Correlates with `db.server.top_query` and
`db.server.query_sample` via the `oracledb.procedure_id` attribute:

```sql theme={null}
GRANT SELECT ON V_$SQL TO <username>;            -- Aggregated procedure execution/resource stats
GRANT SELECT ON DBA_PROCEDURES TO <username>;    -- Stored procedure metadata (owner, name, type)
```

Cumulative counters are converted to per-scrape deltas. Rows are fetched up to
`max_procedure_sample_count`, ranked in the collector by elapsed-time delta, and truncated to
`top_procedure_count`. The fetch limit is deliberately larger than the reported set: ranking on
deltas over a wider pool is what lets a procedure that is hot only in the current interval —
newly deployed, a month-end batch, something that just started misbehaving — reach the report
even though its lifetime totals are modest.

A negative delta on any of the summed resource counters means a cursor aged out of the shared
pool, so the row is discarded rather than emitted as a bogus value.

> \[!NOTE]
> Oracle exposes no per-procedure cumulative execution counter, so
> `oracledb.procedure_execution_count` is derived as the *minimum* statement execution count
> across the procedure's cached statements. This is best effort: a newly loaded child cursor
> starts at 1 and pulls the minimum down, and a statement in a branch that did not run holds it
> flat. The receiver therefore treats this counter separately from the resource counters — it is
> clamped to 0 instead of discarding the row. Resource counters (CPU, elapsed time, reads, writes, rows) are
> summed across the procedure's statements and are not subject to this caveat.

See "CDB-root connections and container-scoped dictionary views" below for how this event
behaves on a CDB-root connection.

### CDB-root connections and container-scoped dictionary views

`DBA_*` dictionary views only expose the container you are connected to, while the `V$` views
report rows for **every** container. Object ids are only unique within a container, so from a
CDB root a dictionary join on object id alone is not just incomplete — it can attribute a PDB
row to an unrelated root object that happens to share the id.

When connected to a CDB root, the receiver therefore reads the `CDB_*` equivalents and matches
on `CON_ID` as well as the object id:

| Event | Affected lookup | Using `DBA_*` from a CDB root |
| - | - | - |
| `db.server.top_query` | `CDB_PROCEDURES`, plus `CON_ID` in the `PROCEDURE_EXECUTIONS` grouping | wrong or empty `procedure_name`; execution counts merged across PDBs |
| `db.server.top_procedure` | `CDB_PROCEDURES` | wrong or empty `procedure_name`; procedures merged across PDBs |
| `db.server.query_sample` | `CDB_PROCEDURES`, `CDB_OBJECTS` | wrong or empty `procedure_name` and blocked-object owner/name |

`top_query` and `top_procedure` only need `CDB_PROCEDURES`; `query_sample` additionally needs
`CDB_OBJECTS`. The two grants are probed independently at startup, so a CDB root with only
`CDB_PROCEDURES` still gets container-qualified `top_query`/`top_procedure` results even while
`query_sample` degrades to the `DBA_*` view:

```sql theme={null}
GRANT SELECT ON CDB_PROCEDURES TO <username> CONTAINER=ALL;
GRANT SELECT ON CDB_OBJECTS TO <username> CONTAINER=ALL;
```

Users holding `SELECT_CATALOG_ROLE` inherit both and need no explicit grant. Non-CDB and
direct-PDB connections continue to use the `DBA_*` views and need nothing extra.

> \[!NOTE]
> Each grant is probed once at startup. If a grant is missing, the receiver logs a warning and
> falls back to the `DBA_*` view for the event(s) that need it, so events keep flowing with the
> container-attribution limitation described above rather than failing with `ORA-00942`. This
> mirrors how per-PDB metrics already degrade when their grants are absent — no upgrade requires
> new grants to keep working.

#### Combined grant statement

For convenience, the complete set of grants required to enable all events:

```sql theme={null}
GRANT SELECT ON V_$SESSION TO <username>;
GRANT SELECT ON V_$SESSION_EVENT TO <username>;
GRANT SELECT ON V_$SQL TO <username>;
GRANT SELECT ON V_$SQL_PLAN_STATISTICS_ALL TO <username>;
GRANT SELECT ON V_$LOCK TO <username>;
GRANT SELECT ON V_$CONTAINERS TO <username>;
GRANT SELECT ON DBA_OBJECTS TO <username>;
GRANT SELECT ON DBA_PROCEDURES TO <username>;
-- Optional, CDB-root connections only (see "CDB-root connections" above):
GRANT SELECT ON CDB_PROCEDURES TO <username> CONTAINER=ALL;
GRANT SELECT ON CDB_OBJECTS TO <username> CONTAINER=ALL;
```

### AWS RDS Oracle grants

Run the following as the master/admin user using `rdsadmin.rdsadmin_util.grant_sys_object` to grant permissions on the required views.
The following grants cover all metrics and events collected by this receiver:

```sql theme={null}
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SYSMETRIC',      '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$CON_SYSMETRIC',  '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$CONTAINERS',     '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SESSION',        '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SESSION_EVENT',  '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SYSSTAT',        '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$CON_SYSSTAT',    '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$OSSTAT',         '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SGAINFO',        '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SQL',            '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SQL_PLAN',       '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SQL_PLAN_STATISTICS_ALL', '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$PARAMETER',      '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$ROWCACHE',       '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$RESOURCE_LIMIT', '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$LOCK',           '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$PROCESS',        '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$TRANSACTION',    '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$DATABASE',       '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$INSTANCE',       '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$DATAFILE',       '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$PDBS',           '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_DATA_FILES',               '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_FREE_SPACE',               '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_RECYCLEBIN',               '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_TABLESPACES',              '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_TABLESPACE_USAGE_METRICS', '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_PROCEDURES',               '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_OBJECTS',                  '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('CDB_TABLESPACE_USAGE_METRICS', '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('CDB_TABLESPACES',              '<username>', 'SELECT', false);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('CDB_SERVICES',                 '<username>', 'SELECT', false);
GRANT CREATE SESSION TO <username>;
```

### Direct-PDB connections

When the receiver connects directly to a PDB (including all AWS RDS Oracle deployments),
`oracledb.transactions.limit` and `oracledb.dml_locks.limit` are derived from
`v$parameter` instead of `v$resource_limit`, which is unavailable in PDB context.
When Oracle auto-tunes these parameters, `v$parameter` reports the computed value
(for example, `354` or `1416`) rather than `-1` (unlimited) as a root or standalone
connection would. A direct-PDB deployment and a CDB-root deployment of the same instance can therefore report different values for these metrics.

## Enabling metrics.

See [documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/oracledbreceiver/documentation.md).

You can enable or disable selective metrics.

Example:

```yaml theme={null}
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.

```yaml theme={null}
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
      db.server.session.wait_sample:
        enabled: true
      db.server.top_procedure:
        enabled: true
      db.server.query_plan:                      # reports the execution plan on its own event, off 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
      allowed_comment_keys: [application]        # keys to extract from leading SQL comments (see SQL Comment Extraction below)
    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.
      allowed_comment_keys: [application]        # keys to extract from leading SQL comments (see SQL Comment Extraction below)
    session_wait_event_collection:               # this collection exports per-session wait event statistics from v$session_event as logs
      max_rows_per_query: 100                    # the maximum number of session wait event rows to be reported                 
    top_procedure_collection:                # this collection exports aggregated stored procedure performance metrics as logs
      max_procedure_sample_count: 1000           # maximum number of rows fetched from db to rank the top N by delta
      top_procedure_count: 250                   # The maximum number of procedures (N) for which the metrics would be reported
      collection_interval: 60s                   # collection interval for procedure metrics collection specifically
```

## SQL Comment Extraction

When the `db.server.query_sample` and/or `db.server.top_query` events are enabled, the receiver can
extract key-value pairs from leading SQL block comments (`/* key=value */`) and emit them as the
`db.query.comment_tags` attribute on the corresponding logs.

This behavior is controlled by the `allowed_comment_keys` option, which can be set independently
under `top_query_collection` and `query_sample_collection`:

* `allowed_comment_keys` (default = `[]`): A list of comment keys to extract. For each enabled
  collection, only keys present in this allowlist are extracted from the leading SQL comment and
  included (as comma-separated `key=value` pairs) in the `db.query.comment_tags` attribute.

Extraction is disabled unless explicitly configured:

* When `allowed_comment_keys` is empty or unset, no comments are extracted.
* Only keys included in the allowlist are emitted; all other comment keys are ignored.
* Only leading block comments are parsed; comments elsewhere in the query are ignored.

Example:

```yaml theme={null}
receivers:
  oracledb:
    datasource: "oracle://otel:password@localhost:51521/XE"
    events:
      db.server.query_sample:
        enabled: true
      db.server.top_query:
        enabled: true
    top_query_collection:
      allowed_comment_keys: [application, team]
    query_sample_collection:
      allowed_comment_keys: [application, team]
```

Given a query such as `/* application=exampleApp,team=payments */ SELECT * FROM users`, the emitted
log record will include `db.query.comment_tags` set to `application=exampleApp,team=payments`. When multiple
keys are extracted, they are emitted as a comma-separated list of `key=value` pairs.

See [documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/oracledbreceiver/documentation.md) for details on the `db.query.comment_tags` attribute.

## Metrics

| Metric Name | Description | Unit | Type | Attributes |
| - | - | - | - | - |
| ❌ `oracledb.asm.disk.errors` | Count of I/O errors on an ASM disk. | \{error} | Counter | oracledb.asm.disk\_group.name, oracledb.asm.disk.name, disk.io.direction |
| ❌ `oracledb.asm.disk_group.capacity` | Total space in an ASM diskgroup. | By | Gauge | oracledb.asm.disk\_group.name |
| ❌ `oracledb.asm.disk_group.free` | Free space in an ASM diskgroup. | By | Gauge | oracledb.asm.disk\_group.name |
| ❌ `oracledb.asm.disk_group.offline_disks` | Count of disks currently offline within an ASM diskgroup. | \{disk} | Gauge | oracledb.asm.disk\_group.name |
| ❌ `oracledb.asm.disk_group.usable_free` | Free space that can safely be used for files after accounting for ASM redundancy and required mirror recovery capacity. | By | Gauge | oracledb.asm.disk\_group.name |
| ❌ `oracledb.buffer.inspected` | Number of buffers inspected from the end of the LRU queue while a process searched for a reusable buffer, grouped by buffer state. | \{buffer} | Counter | oracledb.buffer.state |
| ❌ `oracledb.buffer.requests` | Number of times a reusable or free buffer was requested to create or load a block. | \{request} | Counter | |
| ❌ `oracledb.buffer_cache.block.changes` | Number of changes that were part of an update or delete operation made to blocks in the buffer cache. | \{change} | Counter | |
| ❌ `oracledb.buffer_cache.block.changes.rate` | Rate of changes applied to blocks in the buffer cache. | \{change}/s | Gauge | oracle.db.pdb |
| ❌ `oracledb.buffer_cache.block.gets` | Number of current-mode block gets satisfied from the buffer cache. Distinct from oracledb.db\_block\_gets, which counts all current-mode block gets requested regardless of where they are satisfied. | \{get} | Counter | |
| ❌ `oracledb.buffer_cache.utilization` | Fraction of logical reads served from the buffer cache without physical I/O, as computed by Oracle V\$SYSMETRIC (% (LogRead - PhyRead)/LogRead). | % | Gauge | oracle.db.pdb |
| ❌ `oracledb.call.count` | Total count of calls issued to the database. | \{call} | Counter | oracledb.call.type |
| ❌ `oracledb.call.recursive.cpu.time` | Total CPU time spent on recursive (internal) calls. | s | Counter | |
| ❌ `oracledb.checkpoint.buffers` | Number of buffers written by the Database Writer (DBWR) for checkpoints. | \{buffer} | Counter | |
| ❌ `oracledb.checkpoint.completed` | Number of checkpoints completed by the Database Writer (DBWR). | \{checkpoint} | Counter | |
| ❌ `oracledb.consistent_gets` | Number of times a consistent read was requested for a block from the buffer cache. | \{get} | Counter | oracle.db.pdb |
| ❌ `oracledb.cpu.usage.rate` | CPU consumption rate, in CPU-seconds used per second. | 1 | Gauge | oracle.db.pdb |
| ✅ `oracledb.cpu_time` | Cumulative CPU time, in seconds | s | Counter | oracle.db.pdb |
| ❌ `oracledb.cursor.cache.hits` | Total count of session cursor cache hits, where an existing cached cursor is reused to avoid a soft parse. | \{hit} | Counter | |
| ❌ `oracledb.cursor.cache.size` | Number of cursors currently held in the session cursor cache. | \{cursor} | Gauge | |
| ❌ `oracledb.cursor.cache.utilization` | Percentage of cursor executions that reused a cursor in the session cursor cache. | % | Gauge | oracle.db.pdb |
| ❌ `oracledb.cursor.open` | Number of currently open cursors in the Oracle instance. | \{cursor} | Gauge | |
| ❌ `oracledb.cursor.open.rate` | Rate of cursors opened. | \{cursor}/s | Gauge | oracle.db.pdb |
| ❌ `oracledb.data_dictionary.hit_ratio` | Data dictionary cache hit ratio from v\$rowcache. | % | Gauge | |
| ❌ `oracledb.database.cpu.utilization` | Fraction of total database time spent on CPU, as computed by Oracle V\$SYSMETRIC (% Cpu/DB\_Time). | % | Gauge | oracle.db.pdb |
| ❌ `oracledb.database.wait.utilization` | Fraction of total database time spent waiting on I/O, locks, or latches, as computed by Oracle V\$SYSMETRIC (% Wait/DB\_Time). | % | Gauge | oracle.db.pdb |
| ❌ `oracledb.db.time` | Total wall-clock time spent in database calls. | s | Counter | oracledb.session.type |
| ❌ `oracledb.db_block_gets` | Number of times a current block was requested from the buffer cache. | \{get} | Counter | oracle.db.pdb |
| ❌ `oracledb.ddl_statements_parallelized` | Number of DDL statements that were executed in parallel | \{statement} | Counter | oracle.db.pdb |
| ✅ `oracledb.dml_locks.limit` | Maximum limit of active DML (Data Manipulation Language) locks, -1 if unlimited. | \{lock} | Gauge | |
| ✅ `oracledb.dml_locks.usage` | Current count of active DML (Data Manipulation Language) locks. | \{lock} | Gauge | |
| ❌ `oracledb.dml_statements_parallelized` | Number of DML statements that were executed in parallel | \{statement} | Counter | oracle.db.pdb |
| ❌ `oracledb.enqueue.deadlocks.rate` | Rate of enqueue deadlocks. | \{deadlock}/s | Gauge | oracle.db.pdb |
| ❌ `oracledb.enqueue.operations` | Total count of enqueue (lock) operations. | \{operation} | Counter | oracledb.enqueue.type |
| ❌ `oracledb.enqueue.timeouts.rate` | Rate of enqueue timeouts. | \{timeout}/s | Gauge | oracle.db.pdb |
| ✅ `oracledb.enqueue_deadlocks` | Total number of deadlocks between table or row locks in different sessions. | \{deadlock} | Counter | oracle.db.pdb |
| ✅ `oracledb.enqueue_locks.limit` | Maximum limit of active enqueue locks, -1 if unlimited. | \{lock} | Gauge | |
| ✅ `oracledb.enqueue_locks.usage` | Current count of active enqueue locks. | \{lock} | Gauge | |
| ✅ `oracledb.enqueue_resources.limit` | Maximum limit of active enqueue resources, -1 if unlimited. | \{resource} | Gauge | |
| ✅ `oracledb.enqueue_resources.usage` | Current count of active enqueue resources. | \{resource} | 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. | \{deadlock} | Counter | oracle.db.pdb |
| ❌ `oracledb.execution.utilization` | Fraction of executions that did not require a parse, as computed by Oracle V\$SYSMETRIC (% (ExecWOParse/TotalExec)). High values indicate good cursor reuse. | % | Gauge | oracledb.parse.type, oracle.db.pdb |
| ✅ `oracledb.executions` | Total number of calls (user and recursive) that executed SQL statements | \{execution} | Counter | oracle.db.pdb |
| ❌ `oracledb.executions.rate` | Rate of SQL statement executions. | \{execution}/s | Gauge | oracle.db.pdb |
| ❌ `oracledb.gc.current_block.time` | Cumulative time spent transferring current blocks between instances over RAC cache fusion. | s | Counter | network.io.direction |
| ✅ `oracledb.hard_parses` | Number of hard parses | \{parse} | Counter | oracle.db.pdb |
| ❌ `oracledb.hard_parses.rate` | Rate of hard parses. | \{parse}/s | Gauge | oracle.db.pdb |
| ❌ `oracledb.host.cpu.usage.rate` | Host CPU consumption rate across all cores, in CPU-seconds used per second. | 1 | Gauge | |
| ❌ `oracledb.host.cpu.utilization` | Fraction of host CPU time in use, as computed by Oracle V\$SYSMETRIC (% Busy/(Idle+Busy)). | % | Gauge | oracle.db.pdb |
| ❌ `oracledb.io.requests.rate` | Rate of I/O requests issued by the database. | \{request}/s | Gauge | |
| ❌ `oracledb.io.single_block.read.latency` | Average latency of a synchronous single-block read. | s | Gauge | |
| ❌ `oracledb.io.throughput.rate` | Rate of I/O bytes transferred by the database. | By/s | Gauge | |
| ❌ `oracledb.jvm.memory.committed` | Committed (total) size of Oracle's in-database JVM (OJVM) call heap. | By | Gauge | |
| ❌ `oracledb.jvm.memory.live` | Size of live objects in Oracle's in-database JVM (OJVM) call heap. | By | Gauge | |
| ❌ `oracledb.jvm.memory.used` | Used size of Oracle's in-database JVM (OJVM) call heap. | By | Gauge | |
| ❌ `oracledb.library_cache.utilization` | Fraction of library cache pin requests that found the object already cached, as computed by Oracle V\$SYSMETRIC (% Hits/Pins). | % | Gauge | oracle.db.pdb |
| ❌ `oracledb.lob.operations` | Total count of LOB (large object) I/O operations. | \{operation} | Counter | disk.io.direction |
| ❌ `oracledb.lock.time` | Cumulative time spent on transaction lock activity. | s | Counter | oracle.db.pdb, oracledb.session.type |
| ✅ `oracledb.logical_reads` | Number of logical reads | \{read} | Counter | oracle.db.pdb |
| ❌ `oracledb.logical_reads.rate` | Rate of logical reads performed by the database. | \{read}/s | Gauge | oracle.db.pdb |
| ❌ `oracledb.logons` | Number of logon operations | \{operation} | Counter | oracle.db.pdb |
| ❌ `oracledb.logons.rate` | Rate of logon operations. | \{logon}/s | Gauge | oracle.db.pdb |
| ❌ `oracledb.os.swaps` | Number of OS swap operations. | \{swap} | 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 | \{execution} | Counter | oracle.db.pdb |
| ❌ `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 | \{execution} | Counter | oracle.db.pdb |
| ❌ `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 | \{execution} | Counter | oracle.db.pdb |
| ❌ `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 | \{execution} | Counter | oracle.db.pdb |
| ❌ `oracledb.parallel_operations_downgraded_to_serial` | Number of times parallel execution was requested but execution was serial because of insufficient parallel execution servers | \{execution} | Counter | oracle.db.pdb |
| ❌ `oracledb.parallel_operations_not_downgraded` | Number of times parallel execution was executed at the requested degree of parallelism | \{execution} | Counter | oracle.db.pdb |
| ❌ `oracledb.parse.cpu.time` | Total CPU time spent on SQL parsing. | s | Counter | |
| ❌ `oracledb.parse.elapsed.time` | Total wall-clock time spent on SQL parsing. | s | Counter | |
| ❌ `oracledb.parse.rate` | Rate of parse operations per second broken down by result, as computed by Oracle V\$SYSMETRIC (e.g., Parse Failure Count Per Sec). | \{parse}/s | Gauge | oracledb.parse.result, oracle.db.pdb |
| ❌ `oracledb.parse.utilization` | Fraction of parse calls that were soft parses, as computed by Oracle V\$SYSMETRIC (% SoftParses/TotalParses). High values indicate good cursor reuse. | % | Gauge | oracle.db.pdb |
| ✅ `oracledb.parse_calls` | Total number of parse calls. | \{parse} | Counter | oracle.db.pdb |
| ❌ `oracledb.pga.cache.utilization` | Percentage of PGA work-area memory requests satisfied without spilling to temporary disk. | % | Gauge | |
| ✅ `oracledb.pga_memory` | Session PGA (Program Global Area) memory | By | Counter | oracle.db.pdb |
| ❌ `oracledb.physical_io.cache_writes` | Number of physical writes from the buffer cache to disk by DBWR. Sourced from v\$sysstat name physical writes from cache. | \{write} | Counter | oracle.db.pdb |
| ❌ `oracledb.physical_io.requests` | Number of physical I/O requests issued to storage. Sourced from v\$sysstat names physical read/write total IO requests (disk.io.block\_size=all) and physical read/write total multi block requests (disk.io.block\_size=multi). | \{request} | Counter | disk.io.direction, disk.io.block\_size, oracle.db.pdb |
| ❌ `oracledb.physical_io.requests.rate` | Rate of physical I/O requests issued to storage. | \{request}/s | Gauge | disk.io.direction, oracle.db.pdb |
| ❌ `oracledb.physical_io.transferred` | Total physical I/O bytes transferred between Oracle and storage. Sums across all data files. Sourced from v\$sysstat names physical read/write bytes (disk.io.type=buffered) and physical read/write total bytes (disk.io.type=total). | By | Counter | disk.io.direction, disk.io.type, oracle.db.pdb |
| ❌ `oracledb.physical_io.transferred.rate` | Rate of physical I/O bytes transferred between Oracle and storage. | By/s | Gauge | disk.io.direction, oracle.db.pdb |
| ❌ `oracledb.physical_operations.rate` | Rate of physical read and write operations performed by the database. | \{operation}/s | Gauge | disk.io.direction, oracle.db.pdb |
| ❌ `oracledb.physical_read_io_requests` | Number of read requests for application activity | \{request} | Counter | oracle.db.pdb |
| ✅ `oracledb.physical_reads` | Number of physical reads | \{read} | Counter | oracle.db.pdb |
| ❌ `oracledb.physical_reads_direct` | Number of reads directly from disk, bypassing the buffer cache | \{read} | Counter | oracle.db.pdb |
| ❌ `oracledb.physical_write_io_requests` | Number of write requests for application activity | \{request} | Counter | oracle.db.pdb |
| ❌ `oracledb.physical_writes` | Number of physical writes | \{write} | Counter | oracle.db.pdb |
| ❌ `oracledb.physical_writes_direct` | Number of writes directly to disk, bypassing the buffer cache | \{write} | Counter | oracle.db.pdb |
| ✅ `oracledb.processes.limit` | Maximum limit of active processes, -1 if unlimited. | \{process} | Gauge | |
| ✅ `oracledb.processes.usage` | Current count of active processes. | \{process} | Gauge | |
| ❌ `oracledb.queries_parallelized` | Number of SELECT statements executed in parallel | \{query} | Counter | oracle.db.pdb |
| ❌ `oracledb.recovery.blocks` | Number of blocks read during instance or media recovery. | \{block} | Counter | |
| ❌ `oracledb.recycle_bin.limit` | Total size of the recycle bin. | By | Gauge | |
| ❌ `oracledb.redo.blocks` | Number of redo blocks moved between the redo log and storage. | \{block} | Counter | disk.io.direction |
| ❌ `oracledb.redo.operations` | Number of redo I/O operations. | \{operation} | Counter | disk.io.direction |
| ❌ `oracledb.redo.requests` | Number of times a process requested space in the redo log buffer and had to wait. | \{request} | Counter | oracledb.redo.request.type |
| ❌ `oracledb.redo.retries` | Number of times a process waited and retried to allocate space in the redo buffer. | \{retry} | Counter | oracledb.redo.retry.type |
| ❌ `oracledb.redo.size` | Amount of redo generated. | By | Counter | |
| ❌ `oracledb.redo.size.rate` | Rate of redo bytes generated by the database. | By/s | Gauge | oracle.db.pdb |
| ❌ `oracledb.redo.time` | Time spent in each phase of the redo pipeline. | s | Counter | oracledb.redo.type |
| ❌ `oracledb.redo_allocation.utilization` | Fraction of redo allocations that succeeded without space contention, as computed by Oracle V\$SYSMETRIC (% (#Redo - RedoSpaceReq)/#Redo). | % | Gauge | oracle.db.pdb |
| ❌ `oracledb.scan.count` | Total count of scan operations. | \{operation} | Counter | oracledb.scan.type, oracledb.scan.mode |
| ❌ `oracledb.scan.table.rows` | Total number of rows returned by full-table scans. | \{row} | Counter | |
| ❌ `oracledb.session.average` | Average number of sessions over the metric interval. | \{session} | Gauge | session\_status, oracle.db.pdb |
| ❌ `oracledb.session.stored_procedure.memory` | Memory currently allocated for stored procedures in the session. | By | Gauge | oracle.db.pdb |
| ❌ `oracledb.session.wait.time` | Cumulative time sessions spent in waits. | s | Counter | oracledb.session.wait.state, oracle.db.pdb |
| ❌ `oracledb.session.waits` | Cumulative number of waits across sessions. | \{wait} | Counter | oracledb.session.wait.state, oracle.db.pdb |
| ✅ `oracledb.sessions.limit` | Maximum limit of active sessions, -1 if unlimited. | \{session} | Gauge | |
| ✅ `oracledb.sessions.usage` | Count of active sessions. | \{session} | Gauge | session\_type, session\_status, oracle.db.pdb |
| ❌ `oracledb.sga.limit` | Maximum size of the System Global Area (SGA). | By | Gauge | |
| ❌ `oracledb.sga.usage` | Size of each component of the System Global Area (SGA). | By | Gauge | oracledb.sga.component.name |
| ❌ `oracledb.shared_pool.utilization` | Fraction of the shared pool that is currently free, as computed by Oracle V\$SYSMETRIC (% Free/Total). Low values indicate shared pool pressure. | % | Gauge | oracle.db.pdb |
| ❌ `oracledb.smon.posts` | Number of times SMON was posted to perform recovery. | \{post} | Counter | oracledb.smon.type |
| ❌ `oracledb.sort.operations` | Total count of sort operations. | \{operation} | Counter | oracledb.sort.type |
| ❌ `oracledb.sort.ratio` | Fraction of sorts performed in memory vs disk, as computed by Oracle V\$SYSMETRIC (% MemSort/(MemSort + DiskSort)). Low values indicate PGA memory pressure. | 1 | Gauge | oracledb.sort.type, oracle.db.pdb |
| ❌ `oracledb.sort.rows` | Total number of rows sorted across all sort operations. | \{row} | Counter | |
| ❌ `oracledb.sql_service.response.duration` | Average SQL service response time in seconds, converted from centiseconds as reported by Oracle V\$SYSMETRIC (CentiSeconds Per Call). | s | Gauge | oracle.db.pdb |
| ❌ `oracledb.sqlnet.io.transferred` | Bytes transferred via SQL*Net between Oracle and clients/dblinks. Sourced from v\$sysstat names bytes received/sent via SQL*Net from/to client/dblink. | By | Counter | network.io.direction, destination.type, oracle.db.pdb |
| ❌ `oracledb.storage.usage` | Used database storage size from dba\_data\_files and dba\_free\_space. | By | Gauge | |
| ❌ `oracledb.storage.utilization` | Fraction of allocated database storage that is used. | 1 | Gauge | |
| ❌ `oracledb.system.cpu.count` | Number of CPUs or processors available to the Oracle server, as reported by the operating system. | \{cpu} | Gauge | |
| ❌ `oracledb.system.memory.limit` | Total number of bytes of physical memory on the host running the Oracle server. | By | Gauge | |
| ❌ `oracledb.system.process.count` | Current number of processes that are either running or in the ready state, waiting to be selected by the operating-system scheduler to run. | \{process} | Gauge | |
| ❌ `oracledb.tablespace.limit` | Maximum autoextend size of tablespace in bytes. Returns 0 for temporary tablespaces and tablespaces without autoextend enabled. | By | Gauge | tablespace\_name, oracle.db.pdb |
| ❌ `oracledb.tablespace.status` | Current status of tablespaces, broken down by state. A timeseries is produced for every possible value of oracledb.tablespace.state; the value is 1 for a tablespace's current state, and 0 for all other states. | \{tablespace} | UpDownCounter | tablespace\_name, oracledb.tablespace.state, oracle.db.pdb |
| ❌ `oracledb.tablespace.utilization` | Fraction of tablespace currently in use, expressed as a value between 0 and 1. | 1 | Gauge | tablespace\_name, oracle.db.pdb |
| ✅ `oracledb.tablespace_size.limit` | Maximum size of tablespace in bytes, -1 if unlimited. | By | Gauge | tablespace\_name, oracle.db.pdb |
| ✅ `oracledb.tablespace_size.usage` | Used tablespace in bytes. | By | Gauge | tablespace\_name, oracle.db.pdb |
| ❌ `oracledb.transaction.response.time` | Average response time per transaction. | s | Gauge | oracle.db.pdb |
| ❌ `oracledb.transaction.rollbacks` | Total number of transactions rolled back. | \{rollback} | Counter | oracle.db.pdb |
| ✅ `oracledb.transactions.limit` | Maximum limit of active transactions, -1 if unlimited. | \{transaction} | Gauge | |
| ❌ `oracledb.transactions.rate` | Rate of user transactions. | \{transaction}/s | Gauge | oracledb.transaction.type, oracle.db.pdb |
| ✅ `oracledb.transactions.usage` | Current count of active transactions. | \{transaction} | 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. | \{commit} | Counter | oracle.db.pdb |
| ✅ `oracledb.user_rollbacks` | Number of times users manually issue the ROLLBACK statement or an error occurs during a user's transactions | 1 | Counter | oracle.db.pdb |

## Attributes

| Attribute Name | Description | Type | Values |
| - | - | - | - |
| `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.comment_tags` | Filtered SQL query comments extracted from leading block comments. Contains comma-separated key=value pairs for keys specified in allowed\_comment\_keys configuration. Used for correlation with APM traces. | 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 | |
| `destination.type` | Type of the SQL\*Net destination endpoint (client application or remote database link). | string | `client`, `dblink` |
| `disk.io.block_size` | Multi-block vs single-block (all) I/O request grouping. | string | `all`, `multi` |
| `disk.io.direction` | Direction of the storage I/O operation. | string | `read`, `write` |
| `disk.io.type` | Whether the I/O bytes are buffered (cache-mediated) or total (raw transfer count). | string | `buffered`, `total` |
| `network.io.direction` | Direction of the network transfer. | string | `receive`, `transmit` |
| `network.peer.address` | IP address of the peer client. | string | |
| `network.peer.port` | TCP port used by the peer client. | int | |
| `oracle.db.pdb` | The name of the pluggable database (PDB) the data point belongs to. Emit one data point per PDB on CDB-root connections and one per direct-PDB connection; empty otherwise. When disabled, per-PDB collection is skipped and each metric emits a single instance-wide data point. | string | |
| `oracle.db.service` | The Oracle service name associated with the database connection. | string | |
| `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.asm.disk.name` | The name of the ASM disk. | string | |
| `oracledb.asm.disk_group.name` | The name of the ASM diskgroup. | string | |
| `oracledb.blocking.blocker.root_sid` | The session ID (SID) of the root/head blocker at the top of the blocking chain. Empty string when there is no blocking. | string | |
| `oracledb.blocking.blocker.sid` | The session ID (SID) of the immediate blocker of this session. Empty string when the session is not blocked. | string | |
| `oracledb.blocking.blocker.state` | The status of the blocking session relationship (e.g. VALID, NOT IN WAIT, GLOBAL, NO HOLDER, UNKNOWN). | string | |
| `oracledb.blocking.lock.mode` | The lock mode being requested by the blocked session (e.g., ROW SHARE, ROW EXCLUSIVE, SHARE, SHARE ROW EXCLUSIVE, EXCLUSIVE). Empty when not waiting on a lock. | string | |
| `oracledb.blocking.lock.type` | The type of enqueue lock the session is waiting on, extracted from the wait event (e.g., TX for row lock, TM for table lock). Empty when not waiting on a lock. | string | |
| `oracledb.blocking.object.name` | The name of the database object the session is waiting to lock. Empty when no object lock wait is active. | string | |
| `oracledb.blocking.object.owner` | The owner (schema) of the database object the session is waiting to lock. Empty when no object lock wait is active. | string | |
| `oracledb.blocking.start_time` | Estimated UTC timestamp of when the blocking wait began, derived from SYSDATE - SECONDS\_IN\_WAIT. RFC3339 format. | string | |
| `oracledb.blocking.wait_duration` | The number of seconds this session has been waiting for the current wait event. | int | |
| `oracledb.buffer.state` | The state of a buffer encountered while inspecting the LRU queue for a reusable buffer (free = a reusable buffer that was skipped; dirty = a dirty buffer found). | string | `free`, `dirty` |
| `oracledb.buffer_gets` | Number of logical reads (i.e., buffer cache accesses) performed by a query (reporting delta). | int | |
| `oracledb.call.type` | Type of call reported by Oracle. | string | `recursive`, `user` |
| `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.enqueue.type` | Type of enqueue (lock) operation reported by Oracle. | string | `conversions`, `releases`, `requests`, `timeouts`, `waits` |
| `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.parse.result` | Result of a parse operation (e.g., failure). | string | `failure` |
| `oracledb.parse.type` | Type of parse operation (e.g., soft). | string | `soft` |
| `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.first_load` | Time at which the plan was first loaded into the library cache, in ISO 8601 format (UTC). | string | |
| `oracledb.plan.last_load` | Plan load time, in ISO 8601 format (UTC). | string | |
| `oracledb.plan_hash_value` | Numeric representation of the execution plan. | string | |
| `oracledb.procedure.first_load_time` | Earliest load time across the procedure's cached statements, in ISO 8601 format (UTC). | string | |
| `oracledb.procedure.last_active_time` | The most recent time any of the procedure's cached statements were active, in ISO 8601 format (UTC). | string | |
| `oracledb.procedure.schema.name` | The schema (owner) of the stored procedure or function. | 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.started` | The timestamp when the SQL statement started execution, in ISO 8601 format (UTC). | string | |
| `oracledb.query.wait_time` | The wait time in seconds. If the session is currently waiting, the value is the time spent waiting in the current wait. Returns 0 if the session is not currently waiting. | double | |
| `oracledb.query_plan` | The query execution plan used by the Oracle database. | string | |
| `oracledb.redo.request.type` | The type of redo log buffer space request. | string | `log_space` |
| `oracledb.redo.retry.type` | The type of redo buffer allocation retry. | string | `buffer_allocation` |
| `oracledb.redo.type` | The phase of the redo pipeline that a redo time measurement is attributed to. | string | `write`, `log_space_wait`, `sync` |
| `oracledb.rows_processed` | The total number of rows that a query has read, returned, or affected during its execution (reporting delta). | int | |
| `oracledb.scan.mode` | Execution mode of the scan reported by Oracle. | string | `direct_read`, `full`, `long_tables`, `rowid_ranges` |
| `oracledb.scan.type` | Type of scan operation reported by Oracle. | string | `index_fast_full`, `table` |
| `oracledb.schemaname` | Oracle schema under which SQL statements are being executed | string | |
| `oracledb.serial` | Serial number associated with a session. | string | |
| `oracledb.session.duration` | The total time in seconds that the session has been connected. | double | |
| `oracledb.session.started` | The timestamp when the session logged on, in ISO 8601 format (UTC). | string | |
| `oracledb.session.type` | Class of session the activity is attributed to. | string | `background`, `foreground` |
| `oracledb.session.wait.state` | Whether the session wait time/count is for idle or non-idle wait events. | string | `non_idle` |
| `oracledb.sga.component.name` | Name of the SGA component. | string | `buffer_cache`, `data_transfer_cache`, `fixed_sga`, `in_memory_area`, `java_pool`, `large_pool`, `redo_buffers`, `shared_io_pool`, `shared_pool`, `streams_pool` |
| `oracledb.sid` | ID of the Oracle Server session. | string | |
| `oracledb.smon.type` | Type of recovery SMON was posted to perform. | string | `instance`, `transaction` |
| `oracledb.sort.type` | Type of sort operation (e.g., memory, disk). | string | `disk`, `memory` |
| `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.tablespace.state` | Tablespace state as reported by Oracle (e.g. online, offline, read only) | string | `online`, `offline`, `read only` |
| `oracledb.transaction.type` | The type of user transaction. | string | `commit`, `rollback` |
| `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.count` | Number of times the session has waited on the wait event. | int | |
| `oracledb.wait.duration` | Total time waited in seconds for the wait event. | double | |
| `oracledb.wait.timeouts` | Number of the session's waits on the wait event that timed out. | int | |
| `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 | ✅ |
| `oracle.db.edition` | The edition of the Oracle Database instance (e.g. "EE", "SE2", "XE"). | string | ❌ |
| `oracle.db.hosting_type` | The hosting environment of the Oracle instance. One of "self-managed", "rds", or "oci". | string | ✅ |
| `oracle.db.open_mode` | The open mode of the Oracle database (e.g. "READ WRITE", "READ ONLY", "MOUNTED"). | string | ✅ |
| `oracle.db.role` | The database role of the Oracle instance (e.g. "PRIMARY", "PHYSICAL STANDBY"). | string | ✅ |
| `oracle.db.version` | The Oracle Database version string. | string | ✅ |
| `oracledb.instance.name` | The name of the instance that data is coming from. | string | ✅ |
| `server.address` | The address of the monitored Oracle instance. A loopback target (for example localhost or 127.0.0.1) is reported as the host name of the machine running the collector, since the instance is co-located with it. Omitted when the connection string carries no parseable host, such as a TNS descriptor. | string | ✅ |
| `server.port` | The port of the monitored Oracle instance, defaulting to 1521 when the target does not specify one. | int | ✅ |
| `service.instance.id` | A unique identifier of the Oracle DB instance in the format host:port/serviceName, where host and port are resolved the same way as server.address and server.port. (defaults to 'unknown:1521' when the connection string carries no parseable host) | string | ✅ |
| `service.name` | Logical name of the service. When enabled, defaults to unknown\_service:oracle. | string | ❌ |
| `service.namespace` | Logical namespace for the service (for example team or environment). When enabled, defaults to an empty string until set via configuration. | string | ❌ |

## Configuration

### Example Configuration

```yaml theme={null}
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
  top_procedure_collection:
    max_procedure_sample_count: 555
    top_procedure_count: 111
  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
    db.server.top_procedure:
      enabled: true
```

***

*Last generated: 2026-10-05*