[receiver/oracledb] Add transaction, lock, and recovery metrics (#49067)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description
The Oracle DB receiver scrapes `v$sysstat` with `SELECT * FROM
v$sysstat`, which returns all system-statistics rows. However, the
scraper only processes a subset of those rows in its `switch` block and
silently discards the rest — including the transaction-rollback,
lock-contention, and recovery statistics. This change surfaces **7
discarded `v$sysstat` statistics** as **5 new opt-in metrics**, giving
operators visibility into commit/rollback churn, enqueue/lock pressure,
instance- and transaction-recovery activity, and RAC cache-fusion
latency — core Oracle durability and availability diagnostics.

This change adds 5 new opt-in metrics (disabled by default, stability:
development):

* `oracledb.transaction.rollbacks` — Number of transactions rolled back.
No attributes. Covers `v$sysstat`: `transaction rollbacks`. Distinct
from the existing `oracledb.user_rollbacks` (which counts only
user-issued `ROLLBACK` statements); this counts all transaction
rollbacks, including internal/recursive ones.
* `oracledb.lock.time` — Cumulative time, in seconds, spent on
transaction lock activity. Attribute: `oracledb.session.type`
(background|foreground). Covers `v$sysstat`: `transaction lock
background get time`, `transaction lock foreground wait time` (the raw
centisecond value is divided by 100 in the scraper).
* `oracledb.recovery.blocks` — Number of blocks read during instance or
media recovery. No attributes. Covers `v$sysstat`: `recovery blocks
read`.
* `oracledb.smon.posts` — Number of times SMON was posted to perform
recovery. Attribute: `oracledb.smon.type` (instance|transaction). Covers
`v$sysstat`: `SMON posted for instance recovery` (`instance`), `SMON
posted for txn recovery for other instances` (`transaction`, RAC
cross-instance).
* `oracledb.gc.current_block.time` — Cumulative time, in seconds, spent
transferring current blocks between instances over Oracle RAC cache
fusion. Attribute: `network.io.direction` (receive). Covers `v$sysstat`:
`gc current block receive time` (cs ÷ 100). Here "gc" denotes Oracle's
global cache (Cache Fusion), not JVM garbage collection; the value is 0
on a single-instance (non-RAC) database.

`oracledb.lock.time` and `oracledb.gc.current_block.time` are emitted as
a `Sum` with `aggregation_temporality: cumulative`, `monotonic: true`,
value type `double`, unit `s`. The remaining three are emitted as `Sum`
with `aggregation_temporality: cumulative`, `monotonic: true`, value
type `int`. Per-metric units: `s` (`oracledb.lock.time`,
`oracledb.gc.current_block.time`); `{rollback}`
(`oracledb.transaction.rollbacks`); `{block}`
(`oracledb.recovery.blocks`); `{post}` (`oracledb.smon.posts`).

The two time metrics report seconds (`s`) rather than the raw `cs`
(centisecond) units that Oracle exposes via `v$sysstat`; the scraper
divides the raw value by 100 before recording, matching the conversion
already in place for the existing `oracledb.cpu_time` metric.

> **Note (change since the initial submission):** an earlier revision
included `oracledb.lock.wait.time` mapped to a `v$sysstat` statistic
named `Total Lock Time`. That statistic does not exist in `v$sysstat` on
any supported Oracle version (verified against `v$statname` on Oracle
19c — it returns no such row), so the metric would never emit. It has
been removed. Background/foreground lock timing is already captured by
`oracledb.lock.time`.

These metrics can be enabled in the collector configuration:

```yaml
receivers:
  oracledb:
    datasource: "oracle://user:password@host:1521/service"
    metrics:
      oracledb.transaction.rollbacks:
        enabled: true
      oracledb.lock.time:
        enabled: true
      oracledb.recovery.blocks:
        enabled: true
      oracledb.smon.posts:
        enabled: true
      oracledb.gc.current_block.time:
        enabled: true
```

<!-- Issue number (e.g. #1234) or full URL to issue, if applicable. -->
#### Link to tracking issue
Fixes #49064 

<!--Describe what testing was performed and which tests were added.-->
#### Testing

Unit tests added in `scraper_test.go`:

- `TestScraper_ScrapeTransactionLockRecoveryMetrics` exercises all 5 new
metrics end-to-end through the scraper using the existing fake DB
client, asserting one expected value per data point (2
`oracledb.lock.time` data points — one per `oracledb.session.type` —
plus 2 `oracledb.smon.posts` data points — one per `oracledb.smon.type`
— plus 3 standalone data points = 7 data points per scrape across the 5
metrics).
- The shared `queryResponses[statsSQL]` fixture is extended with 7 new
fake `v$sysstat` rows (one per covered NAME), so `TestScraper_Scrape`,
`TestScraper_ScrapeOperationalMetrics`, and
`TestScraper_ScrapeIOPerformanceMetrics` continue to pass unchanged.
- The test explicitly verifies the centiseconds → seconds conversion:
raw 350/1200 cs from `transaction lock background get time` /
`transaction lock foreground wait time` produce 3.5/12.0 s on the
background/foreground data points; 640 cs from `gc current block receive
time` produces 6.4 s.
- Auto-generated tests in `internal/metadata/generated_metrics_test.go`
and `generated_config_test.go` are regenerated by `make generate` and
cover the new metric configs / metric builders.

<!--Describe the documentation added.-->
#### Documentation
Auto-generated `documentation.md` updated with descriptions and metadata
for the 5 new metrics, the new `oracledb.smon.type` attribute, the
reused `network.io.direction` attribute (on
`oracledb.gc.current_block.time`), and the extended
`oracledb.session.type` attribute (now `background`/`foreground`).
`internal/metadata/generated_*.go` and
`internal/metadata/testdata/config.yaml` regenerated via `make
generate`. `internal/metadata/config.schema.yaml` was updated for the 5
new metric stanzas, as that file is not produced by `make generate`.

<!--Authorship attestation. See AGENTS.md for details. AI agents must
not check this box on behalf
of the user; the human author must check it themselves before the PR is
ready for review.-->
#### Authorship

- [X] I, a human, wrote this pull request description myself.

<!--Please delete paragraphs that you did not use before submitting.-->

Author: rluidash

.chloggen/feat_add-oracledb-transaction-lock-recovery-metrics.yaml

@@ -0,0 +1,28 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/filelog)
+component: receiver/oracledb
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add transaction, lock, and recovery metrics
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [49064]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  The new metrics are disabled by default and add no new database queries.
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

receiver/oracledbreceiver/documentation.md

@@ -409,7 +409,7 @@ Total wall-clock time spent in database calls.
 
 | Name | Description | Values | Requirement Level | Semantic Convention |
 | ---- | ----------- | ------ | ----------------- | ------------------- |
-| oracledb.session.type | Class of session the database time is attributed to. | Str: ``foreground`` | Recommended | - |
+| oracledb.session.type | Class of session the activity is attributed to. | Str: ``background``, ``foreground`` | Recommended | - |
 
 ### oracledb.db_block_gets
 
@@ -463,6 +463,20 @@ Fraction of executions that did not require a parse, as computed by Oracle V$SYS
 | ---- | ----------- | ------ | ----------------- | ------------------- |
 | oracledb.parse.type | Type of parse operation (e.g., soft). | Str: ``soft`` | Recommended | - |
 
+### oracledb.gc.current_block.time
+
+Cumulative time spent transferring current blocks between instances over RAC cache fusion.
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
+| ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
+| s | Sum | Double | Cumulative | true | Development |
+
+#### Attributes
+
+| Name | Description | Values | Requirement Level | Semantic Convention |
+| ---- | ----------- | ------ | ----------------- | ------------------- |
+| network.io.direction | Direction of the network transfer. | Str: ``receive``, ``transmit`` | Recommended | - |
+
 ### oracledb.host.cpu.usage.rate
 
 Host CPU consumption rate across all cores, in CPU-seconds used per second.
@@ -509,6 +523,20 @@ Total count of LOB (large object) I/O operations.
 | ---- | ----------- | ------ | ----------------- | ------------------- |
 | disk.io.direction | Direction of the storage I/O operation. | Str: ``read``, ``write`` | Recommended | - |
 
+### oracledb.lock.time
+
+Cumulative time spent on transaction lock activity.
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
+| ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
+| s | Sum | Double | Cumulative | true | Development |
+
+#### Attributes
+
+| Name | Description | Values | Requirement Level | Semantic Convention |
+| ---- | ----------- | ------ | ----------------- | ------------------- |
+| oracledb.session.type | Class of session the activity is attributed to. | Str: ``background``, ``foreground`` | Recommended | - |
+
 ### oracledb.logons
 
 Number of logon operations
@@ -697,6 +725,14 @@ Number of SELECT statements executed in parallel
 | ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
 | {queries} | Sum | Int | Cumulative | true | Development |
 
+### oracledb.recovery.blocks
+
+Number of blocks read during instance or media recovery.
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
+| ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
+| {block} | Sum | Int | Cumulative | true | Development |
+
 ### oracledb.recycle_bin.limit
 
 Total size of the recycle bin.
@@ -858,6 +894,20 @@ Fraction of the shared pool that is currently free, as computed by Oracle V$SYSM
 | ---- | ----------- | ---------- | --------- |
 | % | Gauge | Double | Development |
 
+### oracledb.smon.posts
+
+Number of times SMON was posted to perform recovery.
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
+| ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
+| {post} | Sum | Int | Cumulative | true | Development |
+
+#### Attributes
+
+| Name | Description | Values | Requirement Level | Semantic Convention |
+| ---- | ----------- | ------ | ----------------- | ------------------- |
+| oracledb.smon.type | Type of recovery SMON was posted to perform. | Str: ``instance``, ``transaction`` | Recommended | - |
+
 ### oracledb.sort.operations
 
 Total count of sort operations.
@@ -914,7 +964,7 @@ Bytes transferred via SQL*Net between Oracle and clients/dblinks. Sourced from v
 
 | Name | Description | Values | Requirement Level | Semantic Convention |
 | ---- | ----------- | ------ | ----------------- | ------------------- |
-| network.io.direction | Direction of the SQL*Net network transfer. | Str: ``receive``, ``transmit`` | Recommended | - |
+| network.io.direction | Direction of the network transfer. | Str: ``receive``, ``transmit`` | Recommended | - |
 | destination.type | Type of the SQL*Net destination endpoint (client application or remote database link). | Str: ``client``, ``dblink`` | Recommended | - |
 
 ### oracledb.storage.usage
@@ -965,6 +1015,14 @@ Average response time per transaction.
 | ---- | ----------- | ---------- | --------- |
 | s | Gauge | Double | Development |
 
+### oracledb.transaction.rollbacks
+
+Total number of transactions rolled back.
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic | Stability |
+| ---- | ----------- | ---------- | ----------------------- | --------- | --------- |
+| {rollback} | Sum | Int | Cumulative | true | Development |
+
 ## Default Events
 
 The following events are emitted by default. Each of them can be disabled by applying the following configuration:

receiver/oracledbreceiver/internal/metadata/config.schema.yaml

@@ -262,6 +262,13 @@ $defs:
           enabled:
             type: boolean
             default: true
+      oracledb.gc.current_block.time:
+        description: "OracledbGcCurrentBlockTimeMetricConfig provides config for the oracledb.gc.current_block.time metric."
+        type: object
+        properties:
+          enabled:
+            type: boolean
+            default: false
       oracledb.hard_parses:
         description: "OracledbHardParsesMetricConfig provides config for the oracledb.hard_parses metric."
         type: object
@@ -306,6 +313,13 @@ $defs:
                 - "disk.io.direction"
             default:
               - "disk.io.direction"
+      oracledb.lock.time:
+        description: "OracledbLockTimeMetricConfig provides config for the oracledb.lock.time metric."
+        type: object
+        properties:
+          enabled:
+            type: boolean
+            default: false
       oracledb.logical_reads:
         description: "OracledbLogicalReadsMetricConfig provides config for the oracledb.logical_reads metric."
         type: object
@@ -517,6 +531,13 @@ $defs:
           enabled:
             type: boolean
             default: false
+      oracledb.recovery.blocks:
+        description: "OracledbRecoveryBlocksMetricConfig provides config for the oracledb.recovery.blocks metric."
+        type: object
+        properties:
+          enabled:
+            type: boolean
+            default: false
       oracledb.recycle_bin.limit:
         description: "OracledbRecycleBinLimitMetricConfig provides config for the oracledb.recycle_bin.limit metric."
         type: object
@@ -637,6 +658,13 @@ $defs:
             default:
               - "session_type"
               - "session_status"
+      oracledb.smon.posts:
+        description: "OracledbSmonPostsMetricConfig provides config for the oracledb.smon.posts metric."
+        type: object
+        properties:
+          enabled:
+            type: boolean
+            default: false
       oracledb.sort.operations:
         description: "OracledbSortOperationsMetricConfig provides config for the oracledb.sort.operations metric."
         type: object
@@ -759,6 +787,13 @@ $defs:
           enabled:
             type: boolean
             default: false
+      oracledb.transaction.rollbacks:
+        description: "OracledbTransactionRollbacksMetricConfig provides config for the oracledb.transaction.rollbacks metric."
+        type: object
+        properties:
+          enabled:
+            type: boolean
+            default: false
       oracledb.transactions.limit:
         description: "OracledbTransactionsLimitMetricConfig provides config for the oracledb.transactions.limit metric."
         type: object