Add INST_ID as a metrics label (#329)

Signed-off-by: Anders Swanson <anders.swanson@oracle.com>

Author: anders-swanson

collector/default_metrics.toml

@@ -1,63 +1,73 @@
 [[metric]]
 context = "sessions"
-labels = [ "status", "type" ]
-metricsdesc = { value= "Gauge metric with count of sessions by status and type." }
+labels = [ "inst_id", "status", "type" ]
+metricsdesc = { value= "Gauge metric with count of sessions by inst_id, status and type." }
 request = '''
-select status, type, count(*) as value
+select inst_id, status, type, count(*) as value
 from gv$session
-group by status, type
+group by inst_id, status, type
 '''
 
 [[metric]]
 context = "resource"
-labels = [ "resource_name" ]
+labels = [ "inst_id", "resource_name" ]
 metricsdesc = { current_utilization= "Generic counter metric from gv$resource_limit view in Oracle (current value).", limit_value="Generic counter metric from v$resource_limit view in Oracle (UNLIMITED: -1)." }
 request = '''
-select resource_name, current_utilization, case when trim(limit_value) like 'UNLIMITED' then '-1' else trim(limit_value) end as limit_value
+select inst_id, resource_name, current_utilization, case when trim(limit_value) like 'UNLIMITED' then '-1' else trim(limit_value) end as limit_value
 from gv$resource_limit
+group by inst_id, resource_name, current_utilization, limit_value
 '''
 ignorezeroresult = true
 
 [[metric]]
 context = "asm_diskgroup"
-labels = [ "name" ]
+labels = [ "inst_id", "name" ]
 metricsdesc = { total = "Total size of ASM disk group.", free = "Free space available on ASM disk group." }
 request = '''
-select name, total_mb*1024*1024 as total, free_mb*1024*1024 as free
+select inst_id, name, total_mb*1024*1024 as total, free_mb*1024*1024 as free
 from gv$asm_diskgroup_stat
 where exists (select 1 from gv$datafile where name like '+%')
 and inst_id = (select max(inst_id) from gv$instance)
-group by name, total_mb, free_mb
+group by inst_id, name, total_mb, free_mb
 '''
 ignorezeroresult = true
 
 [[metric]]
 context = "activity"
+labels = [ "inst_id" ]
 metricsdesc = { value="Generic counter metric from gv$sysstat view in Oracle." }
 fieldtoappend = "name"
 request = '''
-select name, value from gv$sysstat
+select inst_id, name, value from gv$sysstat
 where name in ('parse count (total)', 'execute count', 'user commits', 'user rollbacks')
+group by inst_id, name, value
 '''
 
 [[metric]]
 context = "process"
+labels = [ "inst_id" ]
 metricsdesc = { count="Gauge metric with count of processes." }
-request = "select count(*) as count from gv$process"
+request = '''
+select inst_id, count(*) as count
+from gv$process
+group by inst_id
+'''
 
 [[metric]]
 context = "wait_time"
-labels = ["wait_class","con_id"]
+labels = [ "inst_id", "wait_class", "con_id" ]
 metricsdesc = { time_waited_sec_total="counter metric from system_wait_class view in Oracle." }
 metricstype = { time_waited_sec_total = "counter" }
 fieldtoappend= "wait_class"
 request = '''
 select
+  inst_id,
   wait_class,
   round(time_waited/100,3) time_waited_sec_total,
   con_id
 from gv$system_wait_class
 where wait_class <> 'Idle'
+group by inst_id, wait_class, con_id, time_waited_sec_total
 '''
 ignorezeroresult = true
 
@@ -90,29 +100,32 @@ order by tablespace
 
 [[metric]]
 context = "db_system"
-labels = [ "name" ]
+labels = [ "inst_id", "name" ]
 metricsdesc = { value = "Database system resources metric" }
 request = '''
-select name, value
+select inst_id, name, value
 from gv$parameter
 where name in ('cpu_count', 'sga_max_size', 'pga_aggregate_limit')
+group by inst_id, name, value
 '''
 
 [[metric]]
 context = "db_platform"
-labels = [ "platform_name" ]
+labels = [ "inst_id", "platform_name" ]
 metricsdesc = { value = "Database platform" }
 request = '''
-SELECT platform_name, 1 as value FROM gv$database
+SELECT platform_name, 1 as value
+FROM gv$database
+GROUP BY inst_id, platform_name
 '''
 
 [[metric]]
 context = "top_sql"
-labels = [ "sql_id", "sql_text" ]
+labels = [ "inst_id", "sql_id", "sql_text" ]
 metricsdesc = { elapsed = "SQL statement elapsed time running" }
 request = '''
 select * from (
-select sql_id, elapsed_time / 1000000 as elapsed, substrb(replace(sql_text,'',' '),1,55) as sql_text
+select inst_id, sql_id, elapsed_time / 1000000 as elapsed, substrb(replace(sql_text,'',' '),1,55) as sql_text
 from   gv$sqlstats
 order by elapsed_time desc
 ) where rownum <= 15
@@ -126,7 +139,7 @@ ignorezeroresult = true
 
 [[metric]]
 context = "cache_hit_ratio"
-labels = [ "cache_hit_type" ]
+labels = [ "inst_id", "cache_hit_type" ]
 metricsdesc = { value = "Cache Hit Ratio" }
 request = '''
 select metric_name cache_hit_type, value

custom-metrics-example/custom-metrics.toml

@@ -1,19 +1,23 @@
 [[metric]]
 context = "slow_queries"
+labels = [ "inst_id" ]
 metricsdesc = { p95_time_usecs= "Gauge metric with percentile 95 of elapsed time.", p99_time_usecs= "Gauge metric with percentile 99 of elapsed time." }
 request = '''
-select percentile_disc(0.95) within group (order by elapsed_time) as p95_time_usecs, percentile_disc(0.99) within group (order by elapsed_time) as p99_time_usecs
+select inst_id, percentile_disc(0.95) within group (order by elapsed_time) as p95_time_usecs, percentile_disc(0.99) within group (order by elapsed_time) as p99_time_usecs
 from gv$sql
 where last_active_time >= sysdate - 5/(24*60)
+group by inst_id
 '''
 
 [[metric]]
 context = "big_queries"
+labels = [ "inst_id" ]
 metricsdesc = { p95_rows= "Gauge metric with percentile 95 of returned rows.", p99_rows= "Gauge metric with percentile 99 of returned rows." }
 request = '''
-select percentile_disc(0.95) within group (order by rownum) as p95_rows, percentile_disc(0.99) within group (order by rownum) as p99_rows
+select inst_id, percentile_disc(0.95) within group (order by rownum) as p95_rows, percentile_disc(0.99) within group (order by rownum) as p99_rows
 from gv$sql
 where last_active_time >= sysdate - 5/(24*60)
+group by inst_id
 '''
 
 # User segment queries may return zero rows on certain database configurations

default-metrics.toml

@@ -1,63 +1,73 @@
 [[metric]]
 context = "sessions"
-labels = [ "status", "type" ]
-metricsdesc = { value= "Gauge metric with count of sessions by status and type." }
+labels = [ "inst_id", "status", "type" ]
+metricsdesc = { value= "Gauge metric with count of sessions by inst_id, status and type." }
 request = '''
-select status, type, count(*) as value
+select inst_id, status, type, count(*) as value
 from gv$session
-group by status, type
+group by inst_id, status, type
 '''
 
 [[metric]]
 context = "resource"
-labels = [ "resource_name" ]
-metricsdesc = { current_utilization= "Generic counter metric from v$resource_limit view in Oracle (current value).", limit_value="Generic counter metric from v$resource_limit view in Oracle (UNLIMITED: -1)." }
+labels = [ "inst_id", "resource_name" ]
+metricsdesc = { current_utilization= "Generic counter metric from gv$resource_limit view in Oracle (current value).", limit_value="Generic counter metric from v$resource_limit view in Oracle (UNLIMITED: -1)." }
 request = '''
-select resource_name, current_utilization, case when trim(limit_value) like 'UNLIMITED' then '-1' else trim(limit_value) end as limit_value
+select inst_id, resource_name, current_utilization, case when trim(limit_value) like 'UNLIMITED' then '-1' else trim(limit_value) end as limit_value
 from gv$resource_limit
+group by inst_id, resource_name, current_utilization, limit_value
 '''
 ignorezeroresult = true
 
 [[metric]]
 context = "asm_diskgroup"
-labels = [ "name" ]
+labels = [ "inst_id", "name" ]
 metricsdesc = { total = "Total size of ASM disk group.", free = "Free space available on ASM disk group." }
 request = '''
-select name, total_mb*1024*1024 as total, free_mb*1024*1024 as free
+select inst_id, name, total_mb*1024*1024 as total, free_mb*1024*1024 as free
 from gv$asm_diskgroup_stat
 where exists (select 1 from gv$datafile where name like '+%')
 and inst_id = (select max(inst_id) from gv$instance)
-group by name, total_mb, free_mb
+group by inst_id, name, total_mb, free_mb
 '''
 ignorezeroresult = true
 
 [[metric]]
 context = "activity"
+labels = [ "inst_id" ]
 metricsdesc = { value="Generic counter metric from gv$sysstat view in Oracle." }
 fieldtoappend = "name"
 request = '''
-select name, value from gv$sysstat
+select inst_id, name, value from gv$sysstat
 where name in ('parse count (total)', 'execute count', 'user commits', 'user rollbacks')
+group by inst_id, name, value
 '''
 
 [[metric]]
 context = "process"
+labels = [ "inst_id" ]
 metricsdesc = { count="Gauge metric with count of processes." }
-request = "select count(*) as count from gv$process"
+request = '''
+select inst_id, count(*) as count
+from gv$process
+group by inst_id
+'''
 
 [[metric]]
 context = "wait_time"
-labels = ["wait_class","con_id"]
+labels = [ "inst_id", "wait_class", "con_id" ]
 metricsdesc = { time_waited_sec_total="counter metric from system_wait_class view in Oracle." }
 metricstype = { time_waited_sec_total = "counter" }
 fieldtoappend= "wait_class"
 request = '''
 select
+  inst_id,
   wait_class,
   round(time_waited/100,3) time_waited_sec_total,
   con_id
 from gv$system_wait_class
 where wait_class <> 'Idle'
+group by inst_id, wait_class, con_id, time_waited_sec_total
 '''
 ignorezeroresult = true
 
@@ -90,29 +100,32 @@ order by tablespace
 
 [[metric]]
 context = "db_system"
-labels = [ "name" ]
+labels = [ "inst_id", "name" ]
 metricsdesc = { value = "Database system resources metric" }
 request = '''
-select name, value
+select inst_id, name, value
 from gv$parameter
 where name in ('cpu_count', 'sga_max_size', 'pga_aggregate_limit')
+group by inst_id, name, value
 '''
 
 [[metric]]
 context = "db_platform"
-labels = [ "platform_name" ]
+labels = [ "inst_id", "platform_name" ]
 metricsdesc = { value = "Database platform" }
 request = '''
-SELECT platform_name, 1 as value FROM gv$database
+SELECT platform_name, 1 as value
+FROM gv$database
+GROUP BY inst_id, platform_name
 '''
 
 [[metric]]
 context = "top_sql"
-labels = [ "sql_id", "sql_text" ]
+labels = [ "inst_id", "sql_id", "sql_text" ]
 metricsdesc = { elapsed = "SQL statement elapsed time running" }
 request = '''
 select * from (
-select sql_id, elapsed_time / 1000000 as elapsed, substrb(replace(sql_text,'',' '),1,55) as sql_text
+select inst_id, sql_id, elapsed_time / 1000000 as elapsed, substrb(replace(sql_text,'',' '),1,55) as sql_text
 from   gv$sqlstats
 order by elapsed_time desc
 ) where rownum <= 15
@@ -126,7 +139,7 @@ ignorezeroresult = true
 
 [[metric]]
 context = "cache_hit_ratio"
-labels = [ "cache_hit_type" ]
+labels = [ "inst_id", "cache_hit_type" ]
 metricsdesc = { value = "Cache Hit Ratio" }
 request = '''
 select metric_name cache_hit_type, value

site/docs/configuration/multiple-databases.md

@@ -118,7 +118,7 @@ databases:
     #   label_name2: label_value2
 ```
 
-### Only scraping metrics from specific databases
+### Scraping specific metrics from specific databases
 
 By default, metrics are scraped from every connected database. To expose only certain metrics on specific databases, configure the `databases` property of a metric. The following metric definition will only be scraped from databases "db2" and "db3":
 
@@ -133,4 +133,12 @@ SELECT platform_name, 1 as value FROM gv$database
 databases = [ "db2", "db3" ]
 ```
 
-If the `databases` array is empty or not provided for a metric, that metric will be scraped from all connected databases.
+If the `databases` array is empty or not provided for a metric, that metric will be scraped from all connected databases.
+
+### Duplicated database configurations
+
+If one or more database configurations are "duplicated", that is, using the same URL and username, a WARN message is logged:
+
+```
+msg="duplicated database connections" "database connections"="db1, db2 count=2
+```

site/docs/releases/changelog.md

@@ -11,6 +11,10 @@ List of upcoming and historic changes to the exporter.
 
 Our current priorities are support for Exadata metrics.  We expect to address these in an upcoming release.
 
+- Added WARN logging when database configurations are duplicated in the exporter configuration.
+- Added INST_ID to `gv$` query metrics as a label.
+- Fixed multiple concurrency bugs when the exporter is connected to multiple databases and using a custom scrape interval.
+
 ### Version 2.0.3, August 27, 2025
 
 This release includes the following changes: