Release 1.3 (#96)

### Version 1.3.0, June 7, 2024

This release includes the following changes:

- Alert logs can be exported for collection by a log reader like Promtail or FluentBit. Default
  output to `/log/alert.log` in JSON format.
- Provide ability to connect as SYSDBA or SYSOPER by setting DB_ROLE.
- New default metric is added to report the type of database connected to (CDB or PDB).
- New default metrics are added for cache hit ratios.
- Deafult metrics updated to suppress spurious warnings in log.
- Wait class metric updated to use a better query.
- The sample dashboard is updated to include new metrics.
- Fixed a bug which prevented periodic freeing of memory.
- Set CLIENT_INFO to a meaningful value.
- Update Go toolchain to 1.22.4.
- Updated some third-party dependencies.

Thank you to the following people for their suggestions and contributions:

- [@pioro](https://github.com/pioro)
- [@savoir81](https://github.com/savoir81)
---------

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

Author: markxnelson

Dockerfile

@@ -2,10 +2,10 @@ ARG BASE_IMAGE
 FROM ${BASE_IMAGE} AS build
 
 RUN microdnf install wget gzip gcc && \
-    wget https://go.dev/dl/go1.21.6.linux-amd64.tar.gz && \
+    wget -q https://go.dev/dl/go1.22.4.linux-amd64.tar.gz && \
     rm -rf /usr/local/go && \
-    tar -C /usr/local -xzf go1.21.6.linux-amd64.tar.gz && \
-    rm go1.21.6.linux-amd64.tar.gz
+    tar -C /usr/local -xzf go1.22.4.linux-amd64.tar.gz && \
+    rm go1.22.4.linux-amd64.tar.gz
 
 ENV PATH $PATH:/usr/local/go/bin
 
@@ -25,7 +25,7 @@ LABEL org.opencontainers.image.description="Oracle Database Observability Export
 ENV VERSION ${VERSION:-1.0.0}
 ENV DEBIAN_FRONTEND=noninteractive
 
-RUN  microdnf install -y oracle-instantclient-release-el8 && microdnf install -y oracle-instantclient-basic
+RUN microdnf install -y oracle-instantclient-release-el8 && microdnf install -y oracle-instantclient-basic
 
 ENV LD_LIBRARY_PATH /usr/lib/oracle/21/client64/lib
 ENV PATH $PATH:/usr/lib/oracle/21/client64/bin
@@ -34,6 +34,9 @@ ENV ORACLE_HOME /usr/lib/oracle/21/client64
 COPY --from=build /go/src/oracledb_exporter/oracle-db-appdev-monitoring /oracledb_exporter
 ADD ./default-metrics.toml /default-metrics.toml
 
+# create the mount point for alert log exports (default location)
+RUN mkdir /log && chown 1000:1000 /log
+
 EXPOSE 9161
 
 USER 1000

LICENSE.txt

@@ -21,7 +21,7 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 --
 
-Copyright (c) 2021, 2023, Oracle and/or its affiliates.
+Copyright (c) 2021, 2024, Oracle and/or its affiliates.
 
 The Universal Permissive License (UPL), Version 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        ?= 1.2.1
+VERSION        ?= 1.3.0
 LDFLAGS        := -X main.Version=$(VERSION)
 GOFLAGS        := -ldflags "$(LDFLAGS) -s -w"
 BUILD_ARGS      = --build-arg VERSION=$(VERSION)

README.md

@@ -0,0 +1,142 @@
+// 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 vault
+
+package alertlog
+
+import (
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/go-kit/log"
+	"github.com/go-kit/log/level"
+)
+
+type LogRecord struct {
+	Timestamp string `json:"timestamp"`
+	ModuleId  string `json:"moduleId"`
+	ECID      string `json:"ecid"`
+	Message   string `json:"message"`
+}
+
+func UpdateLog(logDestination string, logger log.Logger, db *sql.DB) {
+
+	// check if the log file exists, and if not, create it
+	if _, err := os.Stat(logDestination); errors.Is(err, os.ErrNotExist) {
+		level.Info(logger).Log("msg", "Log destination file does not exist, will try to create it: "+logDestination)
+		f, e := os.Create(logDestination)
+		if e != nil {
+			level.Error(logger).Log("msg", "Failed to create the log file: "+logDestination)
+			return
+		}
+		f.Close()
+	}
+
+	// read the last line of the file to get the latest timestamp
+	file, err := os.Open(logDestination)
+
+	if err != nil {
+		level.Error(logger).Log("msg", "Could not open the alert log destination file: "+logDestination)
+		return
+	}
+
+	// create an empty line
+	line := ""
+
+	// the file could be very large, so we will read backwards from the end of the file
+	// until the first line break is found, or until we reach the start of the file
+	var pointer int64 = 0
+	stat, _ := file.Stat()
+	filesize := stat.Size()
+
+	for {
+		if filesize == 0 {
+			break
+		}
+
+		pointer -= 1
+		file.Seek(pointer, io.SeekEnd)
+
+		char := make([]byte, 1)
+		file.Read(char)
+
+		if pointer != -1 && (char[0] == 10 || char[0] == 13) {
+			// we found a new line
+			break
+		}
+
+		line = fmt.Sprintf("%s%s", string(char), line)
+
+		if pointer == -filesize {
+			// we got all the way to the start of the file
+			break
+		}
+	}
+
+	// if we got an empty line, then set a reasonable default
+	if len(line) <= 1 {
+		//                    2024-06-06T14:01:22.513Z
+		line = `{"timestamp":"1900-01-01T01:01:01.001Z","moduleId":"","ecid":"","message":""}`
+	}
+
+	file.Close()
+
+	// read the timestamp from the line
+	var lastLogRecord LogRecord
+	err = json.Unmarshal([]byte(line), &lastLogRecord)
+	if err != nil {
+		level.Error(logger).Log("msg", "Could not parse last line of log file")
+		return
+	}
+
+	// query for any new alert log entries
+	stmt := fmt.Sprintf(`select originating_timestamp, module_id, execution_context_id, message_text
+		from v$diag_alert_ext
+		where originating_timestamp > to_utc_timestamp_tz('%s')`, lastLogRecord.Timestamp)
+
+	rows, err := db.Query(stmt)
+	if err != nil {
+		level.Error(logger).Log("msg", "Error querying the alert logs")
+		return
+	}
+	defer rows.Close()
+
+	// write them to the file
+	outfile, err := os.OpenFile(logDestination, os.O_APPEND|os.O_WRONLY, 0600)
+	if err != nil {
+		level.Error(logger).Log("msg", "Could not open log file for writing: "+logDestination)
+		return
+	}
+
+	defer outfile.Close()
+
+	for rows.Next() {
+		var newRecord LogRecord
+		if err := rows.Scan(&newRecord.Timestamp, &newRecord.ModuleId, &newRecord.ECID, &newRecord.Message); err != nil {
+			level.Error(logger).Log("msg", "Error reading a row from the alert logs")
+			return
+		}
+
+		// strip the newline from end of message
+		newRecord.Message = strings.TrimSuffix(newRecord.Message, "\n")
+
+		jsonLogRecord, err := json.Marshal(newRecord)
+		if err != nil {
+			level.Error(logger).Log("msg", "Error marshalling alert log record")
+			return
+		}
+
+		if _, err = outfile.WriteString(string(jsonLogRecord) + "\n"); err != nil {
+			level.Error(logger).Log("msg", "Could not write to log file: "+logDestination)
+			return
+		}
+	}
+
+	if err = rows.Err(); err != nil {
+		level.Error(logger).Log("msg", "Error querying the alert logs")
+	}
+}

THIRD_PARTY_LICENSES.txt

@@ -1,4 +1,4 @@
-// Copyright (c) 2021, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2021, 2024, Oracle and/or its affiliates.
 // Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
 // Portions Copyright (c) 2016 Seth Miller <seth@sethmiller.me>
 
@@ -40,6 +40,8 @@ type Exporter struct {
 	scrapeErrors    *prometheus.CounterVec
 	scrapeResults   []prometheus.Metric
 	up              prometheus.Gauge
+	dbtype          int
+	dbtypeGauge     prometheus.Gauge
 	db              *sql.DB
 	logger          log.Logger
 }
@@ -49,6 +51,7 @@ type Config struct {
 	User               string
 	Password           string
 	ConnectString      string
+	DbRole             string
 	MaxIdleConns       int
 	MaxOpenConns       int
 	CustomMetrics      string
@@ -137,6 +140,11 @@ func NewExporter(logger log.Logger, cfg *Config) (*Exporter, error) {
 			Name:      "up",
 			Help:      "Whether the Oracle database server is up.",
 		}),
+		dbtypeGauge: prometheus.NewGauge(prometheus.GaugeOpts{
+			Namespace: namespace,
+			Name:      "dbtype",
+			Help:      "Type of database the exporter is connected to (0=non-CDB, 1=CDB, >1=PDB).",
+		}),
 		logger: logger,
 		config: cfg,
 	}
@@ -196,6 +204,7 @@ func (e *Exporter) Collect(ch chan<- prometheus.Metric) {
 	ch <- e.error
 	e.scrapeErrors.Collect(ch)
 	ch <- e.up
+	ch <- e.dbtypeGauge
 }
 
 // RunScheduledScrapes is only relevant for users of this package that want to set the scrape on a timer
@@ -277,6 +286,8 @@ func (e *Exporter) scrape(ch chan<- prometheus.Metric) {
 		return
 	}
 
+	e.dbtypeGauge.Set(float64(e.dbtype))
+
 	level.Debug(e.logger).Log("msg", "Successfully pinged Oracle database: "+maskDsn(e.connectString))
 	e.up.Set(1)
 
@@ -325,11 +336,15 @@ func (e *Exporter) scrape(ch chan<- prometheus.Metric) {
 
 			scrapeStart := time.Now()
 			if err = e.ScrapeMetric(e.db, ch, metric); err != nil {
-				level.Error(e.logger).Log("msg", "Error scraping metric",
-					"Context", metric.Context,
-					"MetricsDesc", fmt.Sprint(metric.MetricsDesc),
-					"time", time.Since(scrapeStart),
-					"error", err)
+				if !metric.IgnoreZeroResult {
+					// do not print repetitive error messages for metrics
+					// with ignoreZeroResult set to true
+					level.Error(e.logger).Log("msg", "Error scraping metric",
+						"Context", metric.Context,
+						"MetricsDesc", fmt.Sprint(metric.MetricsDesc),
+						"time", time.Since(scrapeStart),
+						"error", err)
+				}
 				e.scrapeErrors.WithLabelValues(metric.Context).Inc()
 			} else {
 				level.Debug(e.logger).Log("msg", "Successfully scraped metric",
@@ -348,6 +363,14 @@ func (e *Exporter) connect() error {
 	var P godror.ConnectionParams
 	P.Username, P.Password, P.ConnectString = e.user, godror.NewPassword(e.password), e.connectString
 
+	if strings.ToUpper(e.config.DbRole) == "SYSDBA" {
+		P.IsSysDBA = true
+	}
+
+	if strings.ToUpper(e.config.DbRole) == "SYSOPER" {
+		P.IsSysOper = true
+	}
+
 	level.Debug(e.logger).Log("msg", "connection properties: "+fmt.Sprint(P))
 
 	// note that this just configures the connection, it does not acutally connect until later
@@ -360,9 +383,34 @@ func (e *Exporter) connect() error {
 	db.SetConnMaxLifetime(0)
 	level.Debug(e.logger).Log("msg", "Successfully configured connection to "+maskDsn(e.connectString))
 	e.db = db
+
+	if _, err := db.Exec(`
+			begin
+	       		dbms_application_info.set_client_info('oracledb_exporter');
+			end;`); err != nil {
+		level.Info(e.logger).Log("msg", "Could not set CLIENT_INFO.")
+	}
+
+	var result int
+	if err := db.QueryRow("select sys_context('USERENV', 'CON_ID') from dual").Scan(&result); err != nil {
+		level.Info(e.logger).Log("msg", "dbtype err ="+string(err.Error()))
+	}
+	e.dbtype = result
+
+	var sysdba string
+	if err := db.QueryRow("select sys_context('USERENV', 'ISDBA') from dual").Scan(&sysdba); err != nil {
+		level.Info(e.logger).Log("msg", "got error checking my database role")
+	}
+	level.Info(e.logger).Log("msg", "Connected as SYSDBA? "+sysdba)
+
 	return nil
 }
 
+// this is used by the log exporter to share the database connection
+func (e *Exporter) GetDB() *sql.DB {
+	return e.db
+}
+
 func (e *Exporter) checkIfMetricsChanged() bool {
 	for i, _customMetrics := range strings.Split(e.config.CustomMetrics, ",") {
 		if len(_customMetrics) == 0 {