From 01d81fa9592de197a632bf16d097d9646c0c5667 Mon Sep 17 00:00:00 2001
From: Clayton Cornell <clayton.cornell@grafana.com>
Date: Fri, 21 Nov 2025 10:28:36 -0800
Subject: [PATCH 1/5] Add missing prereq adn env var info

---
 .../prometheus.exporter.oracledb.md           | 58 ++++++++++++++-----
 1 file changed, 42 insertions(+), 16 deletions(-)

diff --git a/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md b/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
index e5af107052..5a327386bd 100644
--- a/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
+++ b/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
@@ -15,6 +15,30 @@ title: prometheus.exporter.oracledb
 The `prometheus.exporter.oracledb` component embeds
 [`oracledb_exporter`](https://github.com/oracle/oracle-db-appdev-monitoring) for collecting statistics from a OracleDB server.
 
+Ensure you have the following:
+
+- Oracle Instant Client Basic installed on the system running Grafana Alloy
+- Appropriate environment variables configured for Oracle Client libraries
+
+### Oracle instant client basic
+
+When you run the standalone binary, you must install the [Oracle Instant Client Basic](http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html) for your operating system.
+Only the basic version is required for the exporter.
+
+{{< admonition type="note" >}}
+The Alloy Docker image includes the Oracle Instant Client, so this prerequisite only applies to standalone binary installations.
+{{< /admonition >}}
+
+### Environment variables
+
+Set the following environment variables for Oracle Client library access:
+
+- **Linux**: Set `LD_LIBRARY_PATH` to the Oracle Instant Client library directory
+- **macOS (ARM)**: Set `DYLD_LIBRARY_PATH` to the Oracle Instant Client library directory
+- **`ORACLE_BASE`** (optional): Base directory for Oracle installations
+- **`ORACLE_HOME`** (optional): Location of the Oracle Instant Client installation
+- **`TNS_ADMIN`** (optional): Location of your Oracle wallet directory when using wallet authentication
+
 ## Usage
 
 ```alloy
@@ -27,18 +51,18 @@ prometheus.exporter.oracledb "<LABEL>" {
 
 You can use the following arguments with `prometheus.exporter.oracledb`:
 
-| Name                | Type           | Description                                                    | Default | Required |
-| ------------------- | -------------- | -------------------------------------------------------------- | ------- | -------- |
-| `connection_string` | `secret`       | The connection string used to connect to an Oracle Database.   |         | yes      |
-| `username`          | `string`       | The username to use for authentication to the Oracle Database. |         | no       |
-| `password`          | `secret`       | The password to use for authentication to the Oracle Database. |         | no       |
-| `max_idle_conns`    | `int`          | Number of maximum idle connections in the connection pool.     | `0`     | no       |
-| `max_open_conns`    | `int`          | Number of maximum open connections in the connection pool.     | `10`    | no       |
-| `query_timeout`     | `int`          | The query timeout in seconds.                                  | `5`     | no       |
-| `default_metrics`   | `string`       | The path to the default metrics file. (TOML format)            |         | no       |
-| `custom_metrics`    | `list(string)` | The paths to the custom metrics files. (TOML format)           |         | no       |
+| Name                | Type           | Description                                                                                                                  | Default | Required |
+| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
+| `connection_string` | `secret`       | The connection string used to connect to an Oracle Database. Can be provided as an environment variable `DB_CONNECT_STRING`. |         | yes      |
+| `username`          | `string`       | The username to use for authentication to the Oracle Database. Can be provided as an environment variable `DB_USERNAME`.     |         | no       |
+| `password`          | `secret`       | The password to use for authentication to the Oracle Database. Can be provided as an environment variable `DB_PASSWORD`.     |         | no       |
+| `max_idle_conns`    | `int`          | Number of maximum idle connections in the connection pool.                                                                   | `0`     | no       |
+| `max_open_conns`    | `int`          | Number of maximum open connections in the connection pool.                                                                   | `10`    | no       |
+| `query_timeout`     | `int`          | The query timeout in seconds.                                                                                                | `5`     | no       |
+| `default_metrics`   | `string`       | The path to the default metrics file. (TOML format)                                                                          |         | no       |
+| `custom_metrics`    | `list(string)` | The paths to the custom metrics files. (TOML format)                                                                         |         | no       |
 
-Examples of TOML metrics files can be found in the [oracledb_exporter repository](https://github.com/oracle/oracle-db-appdev-monitoring).
+Examples of TOML metrics files can be found in the [`oracledb_exporter` repository](https://github.com/oracle/oracle-db-appdev-monitoring).
 
 For backward compatibility, the `username` and `password` arguments can still be provided in the `connection_string` argument:
 
@@ -81,8 +105,8 @@ The following example uses a [`prometheus.scrape` component][scrape] to collect
 ```alloy
 prometheus.exporter.oracledb "example" {
   connection_string = "localhost:1521/orcl.localnet"
-  username = "system"
-  password = "YourPassword123"
+  username = "<DB_USERNAME>"
+  password = "<DB_PASSWORD>"
 }
 
 // Configure a prometheus.scrape component to collect oracledb metrics.
@@ -105,9 +129,11 @@ prometheus.remote_write "demo" {
 
 Replace the following:
 
-* _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus `remote_write` compatible server to send metrics to.
-* _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
-* _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
+- _`DB_USERNAME`_: The database username
+- _`DB_PASSWORD`_: The password for the database user
+- _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus `remote_write` compatible server to send metrics to.
+- _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
+- _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
 
 [scrape]: ../prometheus.scrape/
 

From c53c964c3bbe400d7edceda9022b052d03f2c30d Mon Sep 17 00:00:00 2001
From: Clayton Cornell <clayton.cornell@grafana.com>
Date: Fri, 21 Nov 2025 10:31:43 -0800
Subject: [PATCH 2/5] Fix vars

---
 .../components/prometheus/prometheus.exporter.oracledb.md     | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md b/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
index 5a327386bd..9db885e804 100644
--- a/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
+++ b/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
@@ -17,7 +17,7 @@ The `prometheus.exporter.oracledb` component embeds
 
 Ensure you have the following:
 
-- Oracle Instant Client Basic installed on the system running Grafana Alloy
+- Oracle Instant Client Basic installed on the system running {{< param "PRODUCT_NAME" >}}
 - Appropriate environment variables configured for Oracle Client libraries
 
 ### Oracle instant client basic
@@ -26,7 +26,7 @@ When you run the standalone binary, you must install the [Oracle Instant Client
 Only the basic version is required for the exporter.
 
 {{< admonition type="note" >}}
-The Alloy Docker image includes the Oracle Instant Client, so this prerequisite only applies to standalone binary installations.
+The {{< param "PRODUCT_NAME" >}} Docker image includes the Oracle Instant Client, so this prerequisite only applies to standalone binary installations.
 {{< /admonition >}}
 
 ### Environment variables

From a8bb99052ead0e019d4bd2fe9b21999d289e0079 Mon Sep 17 00:00:00 2001
From: Clayton Cornell <clayton.cornell@grafana.com>
Date: Fri, 21 Nov 2025 10:33:30 -0800
Subject: [PATCH 3/5] Fix table descriptions

---
 .../prometheus.exporter.oracledb.md           | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md b/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
index 9db885e804..fb5cb0964b 100644
--- a/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
+++ b/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
@@ -51,16 +51,16 @@ prometheus.exporter.oracledb "<LABEL>" {
 
 You can use the following arguments with `prometheus.exporter.oracledb`:
 
-| Name                | Type           | Description                                                                                                                  | Default | Required |
-| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
-| `connection_string` | `secret`       | The connection string used to connect to an Oracle Database. Can be provided as an environment variable `DB_CONNECT_STRING`. |         | yes      |
-| `username`          | `string`       | The username to use for authentication to the Oracle Database. Can be provided as an environment variable `DB_USERNAME`.     |         | no       |
-| `password`          | `secret`       | The password to use for authentication to the Oracle Database. Can be provided as an environment variable `DB_PASSWORD`.     |         | no       |
-| `max_idle_conns`    | `int`          | Number of maximum idle connections in the connection pool.                                                                   | `0`     | no       |
-| `max_open_conns`    | `int`          | Number of maximum open connections in the connection pool.                                                                   | `10`    | no       |
-| `query_timeout`     | `int`          | The query timeout in seconds.                                                                                                | `5`     | no       |
-| `default_metrics`   | `string`       | The path to the default metrics file. (TOML format)                                                                          |         | no       |
-| `custom_metrics`    | `list(string)` | The paths to the custom metrics files. (TOML format)                                                                         |         | no       |
+| Name                | Type           | Description                                                    | Default | Required |
+| ------------------- | -------------- | -------------------------------------------------------------- | ------- | -------- |
+| `connection_string` | `secret`       | The connection string used to connect to an Oracle Database.   |         | yes      |
+| `custom_metrics`    | `list(string)` | The paths to the custom metrics files. (TOML format)           |         | no       |
+| `default_metrics`   | `string`       | The path to the default metrics file. (TOML format)            |         | no       |
+| `max_idle_conns`    | `int`          | Number of maximum idle connections in the connection pool.     | `0`     | no       |
+| `max_open_conns`    | `int`          | Number of maximum open connections in the connection pool.     | `10`    | no       |
+| `password`          | `secret`       | The password to use for authentication to the Oracle Database. |         | no       |
+| `query_timeout`     | `int`          | The query timeout in seconds.                                  | `5`     | no       |
+| `username`          | `string`       | The username to use for authentication to the Oracle Database. |         | no       |
 
 Examples of TOML metrics files can be found in the [`oracledb_exporter` repository](https://github.com/oracle/oracle-db-appdev-monitoring).
 

From 84bef59c869ff23a31770f159c76e2891b0afd45 Mon Sep 17 00:00:00 2001
From: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com>
Date: Wed, 3 Dec 2025 08:50:55 -0800
Subject: [PATCH 4/5] Apply suggestion from @clayton-cornell

---
 .../components/prometheus/prometheus.exporter.oracledb.md     | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md b/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
index fb5cb0964b..69695c002f 100644
--- a/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
+++ b/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
@@ -129,8 +129,8 @@ prometheus.remote_write "demo" {
 
 Replace the following:
 
-- _`DB_USERNAME`_: The database username
-- _`DB_PASSWORD`_: The password for the database user
+- _`<DB_USERNAME>`_: The database username
+- _`<DB_PASSWORD>`_: The password for the database user
 - _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus `remote_write` compatible server to send metrics to.
 - _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
 - _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.

From 38453668884df7fd0b9308a98a32e6134a9b5312 Mon Sep 17 00:00:00 2001
From: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com>
Date: Thu, 4 Dec 2025 14:04:17 -0800
Subject: [PATCH 5/5] Apply suggestion from @clayton-cornell

---
 .../components/prometheus/prometheus.exporter.oracledb.md      | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md b/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
index 69695c002f..1104c99809 100644
--- a/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
+++ b/docs/sources/reference/components/prometheus/prometheus.exporter.oracledb.md
@@ -26,7 +26,8 @@ When you run the standalone binary, you must install the [Oracle Instant Client
 Only the basic version is required for the exporter.
 
 {{< admonition type="note" >}}
-The {{< param "PRODUCT_NAME" >}} Docker image includes the Oracle Instant Client, so this prerequisite only applies to standalone binary installations.
+You must also provide Oracle Instant Client Basic when you run {{< param "PRODUCT_NAME" >}} in Docker or Kubernetes.
+The `prometheus.exporter.oracledb` component relies on Oracle Instant Client libraries that are available in the container image or host environment.
 {{< /admonition >}}
 
 ### Environment variables