Release changes for v2.1.0

Makefile

@@ -3,7 +3,7 @@ OS_TYPE        ?= $(shell uname -s | tr '[:upper:]' '[:lower:]')
 ARCH_TYPE      ?= $(subst x86_64,amd64,$(patsubst i%86,386,$(ARCH)))
 GOOS           ?= $(shell go env GOOS)
 GOARCH         ?= $(shell go env GOARCH)
-VERSION        ?= 2.0.4
+VERSION        ?= 2.1.0
 LDFLAGS        := -X main.Version=$(VERSION)
 GOFLAGS        := -ldflags "$(LDFLAGS) -s -w"
 BUILD_ARGS      = --build-arg VERSION=$(VERSION)

docker-compose/compose.yaml

@@ -59,7 +59,7 @@ services:
       start_period: 30s
 
   exporter:
-    image: container-registry.oracle.com/database/observability-exporter:2.0.4
+    image: container-registry.oracle.com/database/observability-exporter:2.1.0
     container_name: exporter
     command:
       - '--config.file=/exporter/config.yaml'

go.mod

@@ -8,7 +8,7 @@ require (
 	github.com/BurntSushi/toml v1.5.0
 	github.com/alecthomas/kingpin/v2 v2.4.0
 	github.com/godror/godror v0.49.3
-	github.com/oracle/oci-go-sdk/v65 v65.100.1
+	github.com/oracle/oci-go-sdk/v65 v65.101.0
 	github.com/prometheus/client_golang v1.23.2
 	github.com/prometheus/common v0.66.1
 	github.com/prometheus/exporter-toolkit v0.14.1

go.sum

@@ -140,6 +140,8 @@ github.com/oracle/oci-go-sdk/v65 v65.99.2 h1:W1HzD28r+xqqT57FpH7ymOFE3BM/p4J/Ia1
 github.com/oracle/oci-go-sdk/v65 v65.99.2/go.mod h1:RGiXfpDDmRRlLtqlStTzeBjjdUNXyqm3KXKyLCm3A/Q=
 github.com/oracle/oci-go-sdk/v65 v65.100.1 h1:5Bj+O14s1GoyGfS3GCTP0jSfDTg7OjpOMaiC3jwdenQ=
 github.com/oracle/oci-go-sdk/v65 v65.100.1/go.mod h1:RGiXfpDDmRRlLtqlStTzeBjjdUNXyqm3KXKyLCm3A/Q=
+github.com/oracle/oci-go-sdk/v65 v65.101.0 h1:EErMOuw98JXi0P7DgPg5zjouCA5s61iWD5tFWNCVLHk=
+github.com/oracle/oci-go-sdk/v65 v65.101.0/go.mod h1:RGiXfpDDmRRlLtqlStTzeBjjdUNXyqm3KXKyLCm3A/Q=
 github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c h1:+mdjkGKdHQG3305AYmdv1U2eRNDiU2ErMBj1gwrq8eQ=
 github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c/go.mod h1:7rwL4CYBLnjLxUqIJNnCWiEdr3bn6IUYi15bNlnbCCU=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=

site/docs/configuration/config-file.md

@@ -111,7 +111,7 @@ An individual metric may have its own scrape interval separate from the exporter
 To add your custom config file to a container image, you can layer the base exporter image and include that config:
 
 ```Dockerfile
-FROM container-registry.oracle.com/database/observability-exporter:2.0.3
+FROM container-registry.oracle.com/database/observability-exporter:2.1.0
 COPY my-exporter-config.yaml /
 ENTRYPOINT ["/oracledb_exporter", "--config.file", "/my-exporter-config.yaml"]
 ```

site/docs/configuration/custom-metrics.md

@@ -187,7 +187,7 @@ The default metrics are provided in YAML format as an example. See [default-metr
 If you run the exporter as a container image and want to include your custom metrics in the image itself, you can use the following example `Dockerfile` to create a new image:
 
 ```Dockerfile
-FROM container-registry.oracle.com/database/observability-exporter:2.0.3
+FROM container-registry.oracle.com/database/observability-exporter:2.1.0
 COPY custom-metrics.toml /
 ENTRYPOINT ["/oracledb_exporter", "--custom.metrics", "/custom-metrics.toml"]
 ```

site/docs/configuration/oracle-wallet.md

@@ -32,7 +32,7 @@ docker run -it --rm \
     -e DB_CONNECT_STRING=devdb_tp \
     -v ./wallet:/wallet \
     -p 9161:9161 \
-    container-registry.oracle.com/database/observability-exporter:2.0.3
+    container-registry.oracle.com/database/observability-exporter:2.1.0
 ```
 
 ### mTLS for multiple databases with Oracle Wallet

site/docs/getting-started/basics.md

@@ -72,7 +72,7 @@ docker run -it --rm \
     -e DB_PASSWORD=Welcome12345 \
     -e DB_CONNECT_STRING=free23ai:1521/freepdb \
     -p 9161:9161 \
-    container-registry.oracle.com/database/observability-exporter:2.0.3
+    container-registry.oracle.com/database/observability-exporter:2.1.0
 ```
 
 ## Standalone Binary

site/docs/releases/changelog.md

@@ -11,6 +11,8 @@ List of upcoming and historic changes to the exporter.
 
 Our current priorities to support metrics for advanced database features and use cases, like Exadata, GoldenGate, and views included in the Oracle Diagnostics Pack.
 
+### Version 2.1.0, September 29, 2025
+
 - Updated project dependencies.
 - Standardize multi-arch builds and document supported database versions.
 - The metrics override capability is extended, allowing users to redefine individual existing metrics in custom metrics files. This allows users to modify individual default metrics without wholly replacing the default metrics file. 

site/docusaurus.config.ts

@@ -72,7 +72,7 @@ const config: Config = {
         },
         {
           type: 'docsVersionDropdown',
-          versions: ['current', '2.0.4', '2.0.3' ]
+          versions: ['current', '2.1.0', '2.0.4', '2.0.3' ]
         },
         {
           href: 'https://github.com/oracle/oracle-db-appdev-monitoring',

site/versioned_docs/version-2.1.0/advanced/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Advanced",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Advanced configuration."
+  }
+}

site/versioned_docs/version-2.1.0/advanced/development.md

@@ -0,0 +1,54 @@
+---
+title: Development
+sidebar_position: 3
+---
+
+# Development
+
+The exporter is a Go program using the Prometheus SDK. 
+
+External contributions are welcome, see [CONTRIBUTING](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/CONTRIBUTING.md) for details.
+
+The exporter initialization is as follows:
+
+- Parse flags options and configuration properties
+- Load the default toml file (`default-metrics.toml`) and store each metric in a `Metric` struct
+- Load the custom toml file (if a custom toml file is given)
+- Create an `Exporter` object
+- Register exporter in prometheus library
+- Launching a web server to handle incoming requests
+- Attempt connection to any configured Oracle Database servers
+
+These operations are mainly done in the `main` function.
+
+After this initialization phase, the exporter will wait for the arrival of a request.
+
+Each time, it will iterate over the content of the `metricsToScrape` structure (in the function scrape `func (e * Export) scrape (ch chan <- prometheus.Metric)`).
+
+For each element (of `Metric` type), a call to the `ScrapeMetric` function will be made which will itself make a call to the `ScrapeGenericValues` function.
+
+The `ScrapeGenericValues` function will read the information from the `Metric` structure and, depending on the parameters, will generate the metrics to return. In particular, it will use the `GeneratePrometheusMetrics` function which will make SQL calls to the database.
+
+### Docker/container build
+
+To build a container image, run the following command:
+
+```bash
+make docker
+```
+
+For ARM:
+
+```bash
+make docker-arm
+```
+
+### Building Binaries
+
+Run build:
+
+```bash
+make go-build
+```
+
+This will create binaries and archives inside the `dist` folder for the building operating system.

site/versioned_docs/version-2.1.0/advanced/go-runtime.md

@@ -0,0 +1,14 @@
+---
+title: Configuring the Go Runtime
+sidebar_position: 1
+---
+
+# Exporter Go Runtime
+
+If you are running in an environment with limited memory, or you are running a large number of exporters, you may want to control the exporter's usage of memory.
+
+Under normal circumstances, the exporter process will retain OS memory that was used by the Go garbage collector but is no longer needed, in case it may be needed again in the future, unless the host OS is under memory pressure.  The result of this behavior (which is the normal behavior of the Go runtime) is that the resident set size will not decrease until the host OS memory is almost all used.  Under most circumstances, this will not cause any issues, but if you are in an environment where you need to conserve memory, the following options are provided:
+
+- You may set the `FREE_INTERVAL` environment variable to a Go [duration string](https://pkg.go.dev/maze.io/x/duration), e.g., `60s` and run the exporter in debug mode by setting the `GODEBUG` environment variable to a value including `madvdontneed=1`, e.g., `GODEBUG=gctrace=1,madvdontneed=1`.  The exporter will call the [FreeOSMemory()](https://pkg.go.dev/runtime/debug#FreeOSMemory) at the specified interval.  This tells the Go runtime to attempt to release memory which is no longer needed.  Please note that this does not guarantee that the memory will be released to the OS, but over time you should see the RSS shrink sooner than without these settings.
+- You may set the `RESTART_INTERVAL` environment variable to a Go [duration string](https://pkg.go.dev/maze.io/x/duration), e.g., `10m`.  The exporter will restart its own process at the specified iterval (by calling the OS `exec` syscall).  As no new process is created, the process identifier (PID) does not change, but the machine code, data, heap, and stack of the process are replaced by those of the new program (source: [Wikipedia](https://en.wikipedia.org/wiki/Exec_(system_call))).  This has the side effect of freeing the resident set, so that it will return to its original size.
+- In addition to these, you may also set `GOMAXPROCS`, `GOGC`, and `GOMEMLIMIT` (see [documentation](https://pkg.go.dev/runtime#hdr-Environment_Variables)) to further limit the amount of resources that the Go runtime may use.

site/versioned_docs/version-2.1.0/advanced/older-versions.md

@@ -0,0 +1,34 @@
+---
+title: Compatibility with Older Database Versions
+sidebar_position: 4
+---
+
+# Older Database Versions
+
+In general, fixes and features are not provided for older database versions. However, it is possible to configure the Oracle Database Metrics Exporter to scrape older versions of Oracle Database.
+
+### Known Issues with Older Database Versions
+
+If you are running an unsupported version of Oracle Database, you may encounter the following issues:
+
+- Metrics using modern SQL syntax may not work. For compatibility, you can disable or modify these metrics.
+- The exporter uses a "thick" database client. Ensure your database client libraries are compatible with your database version.
+
+## Disabling incompatible metrics
+
+To disable an incompatible metric, either remove that metric from the metrics file or configure the metric so it does not apply the affected database:
+
+```toml
+[[metric]]
+context = "process"
+labels = [ "inst_id" ]
+metricsdesc = { count="Gauge metric with count of processes." }
+request = '''
+select inst_id, count(*) as count
+from gv$process
+group by inst_id
+'''
+# Set databases to an empty array to disable the metric entirely,
+# or include only compatible databases in this array.
+databases = []
+```

site/versioned_docs/version-2.1.0/advanced/txeventq.md

@@ -0,0 +1,117 @@
+---
+title: Monitoring TxEventQ
+sidebar_position: 2
+---
+
+# Monitoring Transactional Event Queues
+
+[Oracle Transactional Event Queues](https://docs.oracle.com/en/database/oracle/oracle-database/23/adque/index.html) ("TxEventQ") is a fault-tolerant, scalable, real-time messaging backbone offered by converged Oracle Database that allows you to build an enterprise-class event-driven architectures.
+
+Access to the real-time broker, producer, and consumer metrics in a single dashboard and receiving alerts for issues allows teams to understand the state of their system.
+
+The exporter includes a set of metrics for monitoring TxEventQ and a pre-built Grafana dashboard.
+
+> Note: The metrics are written for Oracle Database 21c or later.
+
+### How to create some traffic with PL/SQL
+
+If you need to create a topic to monitor, you can use these statements to create and start a topic, and create a subscriber:
+
+```sql
+declare
+    subscriber sys.aq$_agent;
+begin
+  -- create the topic
+  dbms_aqadm.create_transactional_event_queue(
+    queue_name => 'my_topic',
+    multiple_consumers => true  -- true makes a pub/sub topic
+  );
+
+  -- start the topic
+  dbms_aqadm.start_queue(
+    queue_name => 'my_topic'
+  );
+
+  -- create a subscriber
+  dbms_aqadm.add_subscriber(
+    queue_name => 'my_teq',
+    subscriber => sys.aq$_agent(
+      'my_subscriber',    -- the subscriber name
+      null,               -- address, only used for notifications
+      0                   -- protocol
+    ),
+    rule => 'correlation = ''my_subscriber'''
+  );
+end;
+```
+
+You can produce a message with these commands:
+
+```sql
+declare
+    enqueue_options    dbms_aq.enqueue_options_t;
+    message_properties dbms_aq.message_properties_t;
+    message_handle     raw(16);
+    message            SYS.AQ$_JMS_TEXT_MESSAGE;
+begin
+    -- create the message payload
+    message := SYS.AQ$_JMS_TEXT_MESSAGE.construct;
+    message.set_text('{"orderid": 12345, "username": "Jessica Smith"}');
+
+    -- set the consumer name
+    message_properties.correlation := 'my_subscriber';
+
+    -- enqueue the message
+    dbms_aq.enqueue(
+        queue_name           => 'my_topic',
+        enqueue_options      => enqueue_options,
+        message_properties   => message_properties,
+        payload              => message,
+        msgid                => message_handle);
+
+    -- commit the transaction
+    commit;
+end;
+```
+
+### How to create some traffic with Java (Spring Boot)
+
+A simple load generator is provided in [this directory](https://github.com/oracle/oracle-db-appdev-monitoring/tree/main/docker-compose/txeventq-load) which you can use to create some traffic so you can experiment with the sample dashboard.
+
+To run the sample, first update [application.yaml](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/docker-compose/txeventq-load/src/main/resources/application.yaml) with the correct IP address for your database, then start the application as follows:
+
+```bash
+mvn spring-boot:run
+```
+
+The application will create ten queues names TOPIC_0 through TOPIC_9 and randomly produce and consume messages on those queues.  The example dashboard shown below was monitoring traffic produced using this application.
+
+### Metrics definitions
+
+The metrics definitions are provided in [this file](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/custom-metrics-example/txeventq-metrics.toml).  You need to provide this file to the exporter, e.g., by adding it to your container image, or creating a Kubernetes config map containing the file and mounting that config map as a volume in your deployment.  You also need to set the `CUSTOM_METRICS` environment variable to the location of this file.
+
+### Additional database permissions
+
+The database user that the exporter uses to connect to the database will also need additional permissions, which can be granted with these statements.  This example assumes the exporter connects with the username "exporter":
+
+```sql
+grant execute on dbms_aq to exporter;
+grant execute on dbms_aqadm to exporter;
+grant execute on dbms_aqin to exporter;
+grant execute on dbms_aqjms_internal to exporter;
+grant execute on dbms_teqk to exporter;
+grant execute on DBMS_RESOURCE_MANAGER to exporter;
+grant select_catalog_role to exporter;
+grant select on sys.aq$_queue_shards to exporter;
+grant select on user_queue_partition_assignment_table to exporter;
+```
+
+### Grafana dashboard
+
+A Grafana dashboard for Transactional Event Queues is provided [in this file](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/docker-compose/grafana/dashboards/txeventq.json).  This can be imported into your Grafana environment.  Choose the Prometheus datasource that is collecting metrics from the exporter.
+
+> Note:  You may not see any activity on the dashboard unless there are clients producing and consuming messages from topics.
+
+The dashboard will look like this:
+
+![Oracle Database Dashboard](/img/txeventq-dashboard-v2.png)

site/versioned_docs/version-2.1.0/configuration/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Configuration",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "How to configure the Oracle Database Metrics Exporter."
+  }
+}

site/versioned_docs/version-2.1.0/configuration/alert-logs.md

@@ -0,0 +1,30 @@
+---
+title: Alert Logs
+sidebar_position: 5
+---
+
+# Alert logs
+
+Collect export alert logs with a log ingestion tool.
+
+The exporter exports alert log records as a JSON file suitable for collection by a log ingestion tool like Promtail or FluentBit.
+
+Alert logging is configured with the following parameters in the exporter config file:
+
+| Parameter       | Description                   | Default          |
+|-----------------|-------------------------------|------------------|
+| log.destination | Log file path                 | `/log/alert.log` |
+| log.interval    | Interval to log records       | `15s`            |
+| log.disable     | Disable logging if set to `1` | `0`              |
+
+Example alert log YAML configuration:
+
+```yaml
+log:
+  # Path of log file
+  destination: /opt/exporter/alert.log
+  # Interval of log updates
+  interval: 15s
+  ## Set disable to 1 to disable logging
+  # disable: 0
+```