add txeventq info (#28)

Signed-off-by: Mark Nelson <[email protected]>

Author: markxnelson

README.md

@@ -19,6 +19,7 @@ Contributions are welcome - please see [contributing](CONTRIBUTING.md).
    - [Standalone binary](#standalone-binary)
 - [Custom metrics](#custom-metrics)
 - [Grafana dashboards](#grafana-dashboards)
+- [Monitoring Transactional Event Queues](#monitoring-transactional-event-queues)
 - [Developer notes](#developer-notes)
 
 
@@ -466,6 +467,107 @@ The dashboard shows some basic information, as shown below:
 ![](doc/oracledb-dashboard.png)
 
 
+# Monitoring Transactional Event Queues
+
+[Oracle Transactional Event Queues](https://docs.oracle.com/en/database/oracle/oracle-database/21/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 a topic
+
+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;
+```
+
+## Metrics definitions
+
+The metrics definitions are provided in [this file](./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](./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: 
+
+![](./doc/txeventq-dashboard.png)
+
 # Developer notes
 
 The exporter itself is fairly simple. The initialization is done as follows:

custom-metrics-example/txeventq-metrics.toml

@@ -97,144 +97,3 @@ FROM
     ) t1
     JOIN gv$persistent_queues t2 ON t1.queue_id = t2.queue_id
 '''
-
-[[metric]]
-context = "sessions"
-labels = ["inst_id", "status", "type"]
-metricsdesc = { value = "Gauge metric with count of sessions by status and type." }
-request = '''
-SELECT
-    inst_id,
-    status,
-    type,
-    COUNT(*) AS value
-FROM
-    gv$session
-GROUP BY
-    status,
-    type,
-    inst_id
-'''
-
-
-[[metric]]
-context = "asm_diskgroup"
-labels = ["inst_id", "name"]
-metricsdesc = { total = "Total size of ASM disk group.", free = "Free space available on ASM disk group." }
-request = '''
-SELECT
-    inst_id,
-    name,
-    total_mb * 1024 * 1024 AS total,
-    free_mb * 1024 * 1024 AS free
-FROM
-    gv$asm_diskgroup
-'''
-ignorezeroresult = true
-
-
-[[metric]]
-context = "activity"
-labels = ["inst_id", "name"]
-metricsdesc = { value = "Generic counter metric from gv$sysstat view in Oracle." }
-request = '''
-SELECT
-    inst_id,
-    name,
-    value
-FROM
-    gv$sysstat
-WHERE
-    name IN (
-        'parse count (total)',
-        'execute count',
-        'user commits',
-        'user rollbacks'
-    )
-'''
-
-[[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
-'''
-
-[[metric]]
-context = "wait_class"
-labels = ["inst_id", "wait_class"]
-metricsdesc = { total_waits = "Number of times waits of the class occurred", time_waited = "Amount of time spent in the wait by all sessions in the instance" }
-request = '''
-SELECT
-    inst_id,
-    wait_class,
-    total_waits,
-    time_waited
-FROM
-    gv$system_wait_class
-'''
-
-[[metric]]
-context = "system"
-labels = ["inst_id", "stat_name"]
-metricsdesc = { value = "os metric from gv$osstat view in Oracle." }
-request = '''
-SELECT
-    inst_id,
-    stat_name,
-    value
-FROM
-    gv$osstat
-WHERE
-    upper(stat_name) IN (
-        'NUM_CPUS',
-        'LOAD',
-        'IDLE_TIME',
-        'BUSY_TIME',
-        'USER_TIME',
-        'PHYSICAL_MEMORY_BYTES',
-        'FREE_MEMORY_BYTES'
-    )
-'''
-
-[[metric]]
-context = "system_network"
-labels = ["inst_id"]
-metricsdesc = { received_from_client = "Bytes received from client.", sent_to_client = "Bytes sent to client." }
-request = '''
-SELECT
-    t1.inst_id                AS inst_id,
-    t1.received_from_client   AS received_from_client,
-    t2.sent_to_client         AS sent_to_client
-FROM
-    (
-        SELECT
-            inst_id,
-            value AS received_from_client
-        FROM
-            gv$sysstat
-        WHERE
-            lower(name) LIKE '%received via sql*net from client%'
-        ORDER BY
-            value DESC
-    ) t1
-    LEFT JOIN (
-        SELECT
-            inst_id,
-            value AS sent_to_client
-        FROM
-            gv$sysstat
-        WHERE
-            lower(name) LIKE '%sent via sql*net to client%'
-        ORDER BY
-            value DESC
-    ) t2 ON t1.inst_id = t2.inst_id
-'''
-

doc/txeventq-dashboard.png

@@ -51,6 +51,9 @@ services:
       - DB_USERNAME=system
       - DB_PASSWORD=Welcome12345
       - DB_CONNECT_STRING=free23c:1521/free
+      - CUSTOM_METRICS=/exporter/txeventq-metrics.toml
+    volumes:
+      - ./exporter:/exporter
     depends_on: 
       free23c:
         condition: service_healthy

docker-compose/compose.yaml

@@ -0,0 +1,99 @@
+[[metric]]
+context = "ownership"
+metricsdesc = { inst_id = "Owner instance of the current queues." }
+request = '''
+SELECT
+    inst_id
+FROM
+    gv$persistent_queues
+WHERE
+    ROWNUM < 2
+'''
+
+[[metric]]
+context = "teq"
+metricsdesc = { curr_inst_id = "ID of current instance" }
+request = "SELECT instance_number AS curr_inst_id FROM v$instance"
+
+[[metric]]
+context = "teq"
+labels = ["inst_id"]
+metricsdesc = { total_queues = "Total number of queues"}
+request = '''
+SELECT
+    inst_id,
+    COUNT(*) AS total_queues
+FROM
+    (
+        SELECT DISTINCT
+            t1.inst_id,
+            t2.queue_name
+        FROM
+            gv$aq_sharded_subscriber_stat   t1
+            JOIN gv$persistent_queues            t2 ON t1.queue_id = t2.queue_id
+    )
+GROUP BY
+    inst_id
+'''
+
+[[metric]]
+context = "teq"
+labels = ["inst_id"]
+metricsdesc = { total_subscribers = "Total number of subscribers"}
+request = '''
+SELECT
+    inst_id,
+    COUNT(*) AS total_subscribers
+FROM
+    (
+        SELECT DISTINCT
+            inst_id,
+            subscriber_id
+        FROM
+            gv$aq_sharded_subscriber_stat
+    )
+GROUP BY
+    inst_id
+'''
+
+[[metric]]
+context = "teq"
+labels = ["inst_id", "queue_name", "subscriber_name"]
+metricsdesc = { enqueued_msgs = "Total enqueued messages.", dequeued_msgs = "Total dequeued messages.", remained_msgs = "Total remained messages.", time_since_last_dequeue = "Time since last dequeue.", estd_time_to_drain_no_enq = "Estimated time to drain if no enqueue.", message_latency_1 = "Message latency for last 5 mins.", message_latency_2 = "Message latency for last 1 hour.", message_latency_3 = "Message latency for last 5 hours."}
+request = '''
+SELECT DISTINCT
+    t1.inst_id,
+    t1.queue_id,
+    t2.queue_name,
+    t1.subscriber_id AS subscriber_name,
+    t1.enqueued_msgs,
+    t1.dequeued_msgs,
+    t1.remained_msgs,
+    t1.time_since_last_dequeue,
+    t1.estd_time_to_drain_no_enq,
+    t1.message_latency_1,
+    t1.message_latency_2,
+    t1.message_latency_3
+FROM
+    (
+        SELECT
+            inst_id,
+            queue_id,
+            subscriber_id,
+            SUM(enqueued_msgs) AS enqueued_msgs,
+            SUM(dequeued_msgs) AS dequeued_msgs,
+            SUM(enqueued_msgs - dequeued_msgs) AS remained_msgs,
+            MIN(time_since_last_dequeue) AS time_since_last_dequeue,
+            MAX(estd_time_to_drain_no_enq) AS estd_time_to_drain_no_enq,
+            AVG(10) AS message_latency_1,
+            AVG(20) AS message_latency_2,
+            AVG(30) AS message_latency_3
+        FROM
+            gv$aq_sharded_subscriber_stat
+        GROUP BY
+            queue_id,
+            subscriber_id,
+            inst_id
+    ) t1
+    JOIN gv$persistent_queues t2 ON t1.queue_id = t2.queue_id
+'''