Add Query Timeout to metrics definition (#118)

* Query Timeout

---------

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

Author: anders-swanson

README.md

@@ -621,7 +621,7 @@ Usage of oracledb_exporter:
   --log.level value
        	Only log messages with the given severity or above. Valid levels: [debug, info, warn, error, fatal].
   --custom.metrics string
-        File that may contain various custom metrics in a TOML file.
+        Comma separated list of file(s) that contain various custom metrics in a TOML format.
   --default.metrics string
         Default TOML file metrics.
   --web.systemd-socket
@@ -634,6 +634,8 @@ Usage of oracledb_exporter:
         Number of maximum idle connections in the connection pool. (default "0")
   --database.maxOpenConns string
         Number of maximum open connections in the connection pool. (default "10")
+  --query.timeout int
+        Query timeout (in seconds).
   --web.config.file
         Path to configuration file that can enable TLS or authentication.
 ```
@@ -654,12 +656,21 @@ exporter, you can:
 - Use `--custom.metrics` flag followed by a comma separated list of TOML files, or
 - Export `CUSTOM_METRICS` variable environment (`export CUSTOM_METRICS=my-custom-metrics.toml,my-other-custom-metrics.toml`)
 
-This file must contain the following elements:
-
-- One or several metric sections (`[[metric]]`)
-- For each section: a context, a request and a map between the field(s) in the request and comment(s).
-
-Here's a simple example:
+Custom metrics file must contain a series of `[[metric]]` definitions, in TOML. Each metric definition must follow the custom metric schema:
+
+| Field Name       | Description                                                                                                                                                                                | Type                              | Required | Default                      |
+|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|----------|------------------------------|
+| context          | Metric context, used to build metric FQN                                                                                                                                                   | String                            | Yes      |                              |
+| labels           | Metric labels, which must match column names in the query. Any column that is not a label will be parsed as a metric                                                                       | Array of Strings                  | No       |                              |
+| metricsdesc      | Mapping between field(s) in the request and comment(s)                                                                                                                                     | Dictionary of Strings             | Yes      |                              |
+| metricstype      | Mapping between field(s) in the request and [Prometheus metric types](https://prometheus.io/docs/concepts/metric_types/)                                                                   | Dictionary of Strings             | No       |                              |
+| metricsbuckets   | Split [histogram](https://prometheus.io/docs/concepts/metric_types/#histogram) metric types into buckets based on value ([example](./custom-metrics-example/metric-histogram-example.toml)) | Dictionary of String dictionaries | No       |                              |
+| fieldtoappend    | Field from the request to append to the metric FQN                                                                                                                                         | String                            | No       |                              |
+| request          | Oracle database query to run for metrics scraping                                                                                                                                          | String                            | Yes      |                              |
+| ignorezeroresult | Whether or not an error will be printed if the request does not return any results                                                                                                         | Boolean                           | No       | false                        |
+| querytimeout     | Oracle Database query timeout, in seconds                                                                                                                                                  | Integer                           | No       | 5, or value of query.timeout |
+
+Here's a simple example of a metric definition:
 
 ```
 [[metric]]

collector/collector.go

@@ -81,6 +81,7 @@ type Metric struct {
 	FieldToAppend    string
 	Request          string
 	IgnoreZeroResult bool
+	QueryTimeout     int
 }
 
 // Metrics is a container structure for prometheus metrics
@@ -469,17 +470,17 @@ func (e *Exporter) reloadMetrics() {
 }
 
 // ScrapeMetric is an interface method to call scrapeGenericValues using Metric struct values
-func (e *Exporter) ScrapeMetric(db *sql.DB, ch chan<- prometheus.Metric, metricDefinition Metric) error {
+func (e *Exporter) ScrapeMetric(db *sql.DB, ch chan<- prometheus.Metric, m Metric) error {
 	level.Debug(e.logger).Log("msg", "Calling function ScrapeGenericValues()")
-	return e.scrapeGenericValues(db, ch, metricDefinition.Context, metricDefinition.Labels,
-		metricDefinition.MetricsDesc, metricDefinition.MetricsType, metricDefinition.MetricsBuckets,
-		metricDefinition.FieldToAppend, metricDefinition.IgnoreZeroResult,
-		metricDefinition.Request)
+	return e.scrapeGenericValues(db, ch, m.Context, m.Labels, m.MetricsDesc,
+		m.MetricsType, m.MetricsBuckets, m.FieldToAppend, m.IgnoreZeroResult,
+		m.Request, m.QueryTimeout)
 }
 
 // generic method for retrieving metrics.
 func (e *Exporter) scrapeGenericValues(db *sql.DB, ch chan<- prometheus.Metric, context string, labels []string,
-	metricsDesc map[string]string, metricsType map[string]string, metricsBuckets map[string]map[string]string, fieldToAppend string, ignoreZeroResult bool, request string) error {
+	metricsDesc map[string]string, metricsType map[string]string, metricsBuckets map[string]map[string]string,
+	fieldToAppend string, ignoreZeroResult bool, request string, queryTimeout int) error {
 	metricsCount := 0
 	genericParser := func(row map[string]string) error {
 		// Construct labels value
@@ -572,7 +573,7 @@ func (e *Exporter) scrapeGenericValues(db *sql.DB, ch chan<- prometheus.Metric,
 		return nil
 	}
 	level.Debug(e.logger).Log("msg", "Calling function GeneratePrometheusMetrics()")
-	err := e.generatePrometheusMetrics(db, genericParser, request)
+	err := e.generatePrometheusMetrics(db, genericParser, request, queryTimeout)
 	level.Debug(e.logger).Log("msg", "ScrapeGenericValues() - metricsCount: "+strconv.Itoa(metricsCount))
 	if err != nil {
 		return err
@@ -585,8 +586,13 @@ func (e *Exporter) scrapeGenericValues(db *sql.DB, ch chan<- prometheus.Metric,
 
 // inspired by https://kylewbanks.com/blog/query-result-to-map-in-golang
 // Parse SQL result and call parsing function to each row
-func (e *Exporter) generatePrometheusMetrics(db *sql.DB, parse func(row map[string]string) error, query string) error {
-	ctx, cancel := context.WithTimeout(context.Background(), time.Duration(e.config.QueryTimeout)*time.Second)
+func (e *Exporter) generatePrometheusMetrics(db *sql.DB, parse func(row map[string]string) error, query string, queryTimeout int) error {
+	timeout := e.config.QueryTimeout
+	if queryTimeout > 0 {
+		timeout = queryTimeout
+	}
+	timeoutDuration := time.Duration(timeout) * time.Second
+	ctx, cancel := context.WithTimeout(context.Background(), timeoutDuration)
 	defer cancel()
 	rows, err := db.QueryContext(ctx, query)
 

collector/metrics.go

@@ -0,0 +1,23 @@
+// Copyright (c) 2024, Oracle and/or its affiliates.
+// Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
+
+package collector
+
+import (
+	"github.com/go-kit/log/level"
+	"strconv"
+)
+
+func (e *Exporter) parseFloat(metric, metricHelp string, row map[string]string) (float64, bool) {
+	value, ok := row[metric]
+	if !ok {
+		return -1, ok
+	}
+	valueFloat, err := strconv.ParseFloat(value, 64)
+	if err != nil {
+		level.Error(e.logger).Log("msg", "Unable to convert current value to float (metric="+metric+
+			",metricHelp="+metricHelp+",value=<"+row[metric]+">)")
+		return -1, false
+	}
+	return valueFloat, true
+}