From 4f574ab39dfdf3cf9e59a1de3a7103b1ab150a87 Mon Sep 17 00:00:00 2001 From: Anders Swanson Date: Tue, 28 Oct 2025 11:10:59 -0700 Subject: [PATCH] 2.2.0 changes Signed-off-by: Anders Swanson --- Dockerfile | 9 +- Makefile | 2 +- azvault/azvault.go | 2 +- go.mod | 26 +- go.sum | 52 +-- site/docs/configuration/config-file.md | 4 +- site/docs/configuration/custom-metrics.md | 2 +- site/docs/configuration/oracle-wallet.md | 2 +- site/docs/getting-started/basics.md | 2 +- site/docs/intro.md | 2 +- site/docs/releases/builds.md | 4 +- site/docs/releases/changelog.md | 8 + site/docusaurus.config.ts | 2 +- .../version-2.2.0/advanced/_category_.json | 8 + .../version-2.2.0/advanced/development.md | 54 +++ .../version-2.2.0/advanced/go-ora.md | 28 ++ .../version-2.2.0/advanced/go-runtime.md | 14 + .../version-2.2.0/advanced/older-versions.md | 34 ++ .../version-2.2.0/advanced/txeventq.md | 117 +++++++ .../configuration/_category_.json | 8 + .../version-2.2.0/configuration/alert-logs.md | 30 ++ .../configuration/azure-vault.md | 40 +++ .../configuration/config-file.md | 119 +++++++ .../configuration/custom-metrics.md | 193 +++++++++++ .../configuration/hashicorp-vault.md | 125 +++++++ .../configuration/multiple-databases.md | 144 ++++++++ .../version-2.2.0/configuration/oci-vault.md | 30 ++ .../configuration/oracle-wallet.md | 109 ++++++ .../getting-started/_category_.json | 8 + .../version-2.2.0/getting-started/basics.md | 253 ++++++++++++++ .../getting-started/default-metrics.md | 136 ++++++++ .../getting-started/grafana-dashboards.md | 14 + .../getting-started/kubernetes.md | 116 +++++++ site/versioned_docs/version-2.2.0/intro.md | 43 +++ .../version-2.2.0/releases/_category_.json | 8 + .../version-2.2.0/releases/builds.md | 101 ++++++ .../version-2.2.0/releases/changelog.md | 321 ++++++++++++++++++ .../version-2.2.0/releases/roadmap.md | 21 ++ .../version-2.2.0-sidebars.json | 8 + site/versions.json | 1 + 40 files changed, 2148 insertions(+), 52 deletions(-) create mode 100644 site/versioned_docs/version-2.2.0/advanced/_category_.json create mode 100644 site/versioned_docs/version-2.2.0/advanced/development.md create mode 100644 site/versioned_docs/version-2.2.0/advanced/go-ora.md create mode 100644 site/versioned_docs/version-2.2.0/advanced/go-runtime.md create mode 100644 site/versioned_docs/version-2.2.0/advanced/older-versions.md create mode 100644 site/versioned_docs/version-2.2.0/advanced/txeventq.md create mode 100644 site/versioned_docs/version-2.2.0/configuration/_category_.json create mode 100644 site/versioned_docs/version-2.2.0/configuration/alert-logs.md create mode 100644 site/versioned_docs/version-2.2.0/configuration/azure-vault.md create mode 100644 site/versioned_docs/version-2.2.0/configuration/config-file.md create mode 100644 site/versioned_docs/version-2.2.0/configuration/custom-metrics.md create mode 100644 site/versioned_docs/version-2.2.0/configuration/hashicorp-vault.md create mode 100644 site/versioned_docs/version-2.2.0/configuration/multiple-databases.md create mode 100644 site/versioned_docs/version-2.2.0/configuration/oci-vault.md create mode 100644 site/versioned_docs/version-2.2.0/configuration/oracle-wallet.md create mode 100644 site/versioned_docs/version-2.2.0/getting-started/_category_.json create mode 100644 site/versioned_docs/version-2.2.0/getting-started/basics.md create mode 100644 site/versioned_docs/version-2.2.0/getting-started/default-metrics.md create mode 100644 site/versioned_docs/version-2.2.0/getting-started/grafana-dashboards.md create mode 100644 site/versioned_docs/version-2.2.0/getting-started/kubernetes.md create mode 100644 site/versioned_docs/version-2.2.0/intro.md create mode 100644 site/versioned_docs/version-2.2.0/releases/_category_.json create mode 100644 site/versioned_docs/version-2.2.0/releases/builds.md create mode 100644 site/versioned_docs/version-2.2.0/releases/changelog.md create mode 100644 site/versioned_docs/version-2.2.0/releases/roadmap.md create mode 100644 site/versioned_sidebars/version-2.2.0-sidebars.json diff --git a/Dockerfile b/Dockerfile index 69e1e56f..61394c2b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -13,11 +13,14 @@ ENV TAGS=${TAGS:-godror} ARG CGO_ENABLED ENV CGO_ENABLED=${CGO_ENABLED:-1} +ARG GO_VERSION +ENV GO_VERSION=${GO_VERSION:-1.24.9} + RUN microdnf install wget gzip gcc && \ - wget -q https://go.dev/dl/go1.23.10.${GOOS}-${GOARCH}.tar.gz && \ + wget -q https://go.dev/dl/go${GO_VERSION}.${GOOS}-${GOARCH}.tar.gz && \ rm -rf /usr/local/go && \ - tar -C /usr/local -xzf go1.23.10.${GOOS}-${GOARCH}.tar.gz && \ - rm go1.23.10.${GOOS}-${GOARCH}.tar.gz + tar -C /usr/local -xzf go${GO_VERSION}.${GOOS}-${GOARCH}.tar.gz && \ + rm go${GO_VERSION}.${GOOS}-${GOARCH}.tar.gz ENV PATH=$PATH:/usr/local/go/bin diff --git a/Makefile b/Makefile index b64f7d4b..561698a0 100644 --- a/Makefile +++ b/Makefile @@ -6,7 +6,7 @@ GOARCH ?= $(shell go env GOARCH) TAGS ?= godror DOCKER_TARGET ?= exporter-godror CGO_ENABLED ?= 1 -VERSION ?= 2.1.0 +VERSION ?= 2.2.0 LDFLAGS := -X main.Version=$(VERSION) GOFLAGS := -ldflags "$(LDFLAGS) -s -w" --tags $(TAGS) BUILD_ARGS = --build-arg VERSION=$(VERSION) diff --git a/azvault/azvault.go b/azvault/azvault.go index b27fe5c9..4e185c58 100755 --- a/azvault/azvault.go +++ b/azvault/azvault.go @@ -12,7 +12,7 @@ import ( "github.com/prometheus/common/promslog" "github.com/Azure/azure-sdk-for-go/sdk/azidentity" - "github.com/Azure/azure-sdk-for-go/sdk/keyvault/azsecrets" + "github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets" ) func GetVaultSecret(vaultId string, secretName string) string { diff --git a/go.mod b/go.mod index 89965204..3f1c6eb0 100644 --- a/go.mod +++ b/go.mod @@ -1,18 +1,18 @@ module github.com/oracle/oracle-db-appdev-monitoring -go 1.24.0 +go 1.24.9 require ( - github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.12.0 - github.com/Azure/azure-sdk-for-go/sdk/keyvault/azsecrets v0.12.0 + github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.13.0 + github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets v1.4.0 github.com/BurntSushi/toml v1.5.0 github.com/alecthomas/kingpin/v2 v2.4.0 github.com/godror/godror v0.49.4 github.com/hashicorp/vault/api v1.22.0 - github.com/oracle/oci-go-sdk/v65 v65.102.1 + github.com/oracle/oci-go-sdk/v65 v65.103.0 github.com/prometheus/client_golang v1.23.2 - github.com/prometheus/common v0.67.1 - github.com/prometheus/exporter-toolkit v0.14.1 + github.com/prometheus/common v0.67.2 + github.com/prometheus/exporter-toolkit v0.15.0 github.com/sijms/go-ora/v2 v2.9.0 gopkg.in/yaml.v2 v2.4.0 ) @@ -20,7 +20,7 @@ require ( require ( github.com/Azure/azure-sdk-for-go/sdk/azcore v1.19.1 // indirect github.com/Azure/azure-sdk-for-go/sdk/internal v1.11.2 // indirect - github.com/Azure/azure-sdk-for-go/sdk/keyvault/internal v0.7.1 // indirect + github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/internal v1.2.0 // indirect github.com/AzureAD/microsoft-authentication-library-for-go v1.5.0 // indirect github.com/VictoriaMetrics/easyproto v0.1.4 // indirect github.com/alecthomas/units v0.0.0-20240927000941-0f3dac36c52b // indirect @@ -59,13 +59,13 @@ require ( github.com/xhit/go-str2duration/v2 v2.1.0 // indirect github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect go.yaml.in/yaml/v2 v2.4.3 // indirect - golang.org/x/crypto v0.42.0 // indirect + golang.org/x/crypto v0.43.0 // indirect golang.org/x/exp v0.0.0-20250506013437-ce4c2cf36ca6 // indirect - golang.org/x/net v0.44.0 // indirect - golang.org/x/oauth2 v0.31.0 // indirect + golang.org/x/net v0.46.0 // indirect + golang.org/x/oauth2 v0.32.0 // indirect golang.org/x/sync v0.17.0 // indirect - golang.org/x/sys v0.36.0 // indirect - golang.org/x/text v0.29.0 // indirect - golang.org/x/time v0.12.0 // indirect + golang.org/x/sys v0.37.0 // indirect + golang.org/x/text v0.30.0 // indirect + golang.org/x/time v0.13.0 // indirect google.golang.org/protobuf v1.36.10 // indirect ) diff --git a/go.sum b/go.sum index 274b04e6..9700a1b3 100644 --- a/go.sum +++ b/go.sum @@ -1,15 +1,15 @@ github.com/Azure/azure-sdk-for-go/sdk/azcore v1.19.1 h1:5YTBM8QDVIBN3sxBil89WfdAAqDZbyJTgh688DSxX5w= github.com/Azure/azure-sdk-for-go/sdk/azcore v1.19.1/go.mod h1:YD5h/ldMsG0XiIw7PdyNhLxaM317eFh5yNLccNfGdyw= -github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.12.0 h1:wL5IEG5zb7BVv1Kv0Xm92orq+5hB5Nipn3B5tn4Rqfk= -github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.12.0/go.mod h1:J7MUC/wtRpfGVbQ5sIItY5/FuVWmvzlY21WAOfQnq/I= +github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.13.0 h1:KpMC6LFL7mqpExyMC9jVOYRiVhLmamjeZfRsUpB7l4s= +github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.13.0/go.mod h1:J7MUC/wtRpfGVbQ5sIItY5/FuVWmvzlY21WAOfQnq/I= github.com/Azure/azure-sdk-for-go/sdk/azidentity/cache v0.3.2 h1:yz1bePFlP5Vws5+8ez6T3HWXPmwOK7Yvq8QxDBD3SKY= github.com/Azure/azure-sdk-for-go/sdk/azidentity/cache v0.3.2/go.mod h1:Pa9ZNPuoNu/GztvBSKk9J1cDJW6vk/n0zLtV4mgd8N8= github.com/Azure/azure-sdk-for-go/sdk/internal v1.11.2 h1:9iefClla7iYpfYWdzPCRDozdmndjTm8DXdpCzPajMgA= github.com/Azure/azure-sdk-for-go/sdk/internal v1.11.2/go.mod h1:XtLgD3ZD34DAaVIIAyG3objl5DynM3CQ/vMcbBNJZGI= -github.com/Azure/azure-sdk-for-go/sdk/keyvault/azsecrets v0.12.0 h1:xnO4sFyG8UH2fElBkcqLTOZsAajvKfnSlgBBW8dXYjw= -github.com/Azure/azure-sdk-for-go/sdk/keyvault/azsecrets v0.12.0/go.mod h1:XD3DIOOVgBCO03OleB1fHjgktVRFxlT++KwKgIOewdM= -github.com/Azure/azure-sdk-for-go/sdk/keyvault/internal v0.7.1 h1:FbH3BbSb4bvGluTesZZ+ttN/MDsnMmQP36OSnDuSXqw= -github.com/Azure/azure-sdk-for-go/sdk/keyvault/internal v0.7.1/go.mod h1:9V2j0jn9jDEkCkv8w/bKTNppX/d0FVA1ud77xCIP4KA= +github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets v1.4.0 h1:/g8S6wk65vfC6m3FIxJ+i5QDyN9JWwXI8Hb0Img10hU= +github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets v1.4.0/go.mod h1:gpl+q95AzZlKVI3xSoseF9QPrypk0hQqBiJYeB/cR/I= +github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/internal v1.2.0 h1:nCYfgcSyHZXJI8J0IWE5MsCGlb2xp9fJiXyxWgmOFg4= +github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/internal v1.2.0/go.mod h1:ucUjca2JtSZboY8IoUqyQyuuXvwbMBVwFOm0vdQPNhA= github.com/AzureAD/microsoft-authentication-extensions-for-go/cache v0.1.1 h1:WJTmL004Abzc5wDB5VtZG2PJk5ndYDgVacGqfirKxjM= github.com/AzureAD/microsoft-authentication-extensions-for-go/cache v0.1.1/go.mod h1:tCcJZ0uHAmvjsVYzEFivsRTN00oz5BEsRgQHu5JZ9WE= github.com/AzureAD/microsoft-authentication-library-for-go v1.5.0 h1:XkkQbfMyuH2jTSjQjSoihryI8GINRcs4xp8lNawg0FI= @@ -110,8 +110,8 @@ github.com/mwitkow/go-conntrack v0.0.0-20190716064945-2f068394615f h1:KUppIJq7/+ github.com/mwitkow/go-conntrack v0.0.0-20190716064945-2f068394615f/go.mod h1:qRWi+5nqEBWmkhHvq77mSJWrCKwh8bxhgT7d/eI7P4U= github.com/oklog/ulid/v2 v2.0.2 h1:r4fFzBm+bv0wNKNh5eXTwU7i85y5x+uwkxCUTNVQqLc= github.com/oklog/ulid/v2 v2.0.2/go.mod h1:mtBL0Qe/0HAx6/a4Z30qxVIAL1eQDweXq5lxOEiwQ68= -github.com/oracle/oci-go-sdk/v65 v65.102.1 h1:zLNLz5dVzZxOf5DK/f3WGZUjwrQ9m27fd4abOFwQRCQ= -github.com/oracle/oci-go-sdk/v65 v65.102.1/go.mod h1:oB8jFGVc/7/zJ+DbleE8MzGHjhs2ioCz5stRTdZdIcY= +github.com/oracle/oci-go-sdk/v65 v65.103.0 h1:HfyZx+JefCPK3At0Xt45q+wr914jDXuoyzOFX3XCbno= +github.com/oracle/oci-go-sdk/v65 v65.103.0/go.mod h1:oB8jFGVc/7/zJ+DbleE8MzGHjhs2ioCz5stRTdZdIcY= 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= @@ -120,10 +120,10 @@ github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg= github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk= github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE= -github.com/prometheus/common v0.67.1 h1:OTSON1P4DNxzTg4hmKCc37o4ZAZDv0cfXLkOt0oEowI= -github.com/prometheus/common v0.67.1/go.mod h1:RpmT9v35q2Y+lsieQsdOh5sXZ6ajUGC8NjZAmr8vb0Q= -github.com/prometheus/exporter-toolkit v0.14.1 h1:uKPE4ewweVRWFainwvAcHs3uw15pjw2dk3I7b+aNo9o= -github.com/prometheus/exporter-toolkit v0.14.1/go.mod h1:di7yaAJiaMkcjcz48f/u4yRPwtyuxTU5Jr4EnM2mhtQ= +github.com/prometheus/common v0.67.2 h1:PcBAckGFTIHt2+L3I33uNRTlKTplNzFctXcWhPyAEN8= +github.com/prometheus/common v0.67.2/go.mod h1:63W3KZb1JOKgcjlIr64WW/LvFGAqKPj0atm+knVGEko= +github.com/prometheus/exporter-toolkit v0.15.0 h1:Pcle5sSViwR1x0gdPd0wtYrPQENBieQAM7TmT0qtb2U= +github.com/prometheus/exporter-toolkit v0.15.0/go.mod h1:OyRWd2iTo6Xge9Kedvv0IhCrJSBu36JCfJ2yVniRIYk= github.com/prometheus/procfs v0.16.1 h1:hZ15bTNuirocR6u0JZ6BAHHmwS1p8B4P6MRqxtzMyRg= github.com/prometheus/procfs v0.16.1/go.mod h1:teAbpZRB1iIAJYREa1LsoWUXykVXA1KlTmWl8x/U+Is= github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ= @@ -154,25 +154,25 @@ go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto= go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE= go.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0= go.yaml.in/yaml/v2 v2.4.3/go.mod h1:zSxWcmIDjOzPXpjlTTbAsKokqkDNAVtZO0WOMiT90s8= -golang.org/x/crypto v0.42.0 h1:chiH31gIWm57EkTXpwnqf8qeuMUi0yekh6mT2AvFlqI= -golang.org/x/crypto v0.42.0/go.mod h1:4+rDnOTJhQCx2q7/j6rAN5XDw8kPjeaXEUR2eL94ix8= +golang.org/x/crypto v0.43.0 h1:dduJYIi3A3KOfdGOHX8AVZ/jGiyPa3IbBozJ5kNuE04= +golang.org/x/crypto v0.43.0/go.mod h1:BFbav4mRNlXJL4wNeejLpWxB7wMbc79PdRGhWKncxR0= golang.org/x/exp v0.0.0-20250506013437-ce4c2cf36ca6 h1:y5zboxd6LQAqYIhHnB48p0ByQ/GnQx2BE33L8BOHQkI= golang.org/x/exp v0.0.0-20250506013437-ce4c2cf36ca6/go.mod h1:U6Lno4MTRCDY+Ba7aCcauB9T60gsv5s4ralQzP72ZoQ= -golang.org/x/net v0.44.0 h1:evd8IRDyfNBMBTTY5XRF1vaZlD+EmWx6x8PkhR04H/I= -golang.org/x/net v0.44.0/go.mod h1:ECOoLqd5U3Lhyeyo/QDCEVQ4sNgYsqvCZ722XogGieY= -golang.org/x/oauth2 v0.31.0 h1:8Fq0yVZLh4j4YA47vHKFTa9Ew5XIrCP8LC6UeNZnLxo= -golang.org/x/oauth2 v0.31.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA= +golang.org/x/net v0.46.0 h1:giFlY12I07fugqwPuWJi68oOnpfqFnJIJzaIIm2JVV4= +golang.org/x/net v0.46.0/go.mod h1:Q9BGdFy1y4nkUwiLvT5qtyhAnEHgnQ/zd8PfU6nc210= +golang.org/x/oauth2 v0.32.0 h1:jsCblLleRMDrxMN29H3z/k1KliIvpLgCkE6R8FXXNgY= +golang.org/x/oauth2 v0.32.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA= golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug= golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI= golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.36.0 h1:KVRy2GtZBrk1cBYA7MKu5bEZFxQk4NIDV6RLVcC8o0k= -golang.org/x/sys v0.36.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks= -golang.org/x/term v0.35.0 h1:bZBVKBudEyhRcajGcNc3jIfWPqV4y/Kt2XcoigOWtDQ= -golang.org/x/term v0.35.0/go.mod h1:TPGtkTLesOwf2DE8CgVYiZinHAOuy5AYUYT1lENIZnA= -golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk= -golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4= -golang.org/x/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE= -golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg= +golang.org/x/sys v0.37.0 h1:fdNQudmxPjkdUTPnLn5mdQv7Zwvbvpaxqs831goi9kQ= +golang.org/x/sys v0.37.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks= +golang.org/x/term v0.36.0 h1:zMPR+aF8gfksFprF/Nc/rd1wRS1EI6nDBGyWAvDzx2Q= +golang.org/x/term v0.36.0/go.mod h1:Qu394IJq6V6dCBRgwqshf3mPF85AqzYEzofzRdZkWss= +golang.org/x/text v0.30.0 h1:yznKA/E9zq54KzlzBEAWn1NXSQ8DIp/NYMy88xJjl4k= +golang.org/x/text v0.30.0/go.mod h1:yDdHFIX9t+tORqspjENWgzaCVXgk0yYnYuSZ8UzzBVM= +golang.org/x/time v0.13.0 h1:eUlYslOIt32DgYD6utsuUeHs4d7AsEYLuIAdg7FlYgI= +golang.org/x/time v0.13.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4= google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE= google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= diff --git a/site/docs/configuration/config-file.md b/site/docs/configuration/config-file.md index 72aea2b4..8565c29b 100644 --- a/site/docs/configuration/config-file.md +++ b/site/docs/configuration/config-file.md @@ -92,6 +92,8 @@ log: # configFile: /path/to/webconfigfile ``` +From the exporter configuration file, you may optionally load database credentials from [OCI Vault](./oci-vault.md), [Azure Vault](./azure-vault.md), or [HashiCorp Vault](./hashicorp-vault.md).. + ### Scrape on request vs. Scrape on interval The metrics exporter has two scraping modes: scrape on request, and scrape on interval. By default, the metrics exporter scrapes metrics on request, when the `/metrics` endpoint is invoked. @@ -111,7 +113,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.1.0 +FROM container-registry.oracle.com/database/observability-exporter:2.2.0 COPY my-exporter-config.yaml / ENTRYPOINT ["/oracledb_exporter", "--config.file", "/my-exporter-config.yaml"] ``` \ No newline at end of file diff --git a/site/docs/configuration/custom-metrics.md b/site/docs/configuration/custom-metrics.md index c3137efc..12835e2b 100644 --- a/site/docs/configuration/custom-metrics.md +++ b/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.1.0 +FROM container-registry.oracle.com/database/observability-exporter:2.2.0 COPY custom-metrics.toml / ENTRYPOINT ["/oracledb_exporter", "--custom.metrics", "/custom-metrics.toml"] ``` \ No newline at end of file diff --git a/site/docs/configuration/oracle-wallet.md b/site/docs/configuration/oracle-wallet.md index 379ba625..3da1268f 100644 --- a/site/docs/configuration/oracle-wallet.md +++ b/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.1.0 + container-registry.oracle.com/database/observability-exporter:2.2.0 ``` ### mTLS for multiple databases with Oracle Wallet diff --git a/site/docs/getting-started/basics.md b/site/docs/getting-started/basics.md index 3227f733..5de13f07 100644 --- a/site/docs/getting-started/basics.md +++ b/site/docs/getting-started/basics.md @@ -94,7 +94,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.1.0 + container-registry.oracle.com/database/observability-exporter:2.2.0 ``` ## Standalone Binary diff --git a/site/docs/intro.md b/site/docs/intro.md index e6b92f1f..c5754637 100644 --- a/site/docs/intro.md +++ b/site/docs/intro.md @@ -21,7 +21,7 @@ The exporter supports the following main features - Exports Oracle Database metrics in standard OTEL/Prometheus format - Works with on-prem, in the cloud, and in Kubernetes, with single instance, clustered, or Autonomous Oracle Database instances - Authenticate with plaintext, TLS, and Oracle Wallet -- Secure credentials with Oracle Cloud Infrastructure (OCI) Vault or Azure Vault +- Secure credentials with Oracle Cloud Infrastructure (OCI) Vault, Azure Vault, or HashiCorp Vault - Load metrics from one or more databases using a single exporter instance - Export the Prometheus Alert Log in JSON format for easy ingest by log aggregators - Pre-buit AMD64 and ARM64 images provided diff --git a/site/docs/releases/builds.md b/site/docs/releases/builds.md index b56660ff..d7e22cd4 100644 --- a/site/docs/releases/builds.md +++ b/site/docs/releases/builds.md @@ -95,7 +95,7 @@ For example, for the darwin-arm64 platform: ``` dist/ -├── oracledb_exporter-2.1.0.darwin-arm64 +├── oracledb_exporter-2.2.0.darwin-arm64 │ └── oracledb_exporter -└── oracledb_exporter-2.1.0.darwin-arm64.tar.gz +└── oracledb_exporter-2.2.0.darwin-arm64.tar.gz ``` diff --git a/site/docs/releases/changelog.md b/site/docs/releases/changelog.md index 7940f46f..c25dd7c2 100644 --- a/site/docs/releases/changelog.md +++ b/site/docs/releases/changelog.md @@ -9,16 +9,24 @@ List of upcoming and historic changes to the exporter. ### Next, in-development +- TBD + +### Version 2.2.0, October 28, 2025 + Our current priorities to support metrics for advanced database features and use cases, like Exadata, GoldenGate, and views included in the Oracle Diagnostics Pack. +- Allow loading database credentials from [HashiCorp Vault](../configuration/hashicorp-vault.md). - Added experimental support for the [go-ora](https://github.com/sijms/go-ora) - Move `oracledb_dbtype` metric to the default metrics. You may now disable or override this metric like any other database metric. - Document required database permissions for the exporter. - Fix an issue where some metrics would not be cached when using a per-metric scrape interval with a global scrape interval. +- Update third party dependencies +- Update Go runtime to 1.24.9 Thank you to the following people for their suggestions and contributions: - [@MansuyDavid](https://github.com/MansuyDavid) - [@jdagemark](https://github.com/jdagemark) +- [@ilmarkerm](https://github.com/ilmarkerm) ### Version 2.1.0, September 29, 2025 diff --git a/site/docusaurus.config.ts b/site/docusaurus.config.ts index 645195b1..d4972bcd 100644 --- a/site/docusaurus.config.ts +++ b/site/docusaurus.config.ts @@ -72,7 +72,7 @@ const config: Config = { }, { type: 'docsVersionDropdown', - versions: ['current', '2.1.0', '2.0.4', '2.0.3' ] + versions: ['current', '2.2.0', '2.1.0', '2.0.4', '2.0.3' ] }, { href: 'https://github.com/oracle/oracle-db-appdev-monitoring', diff --git a/site/versioned_docs/version-2.2.0/advanced/_category_.json b/site/versioned_docs/version-2.2.0/advanced/_category_.json new file mode 100644 index 00000000..7181f8f0 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/advanced/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Advanced", + "position": 4, + "link": { + "type": "generated-index", + "description": "Advanced configuration." + } +} diff --git a/site/versioned_docs/version-2.2.0/advanced/development.md b/site/versioned_docs/version-2.2.0/advanced/development.md new file mode 100644 index 00000000..a60e6413 --- /dev/null +++ b/site/versioned_docs/version-2.2.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. diff --git a/site/versioned_docs/version-2.2.0/advanced/go-ora.md b/site/versioned_docs/version-2.2.0/advanced/go-ora.md new file mode 100644 index 00000000..c309a929 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/advanced/go-ora.md @@ -0,0 +1,28 @@ +--- +title: go-ora Driver +sidebar_position: 5 +--- + +# Using the go-ora database driver + +The Oracle Database Metrics Exporter experimentally supports compiling with the [go-ora database driver](https://github.com/sijms/go-ora). By default, the exporter compiles using the `godror` database driver, which uses CGO execution to invoke Oracle Instant Client. the go-ora driver presents an option for users who want to use a "thin" database client without the Oracle Instant Client and CGO. + +### Configuring go-ora + +Because go-ora does not use Oracle Instant Client, it is recommended to provide all connection string options in the `database.url` property: + +```yaml +databases: + go_ora_db: + username: myuser + password: ****** + url: my_tnsname?wallet=/path/to/wallet&ssl=1 +``` + +### Build with go-ora + +To build using `go-ora` instead of `godror`, set `TAGS=goora CGO_ENABLED=0`: + +```bash +make go-build TAGS=goora CGO_ENABLED=0 +``` diff --git a/site/versioned_docs/version-2.2.0/advanced/go-runtime.md b/site/versioned_docs/version-2.2.0/advanced/go-runtime.md new file mode 100644 index 00000000..d99075fb --- /dev/null +++ b/site/versioned_docs/version-2.2.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. diff --git a/site/versioned_docs/version-2.2.0/advanced/older-versions.md b/site/versioned_docs/version-2.2.0/advanced/older-versions.md new file mode 100644 index 00000000..a77fbc77 --- /dev/null +++ b/site/versioned_docs/version-2.2.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 = [] +``` diff --git a/site/versioned_docs/version-2.2.0/advanced/txeventq.md b/site/versioned_docs/version-2.2.0/advanced/txeventq.md new file mode 100644 index 00000000..160c0451 --- /dev/null +++ b/site/versioned_docs/version-2.2.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) diff --git a/site/versioned_docs/version-2.2.0/configuration/_category_.json b/site/versioned_docs/version-2.2.0/configuration/_category_.json new file mode 100644 index 00000000..6fa86074 --- /dev/null +++ b/site/versioned_docs/version-2.2.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." + } +} diff --git a/site/versioned_docs/version-2.2.0/configuration/alert-logs.md b/site/versioned_docs/version-2.2.0/configuration/alert-logs.md new file mode 100644 index 00000000..a2eed50b --- /dev/null +++ b/site/versioned_docs/version-2.2.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 +``` diff --git a/site/versioned_docs/version-2.2.0/configuration/azure-vault.md b/site/versioned_docs/version-2.2.0/configuration/azure-vault.md new file mode 100644 index 00000000..bb49ef77 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/configuration/azure-vault.md @@ -0,0 +1,40 @@ +--- +title: Azure Vault +sidebar_position: 7 +--- + +# Azure Vault + +Securely load database credentials from Azure Vault. + +Each database in the config file may be configured to use Azure Vault. To load the database username and/or password from Azure Vault, set the `vault.azure` property to contain the Azure Vault ID, and secret names for the database username/password: + +```yaml +databases: + mydb: + vault: + azure: + id: + usernameSecret: + passwordSecret: +``` + +### Authentication + +If you are running the exporter outside Azure, we recommend using [application service principal](https://learn.microsoft.com/en-us/azure/developer/go/sdk/authentication/authentication-on-premises-apps). + +If you are running the exporter inside Azure, we recommend using a [managed identity](https://learn.microsoft.com/en-us/azure/developer/go/sdk/authentication/authentication-azure-hosted-apps). + +You should set the following additional environment variables to allow the exporter to authenticate to Azure: + +- `AZURE_TENANT_ID` should be set to your tenant ID +- `AZURE_CLIENT_ID` should be set to the client ID to authenticate to Azure +- `AZURE_CLIENT_SECRET` should be set to the client secret to authenticate to Azure + +### Azure Vault CLI Configuration (without exporter config file) + +If using the default database with CLI parameters, the exporter will read the database username and password from secrets stored in Azure Key Vault if you set these environment variables: + +- `AZ_VAULT_ID` should be set to the ID of the Azure Key Vault that you wish to use +- `AZ_VAULT_USERNAME_SECRET` should be set to the name of the secret in the Azure Key Vault which contains the database username +- `AZ_VAULT_PASSWORD_SECRET` should be set to the name of the secret in the Azure Key Vault which contains the database password \ No newline at end of file diff --git a/site/versioned_docs/version-2.2.0/configuration/config-file.md b/site/versioned_docs/version-2.2.0/configuration/config-file.md new file mode 100644 index 00000000..8565c29b --- /dev/null +++ b/site/versioned_docs/version-2.2.0/configuration/config-file.md @@ -0,0 +1,119 @@ +--- +title: Exporter Configuration +sidebar_position: 1 +--- + +# Exporter Configuration + +The recommended way to configure the exporter is with the `--config.file` argument, specifying a YAML configuration file. + +The configuration file contains the following options: + +```yaml +# Example Oracle Database Metrics Exporter Configuration file. +# Environment variables of the form ${VAR_NAME} will be expanded. +# If you include a config value that contains a '$' character, escape that '$' with another '$', e.g., +# "$test$pwd" => "$$test$$pwd" +# Otherwise, the value will be expanded as an environment variable. + +# Example Oracle Database Metrics Exporter Configuration file. +# Environment variables of the form ${VAR_NAME} will be expanded. + +databases: + ## Path on which metrics will be served + # metricsPath: /metrics + ## Database connection information for the "default" database. + default: + ## Database username + username: ${DB_USERNAME} + ## Database password + password: ${DB_PASSWORD} + ## Database password file + ## If specified, will load the database password from a file. + # passwordFile: ${DB_PASSWORD_FILE} + ## Database connection url + url: localhost:1521/freepdb1 + + ## Metrics query timeout for this database, in seconds + queryTimeout: 5 + + ## Rely on Oracle Database External Authentication by network or OS + # externalAuth: false + ## Database role + # role: SYSDBA + ## Path to Oracle Database wallet, if using wallet + # tnsAdmin: /path/to/database/wallet + + ### Connection settings: + ### Either the go-sql or Oracle Database connection pool may be used. + ### To use the Oracle Database connection pool over the go-sql connection pool, + ### set maxIdleConns to zero and configure the pool* settings. + + ### Connection pooling settings for the go-sql connection pool + ## Max open connections for this database using go-sql connection pool + maxOpenConns: 10 + ## Max idle connections for this database using go-sql connection pool + maxIdleConns: 10 + + ### Connection pooling settings for the Oracle Database connection pool + ## Oracle Database connection pool increment. + # poolIncrement: 1 + ## Oracle Database Connection pool maximum size + # poolMaxConnections: 15 + ## Oracle Database Connection pool minimum size + # poolMinConnections: 15 + + ## Arbitrary labels to add to each metric scraped from this database + # labels: + # label_name1: label_value1 + # label_name2: label_value2 + +metrics: + ## How often to scrape metrics. If not provided, metrics will be scraped on request. + # scrapeInterval: 15s + ## Path to default metrics file. + default: default-metrics.toml + ## Paths to any custom metrics files + custom: + - custom-metrics-example/custom-metrics.toml + +log: + # Path of log file + destination: /opt/alert.log + # Interval of log updates + interval: 15s + ## Set disable to 1 to disable logging + # disable: 0 + +# Optionally configure prometheus webserver +#web: +# listenAddresses: [':9161'] +# systemdSocket: true|false +# configFile: /path/to/webconfigfile +``` + +From the exporter configuration file, you may optionally load database credentials from [OCI Vault](./oci-vault.md), [Azure Vault](./azure-vault.md), or [HashiCorp Vault](./hashicorp-vault.md).. + +### Scrape on request vs. Scrape on interval + +The metrics exporter has two scraping modes: scrape on request, and scrape on interval. By default, the metrics exporter scrapes metrics on request, when the `/metrics` endpoint is invoked. + +To scrape metrics on a given interval, set the `metrics.scrapeInterval` property to a valid interval: + +```yaml +metrics: + # Metrics will be scraped every 30s. + scrapeInterval: 30s +``` + +An individual metric may have its own scrape interval separate from the exporter's scrape interval. See the [metric schema](custom-metrics.md#metric-schema) for details on configuring per-metric scrape intervals. + +### Config file in a container image + +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.2.0 +COPY my-exporter-config.yaml / +ENTRYPOINT ["/oracledb_exporter", "--config.file", "/my-exporter-config.yaml"] +``` \ No newline at end of file diff --git a/site/versioned_docs/version-2.2.0/configuration/custom-metrics.md b/site/versioned_docs/version-2.2.0/configuration/custom-metrics.md new file mode 100644 index 00000000..12835e2b --- /dev/null +++ b/site/versioned_docs/version-2.2.0/configuration/custom-metrics.md @@ -0,0 +1,193 @@ +--- +title: Custom Metrics +sidebar_position: 2 +--- + +# Custom Metrics + +The exporter allows definition of arbitrary custom metrics in one or more TOML or YAML files. + +To specify custom metrics files +exporter, use the `metrics` configuration in the [config file](./config-file.md): + +```yaml +metrics: + ## How often to scrape metrics. If not provided, metrics will be scraped on request. + # scrapeInterval: 15s + ## Path to default metrics file. + default: default-metrics.toml + ## Paths to any custom metrics files (TOML or YAML) + custom: + - custom-metrics-example/custom-metrics.toml +``` + +You may also use `--custom.metrics` flag followed by a comma separated list of TOML or YAML files, or export `CUSTOM_METRICS` variable environment (`export CUSTOM_METRICS=my-custom-metrics.toml,my-other-custom-metrics.toml`) + +### Metric Hot Reload + +The exporter watches for changes in custom metrics. When these files change, the exporter hot reloads the metrics definition, and serves the new metrics on the next scrape. + +### Metric Schema + +Metrics files must contain a series of `[[metric]]` definitions, in TOML, or the equivalent definition in a YAML file. Each metric definition must follow the exporter's 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](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/custom-metrics-example/metric-histogram-example.toml)) | Dictionary of String dictionaries | No | | +| fieldtoappend | Field from the request to append to the metric FQN. This field will **not** be included in the metric labels. | 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 duration, e.g., 300ms, 0.5h | String duration | No | Value of query.timeout in seconds | +| scrapeinterval | Custom metric scrape interval. If the metric was already scraped during the specified interval, a cached value is provided. | String duration | No | | +| databases | Array of databases the metric will be scraped from, using the database name from the exporter config file. If not present, the metric is scraped from all databases. If the databases array is empty (`databases = []`) the metric will not be scraped, effectively being disabled. | Array of Strings | No | | + +### Example Metric Definition + +Here's a simple example of a metric definition: + +```toml +[[metric]] +context = "test" +request = "SELECT 1 as value_1, 2 as value_2 FROM DUAL" +metricsdesc = { value_1 = "Simple example returning always 1.", value_2 = "Same but returning always 2." } +``` + +> NOTE: Do not add a semicolon (`;`) at the end of the SQL queries. + +This file produce the following entries in the exporter: + +```text +# HELP oracledb_test_value_1 Simple example returning always 1. +# TYPE oracledb_test_value_1 gauge +oracledb_test_value_1 1 +# HELP oracledb_test_value_2 Same but returning always 2. +# TYPE oracledb_test_value_2 gauge +oracledb_test_value_2 2 +``` + +You can also provide labels using `labels` field. Here's an example providing two metrics, with and without labels: + +```toml +[[metric]] +context = "context_no_label" +request = "SELECT 1 as value_1, 2 as value_2 FROM DUAL" +metricsdesc = { value_1 = "Simple example returning always 1.", value_2 = "Same but returning always 2." } + +[[metric]] +context = "context_with_labels" +labels = [ "label_1", "label_2" ] +request = "SELECT 1 as value_1, 2 as value_2, 'First label' as label_1, 'Second label' as label_2 FROM DUAL" +metricsdesc = { value_1 = "Simple example returning always 1.", value_2 = "Same but returning always 2." } +``` + +This TOML file produces the following result: + +```text +# HELP oracledb_context_no_label_value_1 Simple example returning always 1. +# TYPE oracledb_context_no_label_value_1 gauge +oracledb_context_no_label_value_1 1 +# HELP oracledb_context_no_label_value_2 Same but returning always 2. +# TYPE oracledb_context_no_label_value_2 gauge +oracledb_context_no_label_value_2 2 +# HELP oracledb_context_with_labels_value_1 Simple example returning always 1. +# TYPE oracledb_context_with_labels_value_1 gauge +oracledb_context_with_labels_value_1{label_1="First label",label_2="Second label"} 1 +# HELP oracledb_context_with_labels_value_2 Same but returning always 2. +# TYPE oracledb_context_with_labels_value_2 gauge +oracledb_context_with_labels_value_2{label_1="First label",label_2="Second label"} 2 +``` + +Last, you can set metric type using **metricstype** field. + +```toml +[[metric]] +context = "context_with_labels" +labels = [ "label_1", "label_2" ] +request = "SELECT 1 as value_1, 2 as value_2, 'First label' as label_1, 'Second label' as label_2 FROM DUAL" +metricsdesc = { value_1 = "Simple example returning always 1 as counter.", value_2 = "Same but returning always 2 as gauge." } +# Can be counter or gauge (default) +metricstype = { value_1 = "counter" } +``` + +This TOML file will produce the following result: + +```text +# HELP oracledb_test_value_1 Simple test example returning always 1 as counter. +# TYPE oracledb_test_value_1 counter +oracledb_test_value_1 1 +# HELP oracledb_test_value_2 Same test but returning always 2 as gauge. +# TYPE oracledb_test_value_2 gauge +oracledb_test_value_2 2 +``` + +You can find [working examples](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/custom-metrics-example/custom-metrics.toml) of custom metrics for slow queries, big queries and top 100 tables. +An example of [custom metrics for Transacational Event Queues](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/custom-metrics-example/txeventq-metrics.toml) is also provided. + +#### Override Existing, Individual Metrics + +You may override properties for existing metrics by supplying a new, custom metric definition with the same `context` and `metricsdesc` values. For example, if you have an existing metric like so: + +```toml +[[metric]] +context = "my_default_metric" +metricsdesc = { value_1 = "Simple example returning always 1.", value_2 = "Same but returning always 2." } +request = "SELECT 1 as value_1, 2 as value_2 FROM DUAL" +``` + +You can redefine this metric in a custom metrics file to change any properties other than `context` or `metricsdesc`. For example, overriding the previous metric with `labels`, `scrapeinterval`, and `querytimeout` properties: + +```toml +[[metric]] +context = "my_default_metric" +metricsdesc = { value_1 = "Simple example returning always 1.", value_2 = "Same but returning always 2." } +labels = [ "label_1", "label_2" ] +request = "SELECT 1 as value_1, 2 as value_2 FROM DUAL" +scrapeinterval = "30s" +querytimeout = "10s" +``` + +Then, provide any metrics overrides as custom metrics files in the [exporter configuration file](config-file.md): + +```yaml +metrics: + ## Paths to any custom metrics files + custom: + - my-custom-metrics.toml +``` + +If any metric appears more than once in the custom metrics file list, the metric definition in the last file provided takes precedence. + +### YAML Metrics + +Metrics may be defined with YAML instead of TOML. YAML metric field names correspond to TOML metric field names. + +YAML metrics are defined as a list of `metrics` objects: + + +```yaml +metrics: + - context: "sessions" + labels: [ "inst_id", "status", "type" ] + metricsdesc: + value: "Gauge metric with count of sessions by inst_id, status and type." + request: | + select inst_id, status, type, count(*) as value + from gv$session + group by inst_id, status, type +``` + +The default metrics are provided in YAML format as an example. See [default-metrics.yaml](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/default-metrics.yaml). + +### Customize metrics in a container image + +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.2.0 +COPY custom-metrics.toml / +ENTRYPOINT ["/oracledb_exporter", "--custom.metrics", "/custom-metrics.toml"] +``` \ No newline at end of file diff --git a/site/versioned_docs/version-2.2.0/configuration/hashicorp-vault.md b/site/versioned_docs/version-2.2.0/configuration/hashicorp-vault.md new file mode 100644 index 00000000..3dd38dd3 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/configuration/hashicorp-vault.md @@ -0,0 +1,125 @@ +--- +title: HashiCorp Vault +sidebar_position: 8 +--- + +# HashiCorp Vault + +Securely load database credentials from HashiCorp Vault. + +Each database in the config file may be configured to use HashiCorp Vault. To load the database username and/or password from HashiCorp Vault, set the `vault.hashicorp` property to contain the following information: + +```yaml +databases: + mydb: + vault: + hashicorp: + proxySocket: /var/run/vault/vault.sock + mountType: "kvv1", "kvv2", "database" or "logical" + mountName: secret engine mount path + secretPath: path of the secret or database role name + usernameAttribute: name of the JSON attribute, where to read the database username, if ommitted defaults to "username" + passwordAttribute: name of the JSON attribute, where to read the database password, if ommitted defaults to "password" +``` + +Example + +```yaml +databases: + mydb: + vault: + hashicorp: + proxySocket: /var/run/vault/vault.sock + mountType: kvv2 + mountName: dev + secretPath: oracle/mydb/monitoring +``` + +### Dynamic database credentials + +Instead of fixed database credentials Vault also supports dynamic credentials that are created every time application requests them. This +makes sure the credentials always have a short time-to-live and even if they leak, they quickly become invalid. + +Follow [Vault documentation on how to set up Oracle database plugin for Vault](https://developer.hashicorp.com/vault/docs/secrets/databases/oracle). + +A few additional notes about connecting exporter to CDB. NB! Below are just example commands, adjust them to fit your environment. + +When setting up connection to CDB, then also need to edit "username_template" parameter, so Vault would create a C## common user for exporter. + +```sh +vault write database/config/mydb \ + plugin_name=vault-plugin-database-oracle \ + allowed_roles="mydb_exporter" \ + connection_url='{{username}}/{{password}}@//172.17.0.3:1521/FREE' \ + username_template='{{ printf "C##V_%s_%s_%s_%s" (.DisplayName | truncate 8) (.RoleName | truncate 8) (random 20) (unix_time) | truncate 30 | uppercase | replace "-" "_" | replace "." "_" }}' \ + username='c##vaultadmin' \ + password='vaultadmin' +``` + +Since Vault is creating common users in CDB, it needs to have CREATE/ALTER/DROP USER privileges on all containers. Here is a modification of the documented Vault Oracle plugin admin user privileges. + +```sql +GRANT CREATE USER to c##vaultadmin WITH ADMIN OPTION container=all; +GRANT ALTER USER to c##vaultadmin WITH ADMIN OPTION container=all; +GRANT DROP USER to c##vaultadmin WITH ADMIN OPTION container=all; +GRANT CREATE SESSION to c##vaultadmin WITH ADMIN OPTION; +GRANT SELECT on gv_$session to c##vaultadmin; +GRANT SELECT on v_$sql to c##vaultadmin; +GRANT ALTER SYSTEM to c##vaultadmin WITH ADMIN OPTION; +``` + +Create no authentication user in Oracle database, that has actual monitoring privileges. + +```sql +CREATE USER c##exporter NO AUTHENTICATION; +GRANT create session TO c##exporter; +GRANT all necessary privileges that Exporter needs TO c##exporter; +``` + +Create database role in Vault: + +```sh +vault write database/roles/mydb_exporter \ + db_name=mydb \ + creation_statements='CREATE USER {{username}} IDENTIFIED BY "{{password}}"; GRANT CREATE SESSION TO {{username}}; ALTER USER c##exporter GRANT CONNECT THROUGH {{username}};' \ + default_ttl="7d" \ + max_ttl="10d" +``` + +NB! Make sure to restart Exporter before TTL above expires, this will fetch new database credentials. When TTL expires, Vault will drop the dynamically created database users. + +And create database config in Exporter: + +```yaml +databases: + mydb: + vault: + hashicorp: + proxySocket: /var/run/vault/vault.sock + mountType: database + mountName: database + secretPath: mydb_exporter + useAsProxyFor: c##exporter +``` + +### Authentication + +In this first version it currently only supports queries via HashiCorp Vault Proxy configured to run on the local host and listening on a Unix socket. Currently also required use_auto_auth_token option to be set. +Will expand the support for other methods in the future. + +Example Vault Proxy configuration snippet: + +``` +listener "unix" { + address = "/var/run/vault/vault.sock" + socket_mode = "0660" + socket_user = "vault" + socket_group = "vaultaccess" + tls_disable = true +} + +api_proxy { + # This always uses the auto_auth token when communicating with Vault server, even if client does not send a token + use_auto_auth_token = true +} +``` diff --git a/site/versioned_docs/version-2.2.0/configuration/multiple-databases.md b/site/versioned_docs/version-2.2.0/configuration/multiple-databases.md new file mode 100644 index 00000000..966a5d25 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/configuration/multiple-databases.md @@ -0,0 +1,144 @@ +--- +title: Multiple Databases +sidebar_position: 3 +--- + +# Scraping Multiple Databases + +The exporter may be configured to scrape as many databases as needed. + +You may scrape as many databases as needed by defining named database configurations in the config file. + +If you're connecting to multiple databases using mTLS, see [mTLS for multiple databases with Oracle Wallet](./oracle-wallet.md#mtls-for-multiple-databases-with-oracle-wallet) + +The following settings configure the exporter to scrape multiple databases, "db1", and "db2", simultaneously: + +```yaml +# Example Oracle Database Metrics Exporter Configuration file. +# Environment variables of the form ${VAR_NAME} will be expanded. + +databases: + ## Path on which metrics will be served + # metricsPath: /metrics + + ## As many named database configurations may be defined as needed. + ## It is recommended to define your database config in the config file, rather than using CLI arguments. + + ## Database connection information for the "db1" database. + db1: + ## Database username + username: ${DB1_USERNAME} + ## Database password + password: ${DB1_PASSWORD} + ## Database connection url + url: localhost:1521/freepdb1 + + ## Metrics query timeout for this database, in seconds + queryTimeout: 5 + + ## Rely on Oracle Database External Authentication by network or OS + # externalAuth: false + ## Database role + # role: SYSDBA + ## Path to Oracle Database wallet, if using wallet + # tnsAdmin: /path/to/database/wallet + + ### Connection settings: + ### Either the go-sql or Oracle Database connection pool may be used. + ### To use the Oracle Database connection pool over the go-sql connection pool, + ### set maxIdleConns to zero and configure the pool* settings. + + ### Connection pooling settings for the go-sql connection pool + ## Max open connections for this database using go-sql connection pool + maxOpenConns: 10 + ## Max idle connections for this database using go-sql connection pool + maxIdleConns: 10 + + ### Connection pooling settings for the Oracle Database connection pool + ## Oracle Database connection pool increment. + # poolIncrement: 1 + ## Oracle Database Connection pool maximum size + # poolMaxConnections: 15 + ## Oracle Database Connection pool minimum size + # poolMinConnections: 15 + + ### Arbitrary labels to add to each metric scraped from this database + ## Any labels configured for one database will be added to metrics from + ## every database, because the same metric names must always have the same + ## full labelset. If the label isn't set for a particular database, then it + ## will just be set to an empty string. + # labels: + # label_name1: label_value1 + # label_name2: label_value2 + + db2: + ## Database username + username: ${DB2_USERNAME} + ## Database password + password: ${DB2_PASSWORD} + ## Database connection url + url: localhost:1522/freepdb1 + + ## Metrics query timeout for this database, in seconds + queryTimeout: 5 + + ## Rely on Oracle Database External Authentication by network or OS + # externalAuth: false + ## Database role + # role: SYSDBA + ## Path to Oracle Database wallet, if using wallet + # tnsAdmin: /path/to/database/wallet + + ### Connection settings: + ### Either the go-sql or Oracle Database connection pool may be used. + ### To use the Oracle Database connection pool over the go-sql connection pool, + ### set maxIdleConns to zero and configure the pool* settings. + + ### Connection pooling settings for the go-sql connection pool + ## Max open connections for this database using go-sql connection pool + maxOpenConns: 10 + ## Max idle connections for this database using go-sql connection pool + maxIdleConns: 10 + + ### Connection pooling settings for the Oracle Database connection pool + ## Oracle Database connection pool increment. + # poolIncrement: 1 + ## Oracle Database Connection pool maximum size + # poolMaxConnections: 15 + ## Oracle Database Connection pool minimum size + # poolMinConnections: 15 + + ### Arbitrary labels to add to each metric scraped from this database + ## Any labels configured for one database will be added to metrics from + ## every database, because the same metric names must always have the same + ## full labelset. If the label isn't set for a particular database, then it + ## will just be set to an empty string. + # labels: + # label_name1: label_value1 + # label_name2: label_value2 +``` + +### 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": + +```toml +[[metric]] +context = "db_platform" +labels = [ "platform_name" ] +metricsdesc = { value = "Database platform" } +request = ''' +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. + +### 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 +``` diff --git a/site/versioned_docs/version-2.2.0/configuration/oci-vault.md b/site/versioned_docs/version-2.2.0/configuration/oci-vault.md new file mode 100644 index 00000000..4a1c0628 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/configuration/oci-vault.md @@ -0,0 +1,30 @@ +--- +title: OCI Vault +sidebar_position: 6 +--- + +# Oracle Cloud Infrastructure (OCI) Vault + +Securely load database credentials from OCI Vault. + +Each database in the config file may be configured to use OCI Vault. To load the database username and/or password from OCI Vault, set the `vault.oci` property to contain the OCI Vault OCID, and secret names for the database username/password: + +```yaml +databases: + mydb: + vault: + oci: + id: + usernameSecret: + passwordSecret: +``` + +### OCI Vault CLI Configuration + +If using the default database with CLI parameters, the exporter will read the username and password from a secret stored in OCI Vault if you set these two environment variables: + +- `OCI_VAULT_ID` should be set to the OCID of the OCI vault that you wish to use +- `OCI_VAULT_USERNAME_SECRET` should be set to the name of the secret in the OCI vault which contains the database username +- `OCI_VAULT_PASSWORD_SECRET` should be set to the name of the secret in the OCI vault which contains the database password + +> Note that the process must be running under a user that has the OCI CLI installed and configured correctly to access the desired tenancy and region. The OCI Profile used is `DEFAULT`. diff --git a/site/versioned_docs/version-2.2.0/configuration/oracle-wallet.md b/site/versioned_docs/version-2.2.0/configuration/oracle-wallet.md new file mode 100644 index 00000000..3da1268f --- /dev/null +++ b/site/versioned_docs/version-2.2.0/configuration/oracle-wallet.md @@ -0,0 +1,109 @@ +--- +title: Oracle Wallet (mTLS) +sidebar_position: 4 +--- + +# Using a Wallet + +For mutual TLS (mTLS) connections, you must use an Oracle Wallet. + +If you are using Oracle Autonomous Database with mTLS, for example, you can download and unzip the wallet from the Oracle Cloud Infrastructure (OCI) console. + +To configure the exporter to use an Oracle Wallet, + +1. Set the `TNS_ADMIN` environment variable to the directory containing the unzipped wallet +2. Configure your database instance with the appropriate database TNS name: + +```yaml +databases: + mydb: + username: admin + password: + # TNS Name from wallet tnsnames.ora file, e.g., mydb_high + url: +``` + +If you are running the exporter as a container, you can mount the wallet as a volume. For example, mounting the `./wallet` directory to the `/wallet` location: + +```bash +docker run -it --rm \ + -e DB_USERNAME=pdbadmin \ + -e DB_PASSWORD=Welcome12345 \ + -e DB_CONNECT_STRING=devdb_tp \ + -v ./wallet:/wallet \ + -p 9161:9161 \ + container-registry.oracle.com/database/observability-exporter:2.2.0 +``` + +### mTLS for multiple databases with Oracle Wallet + +The Oracle Database Metrics exporter uses ODPI-C, which can only initalize the TNS aliases from a `tnsnames.ora` file once per process. To work around this, the exporter can be configured to read from a "combined" `tnsnames.ora` file containing all TNS aliases for connections in a multi-database configuration. + +1. For each database the exporter will connect to, download the corresponding wallet files. If you're using ADB/ATP-S, download the regional wallet instead of the instance wallet if the databases are in the same region. + +2. Copy the TNS aliases the `tnsnames.ora` file from each wallet, and combine them into one file, so all your database service names are in one file together + +3. In the combined `tnsnames.ora` file, and add the following snippet to each TNS alias connection string, to tell the client where the wallet directory is: + +``` +(security=(MY_WALLET_DIRECTORY=/path/to/this/database/wallet)) +``` + +The combined `tnsnames.ora` file, which contains the TNS aliases for both databases, and their corresponding wallet location in the `security` configuration will look something like the following: + +```sql +db1_high = (description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1522)(host=adb.****.oraclecloud.com))(connect_data=(service_name=****.adb.oraclecloud.com))(security=(MY_WALLET_DIRECTORY=/wallets/db1)(ssl_server_dn_match=yes))) + +db2_high = (description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1522)(host=adb.****.oraclecloud.com))(connect_data=(service_name=****.adb.oraclecloud.com))(security=(MY_WALLET_DIRECTORY=/wallets/db2)(ssl_server_dn_match=yes))) +``` + +4. Take wallet files (cwallet.sso, ewallet.p12, & ewallet.pem) for each database, and place them in separate directories. For example, `db1` gets its own directory, `db2` gets its own directory, and so forth. + +The resulting directory structure should look like the following, with wallet information separate from the combined `tnsnames.ora` file: + +``` +wallets +├── combined +│ ├── sqlnet.ora +│ └── tnsnames.ora // Combined tnsnames.ora +├── db1 +│ ├── cwallet.sso +│ ├── ewallet.p12 +│ └── ewallet.pem +└── db2 +├── cwallet.sso +├── ewallet.p12 +└── ewallet.pem +``` + +5. Set the `TNS_ADMIN` environment variable where the exporter is running to the directory containing your combined `tnsnames.ora` file: + +``` +export TNS_ADMIN=/wallets/combined +``` + +6. Finally, update the exporter configuration file to include the TNS aliases for all databases you will be connecting to. Ensure your database configuration file does not use the `tnsAdmin` property, as we are using the global `TNS_ADMIN` environment variable to point to the combined `tnsnames.ora` file: + +```yaml +databases: + db2: + username: **** + password: **** + url: db2_high + queryTimeout: 5 + maxOpenConns: 10 + maxIdleConns: 10 + db1: + username: **** + password: **** + url: db1_high + queryTimeout: 5 + maxOpenConns: 10 + maxIdleConns: 10 +``` + +Then, run the exporter with the config file: + +```shell +./oracledb_exporter --config.file=my-config-file.yaml +``` \ No newline at end of file diff --git a/site/versioned_docs/version-2.2.0/getting-started/_category_.json b/site/versioned_docs/version-2.2.0/getting-started/_category_.json new file mode 100644 index 00000000..a5d3001d --- /dev/null +++ b/site/versioned_docs/version-2.2.0/getting-started/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Getting Started", + "position": 2, + "link": { + "type": "generated-index", + "description": "Learn the most important Oracle Database Metrics Exporter concepts." + } +} diff --git a/site/versioned_docs/version-2.2.0/getting-started/basics.md b/site/versioned_docs/version-2.2.0/getting-started/basics.md new file mode 100644 index 00000000..5de13f07 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/getting-started/basics.md @@ -0,0 +1,253 @@ +--- +title: Installation +sidebar_position: 1 +--- + +# Installation + +In this section you will find information on running the exporter. + +- In a container runtime like [Docker, Podman, etc](#docker-podman-etc) +- In a test/demo environment using [Docker Compose](#docker-compose) +- In [Kubernetes](./kubernetes.md) +- As a [standalone binary](#standalone-binary) + +## Database Permissions + +For the built-in default metrics, the exporter database database user must have the `SELECT_CATALOG_ROLE` privilege and/or `SELECT` permission on the following objects: + +``` +dba_tablespace_usage_metrics +dba_tablespaces +gv$system_wait_class +gv$asm_diskgroup_stat +gv$datafile +gv$sysstat +gv$process +gv$waitclassmetric +gv$session +gv$resource_limit +gv$parameter +gv$database +gv$sqlstats +gv$sysmetric +v$diag_alert_ext (for alert logs only) +``` + +## Docker, Podman, etc + +You can run the exporter in a local container using a container image from [Oracle Container Registry](https://container-registry.oracle.com). The container image is available in the "observability-exporter" repository in the "Database" category. No authentication or license presentment/acceptance are required to pull this image from the registry. + +### Oracle Database Free + +If you need an Oracle Database to test the exporter, you can use this command to start up an instance of [Oracle Database Free](https://www.oracle.com/database/free/) which also requires no authentication or license presentment/acceptance to pull the image. + +```bash +docker run --name free23ai \ + -d \ + -p 1521:1521 \ + -e ORACLE_PASSWORD=Welcome12345 \ + gvenzl/oracle-free:23.9-slim-faststart +``` + +This will pull the image and start up the database with a listener on port 1521. It will also create a pluggable database (a database container) called "FREEPDB1" and will set the admin passwords to the password you specified on this command. + +You can tail the logs to see when the database is ready to use: + +```bash +docker logs -f free23ai + +(look for this message...) +######################### +DATABASE IS READY TO USE! +######################### +``` + +To obtain the IP address of the container, which you will need to connect to the database, use this command. Note: depending on your platform and container runtime, you may be able to access the database at "localhost": + +```bash +docker inspect free23ai | grep IPA + "SecondaryIPAddresses": null, + "IPAddress": "172.17.0.2", + "IPAMConfig": null, + "IPAddress": "172.17.0.2", +``` + +### Exporter + +You need to give the exporter the connection details for the Oracle Database that you want it to run against. You can use a simple connection, or a wallet. + +### Simple connection + +For a simple connection, you will provide the details using these variables: + +- `DB_USERNAME` is the database username, e.g., `pdbadmin` +- `DB_PASSWORD` is the password for that user, e.g., `Welcome12345` +- `DB_CONNECT_STRING` is the connection string, e.g., `free23ai:1521/freepdb` +- `DB_ROLE` (Optional) can be set to `SYSDBA`, `SYSOPER`, `SYSBACKUP`, `SYSDG`, `SYSKM`, `SYSRAC` or `SYSASM` if you want to connect with one of those roles, however Oracle recommends that you connect with the lowest possible privileges and roles necessary for the exporter to run. + +To run the exporter in a container and expose the port, use a command like this, with the appropriate values for the environment variables: + +```bash +docker run -it --rm \ + -e DB_USERNAME=pdbadmin \ + -e DB_PASSWORD=Welcome12345 \ + -e DB_CONNECT_STRING=free23ai:1521/freepdb \ + -p 9161:9161 \ + container-registry.oracle.com/database/observability-exporter:2.2.0 +``` + +## Standalone Binary + +Pre-compiled versions for Linux, ARM and Darwin 64-bit can be found under [releases](https://github.com/oracle/oracle-db-appdev-monitoring/releases). + +In order to run, you'll need the [Oracle Instant Client Basic](http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html) for your operating system. Only the basic version is required for the exporter. + +> NOTE: If you are running the Standalone binary on a Mac ARM platform you must set the variable `DYLD_LIBRARY_PATH` to the location of where the instant client installed. For example `export DYLD_LIBRARY_PATH=/lib/oracle/instantclient_23_3`. + +The following command line arguments (flags) can be passed to the exporter (the --help flag will show the table below). + +```bash +Usage of oracledb_exporter: + --config.file="example-config.yaml" + File with metrics exporter configuration. (env: CONFIG_FILE) + --web.telemetry-path="/metrics" + Path under which to expose metrics. (env: TELEMETRY_PATH) + --default.metrics="default-metrics.toml" + File with default metrics in a TOML file. (env: DEFAULT_METRICS) + --custom.metrics="" Comma separated list of file(s) that contain various custom metrics in a TOML format. (env: CUSTOM_METRICS) + --query.timeout=5 Query timeout (in seconds). (env: QUERY_TIMEOUT) + --database.maxIdleConns=0 Number of maximum idle connections in the connection pool. (env: DATABASE_MAXIDLECONNS) + --database.maxOpenConns=10 + Number of maximum open connections in the connection pool. (env: DATABASE_MAXOPENCONNS) + --database.poolIncrement=-1 + Connection increment when the connection pool reaches max capacity. (env: DATABASE_POOLINCREMENT) + --database.poolMaxConnections=-1 + Maximum number of connections in the connection pool. (env: DATABASE_POOLMAXCONNECTIONS) + --database.poolMinConnections=-1 + Minimum number of connections in the connection pool. (env: DATABASE_POOLMINCONNECTIONS) + --scrape.interval=0s Interval between each scrape. Default is to scrape on collect requests. + --log.disable=0 Set to 1 to disable alert logs + --log.interval=15s Interval between log updates (e.g. 5s). + --log.destination="/log/alert.log" + File to output the alert log to. (env: LOG_DESTINATION) + --web.listen-address=:9161 ... + Addresses on which to expose metrics and web interface. Repeatable for multiple addresses. Examples: `:9100` or `[::1]:9100` for http, `vsock://:9100` for vsock + --web.config.file="" Path to configuration file that can enable TLS or authentication. See: https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md + --log.level=info Only log messages with the given severity or above. One of: [debug, info, warn, error] + --log.format=logfmt Output format of log messages. One of: [logfmt, json] + --[no-]version Show application version. +``` + +You may provide the connection details using these variables: + +- `DB_USERNAME` is the database username, e.g., `pdbadmin` +- `DB_PASSWORD` is the password for that user, e.g., `Welcome12345` +- `DB_CONNECT_STRING` is the connection string, e.g., `localhost:1521/freepdb1` +- `DB_ROLE` (Optional) can be set to `SYSDBA` or `SYSOPER` if you want to connect with one of those roles, however Oracle recommends that you connect with the lowest possible privileges and roles necessary for the exporter to run. +- `ORACLE_HOME` is the location of the Oracle Instant Client, e.g., `/lib/oracle/21/client64/lib`. +- `TNS_ADMIN` is the location of your (unzipped) wallet. The `DIRECTORY` set in the `sqlnet.ora` file must match the path that it will be mounted on inside the container. + +The following example puts the logfile in the current location with the filename `alert.log` and loads the default matrics file (`default-metrics,toml`) from the current location. + +If you prefer to provide configuration via a [config file](../configuration/config-file.md), you may do so with the `--config.file` argument. The use of a config file over command line arguments is preferred. If a config file is not provided, the "default" database connection is managed by command line arguments. + +```yaml +# Example Oracle Database Metrics Exporter Configuration file. +# Environment variables of the form ${VAR_NAME} will be expanded. +# If you include a config value that contains a '$' character, escape that '$' with another '$', e.g., +# "$test$pwd" => "$$test$$pwd" +# Otherwise, the value will be expanded as an environment variable. + +# Example Oracle Database Metrics Exporter Configuration file. +# Environment variables of the form ${VAR_NAME} will be expanded. + +databases: + ## Path on which metrics will be served + # metricsPath: /metrics + ## Database connection information for the "default" database. + default: + ## Database username + username: ${DB_USERNAME} + ## Database password + password: ${DB_PASSWORD} + ## Database password file + ## If specified, will load the database password from a file. + # passwordFile: ${DB_PASSWORD_FILE} + ## Database connection url + url: localhost:1521/freepdb1 + + ## Metrics query timeout for this database, in seconds + queryTimeout: 5 + + ## Rely on Oracle Database External Authentication by network or OS + # externalAuth: false + ## Database role + # role: SYSDBA + ## Path to Oracle Database wallet, if using wallet + # tnsAdmin: /path/to/database/wallet + + ### Connection settings: + ### Either the go-sql or Oracle Database connection pool may be used. + ### To use the Oracle Database connection pool over the go-sql connection pool, + ### set maxIdleConns to zero and configure the pool* settings. + + ### Connection pooling settings for the go-sql connection pool + ## Max open connections for this database using go-sql connection pool + maxOpenConns: 10 + ## Max idle connections for this database using go-sql connection pool + maxIdleConns: 10 + + ### Connection pooling settings for the Oracle Database connection pool + ## Oracle Database connection pool increment. + # poolIncrement: 1 + ## Oracle Database Connection pool maximum size + # poolMaxConnections: 15 + ## Oracle Database Connection pool minimum size + # poolMinConnections: 15 + + ## Arbitrary labels to add to each metric scraped from this database + # labels: + # label_name1: label_value1 + # label_name2: label_value2 + +metrics: + ## How often to scrape metrics. If not provided, metrics will be scraped on request. + # scrapeInterval: 15s + ## Path to default metrics file. + default: default-metrics.toml + ## Paths to any custom metrics files + custom: + - custom-metrics-example/custom-metrics.toml + +log: + # Path of log file + destination: /opt/alert.log + # Interval of log updates + interval: 15s + ## Set disable to 1 to disable logging + # disable: 0 + +# Optionally configure prometheus webserver +#web: +# listenAddresses: [':9161'] +# systemdSocket: true|false +# configFile: /path/to/webconfigfile +``` + +### Docker Compose + +If you would like to set up a test environment with the exporter, you can use the provided "Docker Compose" file in this repository which will start an Oracle Database instance, the exporter, Prometheus and Grafana. + +```bash +cd docker-compose +docker-compose up -d +``` + +The containers will take a short time to start. The first time, the Oracle container might take a few minutes to start while it creates the database instance, but this is a one-time operation, and subequent restarts will be much faster (a few seconds). + +Once the containers are all running, you can access the services using these URLs: + +- [Exporter](http://localhost:9161/metrics) +- [Prometheus](http://localhost:9090) - try a query for "oracle". +- [Grafana](http://localhost:3000) - username is "admin" and password is "grafana". An Oracle Database dashboard is provisioned and configured to use data from the exporter. \ No newline at end of file diff --git a/site/versioned_docs/version-2.2.0/getting-started/default-metrics.md b/site/versioned_docs/version-2.2.0/getting-started/default-metrics.md new file mode 100644 index 00000000..084960a0 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/getting-started/default-metrics.md @@ -0,0 +1,136 @@ +--- +title: Default Metrics +sidebar_position: 2 +--- + +# Default Metrics + +The exporter includes [default metrics](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/collector/default_metrics.toml) for Oracle Database, and process-specific metrics on the `go` runtime. + +You can find the exporter's metric schema in the [Custom Metrics configuration](../configuration/custom-metrics.md#metric-schema). + +The following metrics are included by default. The values given are a sample for a single database, "db1": + +```bash +# HELP oracledb_activity_execute_count Generic counter metric from gv$sysstat view in Oracle. +# TYPE oracledb_activity_execute_count gauge +oracledb_activity_execute_count{database="db1"} 6.212049e+06 +# HELP oracledb_activity_parse_count_total Generic counter metric from gv$sysstat view in Oracle. +# TYPE oracledb_activity_parse_count_total gauge +oracledb_activity_parse_count_total{database="db1"} 1.054178e+06 +# HELP oracledb_activity_user_commits Generic counter metric from gv$sysstat view in Oracle. +# TYPE oracledb_activity_user_commits gauge +oracledb_activity_user_commits{database="db1"} 86538 +# HELP oracledb_activity_user_rollbacks Generic counter metric from gv$sysstat view in Oracle. +# TYPE oracledb_activity_user_rollbacks gauge +oracledb_activity_user_rollbacks{database="db1"} 18 +# HELP oracledb_db_platform_value Database platform +# TYPE oracledb_db_platform_value gauge +oracledb_db_platform_value{database="db1",platform_name="Linux OS (AARCH64)"} 1 +# HELP oracledb_db_system_value Database system resources metric +# TYPE oracledb_db_system_value gauge +oracledb_db_system_value{database="db1",name="cpu_count"} 2 +oracledb_db_system_value{database="db1",name="pga_aggregate_limit"} 2.147483648e+09 +oracledb_db_system_value{database="db1",name="sga_max_size"} 1.610612736e+09 +# HELP oracledb_dbtype Type of database the exporter is connected to (0=non-CDB, 1=CDB, >1=PDB). +# TYPE oracledb_dbtype gauge +oracledb_dbtype{database="db1"} 3 +# HELP oracledb_exporter_build_info A metric with a constant '1' value labeled by version, revision, branch, goversion from which oracledb_exporter was built, and the goos and goarch for the build. +# TYPE oracledb_exporter_build_info gauge +oracledb_exporter_build_info{branch="",goarch="arm64",goos="darwin",goversion="go1.24.5",revision="unknown",tags="unknown",version=""} 1 +# HELP oracledb_exporter_last_scrape_duration_seconds Duration of the last scrape of metrics from Oracle DB. +# TYPE oracledb_exporter_last_scrape_duration_seconds gauge +oracledb_exporter_last_scrape_duration_seconds 0.05714725 +# HELP oracledb_exporter_last_scrape_error Whether the last scrape of metrics from Oracle DB resulted in an error (1 for error, 0 for success). +# TYPE oracledb_exporter_last_scrape_error gauge +oracledb_exporter_last_scrape_error 0 +# HELP oracledb_exporter_scrapes_total Total number of times Oracle DB was scraped for metrics. +# TYPE oracledb_exporter_scrapes_total counter +oracledb_exporter_scrapes_total 2 +# HELP oracledb_process_count Gauge metric with count of processes. +# TYPE oracledb_process_count gauge +oracledb_process_count{database="db1"} 85 +# HELP oracledb_sessions_value Gauge metric with count of sessions by status and type. +# TYPE oracledb_sessions_value gauge +oracledb_sessions_value{database="db1",status="ACTIVE",type="BACKGROUND"} 61 +oracledb_sessions_value{database="db1",status="ACTIVE",type="USER"} 2 +oracledb_sessions_value{database="db1",status="INACTIVE",type="USER"} 19 +# HELP oracledb_tablespace_bytes Generic counter metric of tablespaces bytes in Oracle. +# TYPE oracledb_tablespace_bytes gauge +oracledb_tablespace_bytes{database="db1",tablespace="SYSAUX",type="PERMANENT"} 7.7430784e+08 +oracledb_tablespace_bytes{database="db1",tablespace="SYSTEM",type="PERMANENT"} 3.18963712e+08 +oracledb_tablespace_bytes{database="db1",tablespace="TEMP",type="TEMPORARY"} 7.340032e+06 +oracledb_tablespace_bytes{database="db1",tablespace="UNDOTBS1",type="UNDO"} 2.1364736e+07 +oracledb_tablespace_bytes{database="db1",tablespace="USERS",type="PERMANENT"} 7.340032e+06 +# HELP oracledb_tablespace_free Generic counter metric of tablespaces free bytes in Oracle. +# TYPE oracledb_tablespace_free gauge +oracledb_tablespace_free{database="db1",tablespace="SYSAUX",type="PERMANENT"} 7.5289739264e+10 +oracledb_tablespace_free{database="db1",tablespace="SYSTEM",type="PERMANENT"} 7.524491264e+10 +oracledb_tablespace_free{database="db1",tablespace="TEMP",type="TEMPORARY"} 1.3631488e+07 +oracledb_tablespace_free{database="db1",tablespace="UNDOTBS1",type="UNDO"} 3.518435069952e+13 +oracledb_tablespace_free{database="db1",tablespace="USERS",type="PERMANENT"} 3.4352381952e+10 +# HELP oracledb_tablespace_max_bytes Generic counter metric of tablespaces max bytes in Oracle. +# TYPE oracledb_tablespace_max_bytes gauge +oracledb_tablespace_max_bytes{database="db1",tablespace="SYSAUX",type="PERMANENT"} 7.6064047104e+10 +oracledb_tablespace_max_bytes{database="db1",tablespace="SYSTEM",type="PERMANENT"} 7.5563876352e+10 +oracledb_tablespace_max_bytes{database="db1",tablespace="TEMP",type="TEMPORARY"} 2.097152e+07 +oracledb_tablespace_max_bytes{database="db1",tablespace="UNDOTBS1",type="UNDO"} 3.5184372064256e+13 +oracledb_tablespace_max_bytes{database="db1",tablespace="USERS",type="PERMANENT"} 3.4359721984e+10 +# HELP oracledb_tablespace_used_percent Gauge metric showing as a percentage of how much of the tablespace has been used. +# TYPE oracledb_tablespace_used_percent gauge +oracledb_tablespace_used_percent{database="db1",tablespace="SYSAUX",type="PERMANENT"} 1.0179682379262742 +oracledb_tablespace_used_percent{database="db1",tablespace="SYSTEM",type="PERMANENT"} 0.4221113677574824 +oracledb_tablespace_used_percent{database="db1",tablespace="TEMP",type="TEMPORARY"} 0.35 +oracledb_tablespace_used_percent{database="db1",tablespace="UNDOTBS1",type="UNDO"} 6.072223190734319e-05 +oracledb_tablespace_used_percent{database="db1",tablespace="USERS",type="PERMANENT"} 0.021362314873845517 +# HELP oracledb_top_sql_elapsed SQL statement elapsed time running +# TYPE oracledb_top_sql_elapsed gauge +oracledb_top_sql_elapsed{database="db1",sql_id="0npm6czzaj44m",sql_text="SELECT idx_objn FROM vecsys.vector$index WHERE JSON_VAL"} 6.118614 +oracledb_top_sql_elapsed{database="db1",sql_id="0sbbcuruzd66f",sql_text="select /*+ rule */ bucket_cnt, row_cnt, cache_cnt, null"} 1.538687 +oracledb_top_sql_elapsed{database="db1",sql_id="121ffmrc95v7g",sql_text="select i.obj#,i.ts#,i.file#,i.block#,i.intcols,i.type#,"} 2.200984 +oracledb_top_sql_elapsed{database="db1",sql_id="61znfd8fvgha6",sql_text="SELECT new.sql_seq, old.plan_hash_value, sqlset_row(ne"} 2.628263 +oracledb_top_sql_elapsed{database="db1",sql_id="68dw2nt8wtunk",sql_text="select originating_timestamp, module_id, execution_cont"} 2.296924 +oracledb_top_sql_elapsed{database="db1",sql_id="9bd61v53p81sk",sql_text="begin prvt_hdm.auto_execute( :dbid , :inst_num , :end_s"} 1.67611 +oracledb_top_sql_elapsed{database="db1",sql_id="aba13jkkk3fts",sql_text="SELECT idx_objn, json_value(IDX_SPARE2, '$.counter') FR"} 3.010397 +oracledb_top_sql_elapsed{database="db1",sql_id="afcz0dh295hzp",sql_text=" SELECT /*+ first_rows(1) */ sql_id, force_matching_sig"} 2.246092 +oracledb_top_sql_elapsed{database="db1",sql_id="ampw9ddqufjd3",sql_text="begin /*KAPI:capture*/ dbms_auto_index_internal.capture"} 4.102646 +oracledb_top_sql_elapsed{database="db1",sql_id="avzy19hxu6gg4",sql_text="SELECT VALUE(P) FROM TABLE(DBMS_SQLTUNE.SELECT_CURSOR_C"} 2.564301 +oracledb_top_sql_elapsed{database="db1",sql_id="b39m8n96gxk7c",sql_text="call dbms_autotask_prvt.run_autotask ( :0,:1 )"} 4.418653 +oracledb_top_sql_elapsed{database="db1",sql_id="bj9ajtpfh9f41",sql_text=" declare purge_scn "} 6.425015 +oracledb_top_sql_elapsed{database="db1",sql_id="bq819r502v7u2",sql_text="select originating_timestamp, module_id, execution_cont"} 3.676572 +oracledb_top_sql_elapsed{database="db1",sql_id="ddrfu7d7hbkym",sql_text=" select count(1), partition_id "} 1.870379 +oracledb_top_sql_elapsed{database="db1",sql_id="f6w8rqdkx0bnv",sql_text="SELECT * FROM ( SELECT /*+ ordered use_nl(o c cu h) ind"} 1.895947 +# HELP oracledb_up Whether the Oracle database server is up. +# TYPE oracledb_up gauge +oracledb_up{database="db1"} 1 +# HELP oracledb_wait_time_administrative counter metric from system_wait_class view in Oracle. +# TYPE oracledb_wait_time_administrative counter +oracledb_wait_time_administrative{database="db1"} 0 +# HELP oracledb_wait_time_application counter metric from system_wait_class view in Oracle. +# TYPE oracledb_wait_time_application counter +oracledb_wait_time_application{database="db1"} 0.73 +# HELP oracledb_wait_time_commit counter metric from system_wait_class view in Oracle. +# TYPE oracledb_wait_time_commit counter +oracledb_wait_time_commit{database="db1"} 0.17 +# HELP oracledb_wait_time_concurrency counter metric from system_wait_class view in Oracle. +# TYPE oracledb_wait_time_concurrency counter +oracledb_wait_time_concurrency{database="db1"} 6.8 +# HELP oracledb_wait_time_configuration counter metric from system_wait_class view in Oracle. +# TYPE oracledb_wait_time_configuration counter +oracledb_wait_time_configuration{database="db1"} 19.71 +# HELP oracledb_wait_time_network counter metric from system_wait_class view in Oracle. +# TYPE oracledb_wait_time_network counter +oracledb_wait_time_network{database="db1"} 0.29 +# HELP oracledb_wait_time_other counter metric from system_wait_class view in Oracle. +# TYPE oracledb_wait_time_other counter +oracledb_wait_time_other{database="db1"} 6.02 +# HELP oracledb_wait_time_scheduler counter metric from system_wait_class view in Oracle. +# TYPE oracledb_wait_time_scheduler counter +oracledb_wait_time_scheduler{database="db1"} 4.01 +# HELP oracledb_wait_time_system_io counter metric from system_wait_class view in Oracle. +# TYPE oracledb_wait_time_system_io counter +oracledb_wait_time_system_io{database="db1"} 0.13 +# HELP oracledb_wait_time_user_io counter metric from system_wait_class view in Oracle. +# TYPE oracledb_wait_time_user_io counter +oracledb_wait_time_user_io{database="db1"} 12.38 +``` \ No newline at end of file diff --git a/site/versioned_docs/version-2.2.0/getting-started/grafana-dashboards.md b/site/versioned_docs/version-2.2.0/getting-started/grafana-dashboards.md new file mode 100644 index 00000000..30aeed2c --- /dev/null +++ b/site/versioned_docs/version-2.2.0/getting-started/grafana-dashboards.md @@ -0,0 +1,14 @@ +--- +title: Grafana Dashboards +sidebar_position: 4 +--- + +# Grafana Dashboards + +Sample Grafana dashboards are included with the exporter. + +A sample Grafana dashboard definition is provided [in this directory](https://github.com/oracle/oracle-db-appdev-monitoring/tree/main/docker-compose/grafana/dashboards). You can import these dashboards into your Grafana instance, and set it to use the Prometheus datasource that you have defined for the Prometheus instance that is collecting metrics from the exporter. + +The dashboard shows some basic information, as shown below: + +![Oracle Database Dashboard](/img/oracledb-dashboard.png) diff --git a/site/versioned_docs/version-2.2.0/getting-started/kubernetes.md b/site/versioned_docs/version-2.2.0/getting-started/kubernetes.md new file mode 100644 index 00000000..8023da40 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/getting-started/kubernetes.md @@ -0,0 +1,116 @@ +--- +title: Kubernetes +sidebar_position: 3 +--- + +# Kubernetes + +You can run the exporter in Kubernetes using provided manifests. + +To run the exporter in Kubernetes, you must complete the following steps. All steps must be completed in the same Kunernetes namespace. The examples below assume you want to use a namespace called `exporter`, you must change the commands if you wish to use a different namespace. + +### Create a secret with credentials for connecting to the Oracle Database + +Create a secret with the Oracle database user and password that the exporter should use to connect to the database using this command. You must specify the correct user and password for your environment. This example uses `pdbadmin` as the user and `Welcome12345` as the password: + +```bash +kubectl create secret generic db-secret \ + --from-literal=username=pdbadmin \ + --from-literal=password=Welcome12345 \ + -n exporter +``` + +### Create a config map for the exporter configuration file (recommended) + +Create a config map with the exporter configuration file (if you are using one) using this command: + +```bash +kubectl create cm metrics-exporter-config \ + --from-file=metrics-exporter-config.yaml +``` + +> NOTE: It is strongly recommended to migrate to the new config file if you are running version 2.0.0 or later. + + +### Create a config map for the wallet (optional) + +Create a config map with the wallet (if you are using one) using this command. Run this command in the `wallet` directory you created earlier. + +```bash +kubectl create cm db-metrics-tns-admin \ + --from-file=cwallet.sso \ + --from-file=ewallet.p12 \ + --from-file=ewallet.pem \ + --from-file=keystore.jks \ + --from-file=ojdbc.properties \ + --from-file=sqlnet.ora \ + --from-file=tnsnames.ora \ + --from-file=truststore.jks \ + -n exporter +``` + +### Create a config map for your metrics definition file (optional) + +If you have defined any [custom metrics](../configuration/custom-metrics.md), you must create a config map for the metrics definition file. For example, if you created a configuration file called `txeventq-metrics.toml`, then create the config map with this command: + +```bash +kubectl create cm db-metrics-txeventq-exporter-config \ + --from-file=txeventq-metrics.toml \ + -n exporter +``` + +### Deploy the Oracle Database Observability exporter + +A sample Kubernetes manifest is provided [here](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/kubernetes/metrics-exporter-deployment.yaml). You must edit this file to set the namespace you wish to use, the database connect string to use, and if you have any custom metrics, you will need to uncomment and customize some sections in this file. + +Once you have made the necessary updates, apply the file to your cluster using this command: + +```bash +kubectl apply -f metrics-exporter-deployment.yaml +``` + +You can check the deployment was successful and monitor the exporter startup with this command: + +```bash +kubectl get pods -n exporter -w +``` + +You can view the exporter's logs with this command: + +```bash +kubectl logs -f svc/metrics-exporter -n exporter +``` + +### Create a Kubernetes service for the exporter + +Create a Kubernetes service to allow access to the exporter pod(s). A sample Kubernetes manifest is provided [here](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/kubernetes/metrics-exporter-service.yaml). You may need to customize this file to update the namespace. + +Once you have made any necessary udpates, apply the file to your cluster using this command: + +```bash +kubectl apply -f metrics-exporter-service.yaml +``` + +### Create a Kubernetes service monitor + +Create a Kubernetes service monitor to tell Prometheus (for example) to collect metrics from the exporter. A sample Kubernetes manifest is provided [here](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/kubernetes/metrics-service-monitor.yaml). You may need to customize this file to update the namespace. + +Once you have made any necessary udpates, apply the file to your cluster using this command: + +```bash +kubectl apply -f metrics-service-monitor.yaml +``` + +### Configure a Prometheus target (optional) + +You may need to update your Prometheus configuration to add a target. If so, you can use this example job definition as a guide: + +```yaml + - job_name: 'oracle-exporter' + metrics_path: '/metrics' + scrape_interval: 15s + scrape_timeout: 10s + static_configs: + - targets: + - metrics-exporter.exporter.svc.cluster.local:9161 +``` diff --git a/site/versioned_docs/version-2.2.0/intro.md b/site/versioned_docs/version-2.2.0/intro.md new file mode 100644 index 00000000..c5754637 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/intro.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 1 +--- + +# OpenTelemetry Metrics for Oracle Database + +The Oracle Database Metrics Exporter provides OpenTelemetry-compatible metrics so you can monitor the health, performance, and availability of your databaeses from anywhere. + +The metrics supports monitoring multiple database instances, querying default and custom metrics, and ensures that if one database goes offline for maintenance, the rest stay monitored. + +Over time, this project will provide not just metrics, but also logging and tracing support, and integration into popular frameworks like Spring Boot. The project aims to deliver functionality to support both cloud and on-premises databases, including those running in Kubernetes and containers. + +Contributions are welcome - please see [contributing](https://github.com/oracle/oracle-db-appdev-monitoring/blob/main/CONTRIBUTING.md). + +![Oracle Database Dashboard](/img/exporter-running-against-basedb.png) + +## Main Features + +The exporter supports the following main features + +- Exports Oracle Database metrics in standard OTEL/Prometheus format +- Works with on-prem, in the cloud, and in Kubernetes, with single instance, clustered, or Autonomous Oracle Database instances +- Authenticate with plaintext, TLS, and Oracle Wallet +- Secure credentials with Oracle Cloud Infrastructure (OCI) Vault, Azure Vault, or HashiCorp Vault +- Load metrics from one or more databases using a single exporter instance +- Export the Prometheus Alert Log in JSON format for easy ingest by log aggregators +- Pre-buit AMD64 and ARM64 images provided +- Standard, default metrics included "out of the box" +- Easily define custom metrics using YAML or TOML +- Define the scrape interval, database query timeout, and other parameters on a per-metric, per-database level +- Customize the database connection pool using go-sql, Oracle Database connection pools, and works with Database Resident Connection Pools +- Includes a sample [Grafana dashboards](https://github.com/oracle/oracle-db-appdev-monitoring/tree/main/docker-compose/grafana) for inspiration or customization + +## Supported Oracle Database Versions + +The Oracle Database Metrics Exporter natively supports Oracle Database versions 19c and 23ai. + +## Acknowledgements + +From the v1.0 release onwards, this project provides a [Prometheus](https://prometheus.io/) exporter for Oracle Database based in part on a Prometheus exporter created by [Seth Miller](https://github.com/iamseth/oracledb_exporter). This project includes changes to comply with various Oracle standards and policies, as well as new features. + +> Seth has archived his exporter as of Feb 13, 2025 and added a note encouraging people to check out ours instead. We wanted to extend a huge "Thank You!" to Seth for the work he did on that exporter, and his contributions to the Oracle and open source communities! + diff --git a/site/versioned_docs/version-2.2.0/releases/_category_.json b/site/versioned_docs/version-2.2.0/releases/_category_.json new file mode 100644 index 00000000..ec3de8d2 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/releases/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Releases", + "position": 5, + "link": { + "type": "generated-index", + "description": "Information on the exporter releases, changelog, and roadmap." + } +} diff --git a/site/versioned_docs/version-2.2.0/releases/builds.md b/site/versioned_docs/version-2.2.0/releases/builds.md new file mode 100644 index 00000000..d7e22cd4 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/releases/builds.md @@ -0,0 +1,101 @@ +--- +title: Builds +sidebar_position: 3 +--- + +The Oracle Database Metrics Exporter publishes cross-platform builds for each release. + +Binaries: +- linux/amd64 +- linux/arm64 +- darwin/arm64 + +Container images: +- linux/amd64 +- linux/arm64 + +### Pre-built binaries + +Download pre-built binaries from the metrics exporter [GitHub Releases page](https://github.com/oracle/oracle-db-appdev-monitoring/releases). + +`linux-amd64`, `linux-arm64`, and `darwin-arm64` binaries are included, built using GLIBC 2.39. If you require a specific target architecture or are using an older verison of GLIBC, it's recommended to build the metrics exporter binary yourself. + +### Container images + +```bash +docker pull container-registry.oracle.com/database/observability-exporter:${VERSION} +``` + +### Build the Oracle Database Metrics Exporter + +Follow these steps to build the metrics exporter on a Ubuntu Linux system. + +#### Install build tools. + +Note that `podman` and `qemu-user-static` are only required for container builds. + +```bash +sudo apt-get -y install podman qemu-user-static golang gcc-aarch64-linux-gnu +``` + +#### How to build metrics exporter binaries + +Linux amd64: + +```bash +make go-build-linux-amd64 +``` + +Linux arm64 (requires `gcc-aarch64-linux-gnu`): + +``bash +make go-build-linux-gcc-arm64 +`` + +Darwin arm64 (requires MacOS platform compilers): + +```bash +make go-build-darwin-arm64 +``` + +#### How to build metrics exporter container images + +Creates multi-arch container builds for linux/amd64 and linux/arm64: + +``` +make podman-build +``` + +### Build on Oracle Linux + +To build on Oracle Linux, follow these steps. + +#### 1. Install build tools + +```bash +dnf install -y git golang make +``` + +#### 2. Clone the exporter git repository + +```bash +git clone git@github.com:oracle/oracle-db-appdev-monitoring.git +``` + +#### 3. Build the binary + +```bash +cd oracle-db-appdev-monitoring +make go-build +``` + +You will now have a tar.gz and binary file in the `dist/` directory, named according to your target platform. + +For example, for the darwin-arm64 platform: + +``` +dist/ +├── oracledb_exporter-2.2.0.darwin-arm64 +│ └── oracledb_exporter +└── oracledb_exporter-2.2.0.darwin-arm64.tar.gz +``` diff --git a/site/versioned_docs/version-2.2.0/releases/changelog.md b/site/versioned_docs/version-2.2.0/releases/changelog.md new file mode 100644 index 00000000..99702b68 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/releases/changelog.md @@ -0,0 +1,321 @@ +--- +title: Changelog +sidebar_position: 2 +--- + +# Release Notes + +List of upcoming and historic changes to the exporter. + +### Version 2.2.0, October 28, 2025 + +Our current priorities to support metrics for advanced database features and use cases, like Exadata, GoldenGate, and views included in the Oracle Diagnostics Pack. + +- Allow loading database credentials from [HashiCorp Vault](../configuration/hashicorp-vault.md). +- Added experimental support for the [go-ora](https://github.com/sijms/go-ora) +- Move `oracledb_dbtype` metric to the default metrics. You may now disable or override this metric like any other database metric. +- Document required database permissions for the exporter. +- Fix an issue where some metrics would not be cached when using a per-metric scrape interval with a global scrape interval. +- Update third party dependencies +- Update Go runtime to 1.24.9 + +Thank you to the following people for their suggestions and contributions: +- [@MansuyDavid](https://github.com/MansuyDavid) +- [@jdagemark](https://github.com/jdagemark) +- [@ilmarkerm](https://github.com/ilmarkerm) + +### 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. +- If the exporter fails to connect to a database due to invalid or locked credentials (ORA-01017 or ORA-28000 errors), that database configuration will be invalidated and the exporter will not attempt to re-establish the database connection. Other databases will continue to be scraped. +- Metrics with an empty databases array (`databases = []`) are now considered disabled, and will not be scraped. +- Increased the default query timeout for the `top_sql` metric to 10 seconds (previously 5 seconds). +- Metrics using the `scrapeinterval` property will no longer be scraped on every request if they have a cached value. This only applies when the metrics exporter is configured to scrape metrics _on request_, rather than on a global interval. +- Metrics using the `fieldtoappend` property now support labels. The `wait_time` and `activity` default metrics use the `fieldtoappend` property, and now properly display their labels. +- Fix `wait_time` default metric to work with Oracle Database 19c. +- Fix an issue where the exporter would unnecessarily scrape metrics with a custom scrape interval. + +Thank you to the following people for their suggestions and contributions: +- [@romankspb](https://github.com/romankspb) +- [@muhammadabdullah-amjad](https://github.com/muhammadabdullah-amjad) +- [@MansuyDavid](https://github.com/MansuyDavid) +- [@borkoz](https://github.com/borkoz) +- [@ristagg](https://github.com/ristagg) + +### Version 2.0.4, September 8, 2025 + +This release includes the following changes: +- 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. + +Thank you to the following people for their suggestions and contributions: + +- [@Supporterino](https://github.com/Supporterino) +- [@msafdal](https://github.com/msafdal) +- [@aberinnj](https://github.com/aberinnj) + +### Version 2.0.3, August 27, 2025 + +This release includes the following changes: +- Enable configuration of the prometheus webserver from the config file using the `web` prefix. +- Allow loading of database password(s) from a file. +- Fixed a bug where database type (CDB, PDB, etc.) was not reported in certain situations. +- Fixed a bug where literal passwords containing the '$' character (in the config file) would be evaluated as environment variables. To use literal passwords with the '$' character, escape the '$' character with a second '$': `$test$pwd` becomes `$$test$$pwd`. +- Fixed a bug when using `metrics.scrapeInterval` combined with per-metric scrape intervals that made the available metrics data set inconsistent. + +Thank you to the following people for their suggestions and contributions: + +- [@Supporterino](https://github.com/Supporterino) +- [@neilschelly](https://github.com/neilschelly) +- [@aberinnj](https://github.com/aberinnj) +- [@redelang](https://github.com/redelang) +- [@qrkop](https://github.com/qrkop) +- [@KevDi](https://github.com/KevDi) +- [@bomuva](https://github.com/bomuva) +- [@anilmoris](https://github.com/anilmoris) +- [@Sycri](https://github.com/Sycri) +- [@kizuna-lek](https://github.com/kizuna-lek) +- [@rfrozza](https://github.com/rfrozza) +- [@neilschelly](https://github.com/neilschelly) + +### Version 2.0.2, June 24, 2025 + +This release includes the following changes: + +- Fixed a case-sensitive issue with resource name in the default metrics file. +- Add query timeouts to initial database connections, which could cause the exporter to hang in multi-database configurations +- Fix an issue where rapidly acquiring connections could cause the exporter to crash. This was more common in multi-database configurations, due to the increased number of connection pools. +- Update some third-party dependencies. + +Thank you to the following people for their suggestions and contributions: + +- [@rfrozza](https://github.com/rfrozza) +- [@neilschelly](https://github.com/neilschelly) +- [@rafal-szypulka](https://github.com/rafal-szypulka) +- [@darkelfit](https://github.com/darkelfit) + +### Version 2.0.1, June 12, 2025 + +This release includes the following changes: + +- Use gv$ views instead of v$ views to allow collection of metrics from all instances in a cluster. (In preparation for RAC support). +- Update some third-party dependencies. + +### Version 2.0.0, May 27, 2025 + +This release includes the following changes: + +- Fixed an issue with `scrapeinterval` that could cause metrics not to be scraped (#172, #176). +- Added configuration through a YAML file, passed using the `--config.file` command-line argument. Backwards compatibility is maintained for the command-line arguments, through it is recommended to use the configuration file from the 2.0.0 release onward. It is not recommended to use a combination of command-line arguments and the configuration file. +- Added support for multiple databases through the configuration file. As many database instances may be specified as needed, which will be scraped concurrently (#89). +- Updated provided dashboards. +- Updated some third-party dependencies. + +### Version 1.6.1, May 2, 2025 + +This release includes the following changes: + +- Updated some third-party dependencies. + +Thank you to the following people for their suggestions and contributions: + +- Deepak A. + +### Version 1.6.0, April 18, 2025 + +This release includes the following changes: + +- Added support for Azure Key Vault (#200). +- [4Aiur](https://github.com/4Aiur) added missing grants for alert log to the demo environment (#207). +- Updated some third-party dependencies. + +Thank you to the following people for their suggestions and contributions: + +- Brian, Damian et al. +- [4Aiur](https://github.com/4Aiur) + + +### Version 1.5.5, March 13, 2025 + +This release includes the following changes: + +- [@VictorErmakov](https://github.com/VictorErmakov) updated the docker-compose sample with connection pool parameters to avoid fast connect cycling (#191). +- Update default values for connection pool parameters to use go-sql pooling by default to avoid fast connet cycling. +- Updated some third-party dependencies. + +Thank you to the following people for their suggestions and contributions: + +- [@VictorErmakov](https://github.com/VictorErmakov) + + +### Version 1.5.4, March 3, 2025 + +This release includes the following changes: + +- Based of this recommendation from [godror](https://github.com/godror/godror?tab=readme-ov-file#pooling), which relates to the two following items, and in discussion with the ODPI-C team, we have introduced additional parameters to allow you to set connection pool parameters, and have set defaults which will avoid fast connect cycling. It is our expectation that a fix may be produced in the underlying ODPI-C library for the underlying issue. In the mean time, these changes will avoid the conditions under which the error can occur. +- Fix malloc error (#177, #181). +- Fix intermittent connection issues with ADB-S when exporter is run in a container (#169). +- Fix Multiple custom metrics files overwrite one another (#179). +- Replace go-kit/log with log/slog, due to upstream changes in prometheus/common. +- Add support for additional admin roles, expanding list of options for `DB_ROLE` to `SYSDBA`, `SYSOPER`, `SYSBACKUP`, `SYSDG`, `SYSKM`, `SYSRAC` and `SYSASM` (#180). +- Updated some third-party dependencies. + +Thank you to the following people for their suggestions and contributions: + +- [@Jman1993](https://github.com/Jman1993) +- [@oey](https://github.com/oey) +- [@jlembeck06](https://github.com/jlembeck06) +- [@Jman1993](https://github.com/Jman1993) +- [@PeterP55P](https://github.com/PeterP55P) +- [@rlagyu0](https://github.com/rlagyu0) +- [@Sycri](https://github.com/Sycri) + +Thank you to [@tgulacsi](https://github.com/tgulacsi) for changes in godror (https://github.com/godror/godror/issues/361, https://github.com/godror/godror/issues/360), and to [@cjbj](https://github.com/cjbj) and [@sudarshan12s](https://github.com/sudarshan12s) for support and guidance from ODPI-C (https://github.com/oracle/odpi). + +In this release, we also continued some minor code refactoring. + +### Version 1.5.3, January 28, 2025 + +*Known issue*: This release has a known issue that results in the error message `malloc(): unsorted double linked list corrupted`. +We recommend staying on 1.5.2 until a new release with a fix is available. We hope to have a fix by early March. + +This release includes the following changes: + +- Fix over-zealous supression of errors when `ignorezeroresult = true` (#168). +- When `scrapeinterval` is set, do first scrape immediately, not after the interval (#166). +- Updated some third-party dependencies. + +Thank you to the following people for their suggestions and contributions: + +- [@redelang](https://github.com/redelang) + +In this release, we also started some minor code refactoring. + +### Version 1.5.2, December 2, 2024 + +This release includes the following changes: + +- Update the metric defintion for tablespace usage to report more accurate temp space usage. +- Revert InstantClient to 21c version due to ADB connectivity issue. +- Update documentation to explain how to obtain credentials from a wallet. +- Fix race condition on err variable in scrape() func (by @valrusu). +- Updated some third-party dependencies. + +Thank you to the following people for their suggestions and contributions: + +- [@aureliocirella](https://github.com/aureliocirella) +- [@mitoeth](https://github.com/mitoeth) +- [@valrusu](https://github.com/valrusu) + +### Version 1.5.1, October 28, 2024 + +This release includes the following changes: + +- Added support for using the `TNS_ADMIN` environment variable, which fixes an issue when connecting to Autonomous Database instances using TNS name. +- Updated InstantClient to 23ai version for amd64 and latest available 19.24 version for arm64. +- Fixed an issue with wrong `LD_LIBRARY_PATH` on some platforms. (#136) +- Added documentation and an example of using the `scrapeinterval` setting to change the interval at which a certain metric is colected. +- Added notes to documentation for extra security parameters needed when using a wallet with Podman. +- Updated some third-party dependencies. + +### Version 1.5.0, September 26, 2024 + +This release includes the following changes: + +- Support for running the exporter on ARM processors (darwin and linux). +- Updated some third-party dependencies. +- Updated the "test/demo environment" to use newer version of Oracle Database (23.5.0.24.07) and faster startup. + +### Version 1.4.0, September 4, 2024 + +This release includes the following changes: + +- Allow multiple custom metrics definition files. +- Allow query timeout per-metric. +- Allow scrape interval per-metric. +- Updated some third-party dependencies. + +### Version 1.3.1, July 22, 2024 + +This release includes the following changes: + +- Alert logs can be disabled by setting parameter `log.disable` to `1`. +- Alert log exporter will stop if it gets three consecutive failures. +- Updated the list of required permissions. +- Updated the TxEventQ sample dashboard. +- Updated some third-party dependencies. + +Thank you to the following people for their suggestions and contributions: + +- [@tux-jochen](https://github.com/tux-jochen) + +### 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. +- Default 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) + +### Version 1.2.1, April 16, 2024 + +This release includes the following changes: + +- Accept max idle and open connections settings as parameters. +- Updated some third-party dependencies. + +### Version 1.2.0, January 17, 2024 + +This release includes the following changes: + +- Introduced a new feature to periodically restart the process if requested. +- Introduced a new feature to periodically attempt to free OS memory if requested. +- Updated some third-party dependencies. + +### Version 1.1.1, November 28, 2023 + +This release just updates some third-party dependencies. + +### Version 1.1, October 27, 2023 + +This release includes the following changes: + +- The query for the standard metric `wait_class` has been updated so that it will work in both container databases + and pluggable databases, including in Oracle Autonomous Database instances. Note that this query will not return + any data unless the database instance is under load. +- Support for reading the database password from OCI Vault has been added (see [details](../configuration/oci-vault.md)) +- Log messages have been improved +- Some dependencies have been updated + +### Version 1.0, September 13, 2023 + +The first production release, v1.0, includes the following features: + +- A number of [standard metrics](../getting-started/default-metrics.md) are exposed, +- Users can define [custom metrics](../configuration/custom-metrics.md), +- Oracle regularly reviews third-party licenses and scans the code and images, including transitive/recursive dependencies for issues, +- Connection to Oracle can be a basic connection or use an Oracle Wallet and TLS - connection to Oracle Autonomous Database is supported, +- Metrics for Oracle Transactional Event Queues are also supported, +- A Grafana dashboard is provided for Transactional Event Queues, and +- A pre-built container image is provided, based on Oracle Linux, and optimized for size and security. + +Note that this exporter uses a different Oracle Database driver which in turn uses code directly written by Oracle to access the database. This driver does require an Oracle client. In this initial release, the client is bundled into the container image, however we intend to make that optional in order to minimize the image size. + +The interfaces for this version have been kept as close as possible to those of earlier alpha releases in this repository to assist with migration. However, it should be expected that there may be breaking changes in future releases. \ No newline at end of file diff --git a/site/versioned_docs/version-2.2.0/releases/roadmap.md b/site/versioned_docs/version-2.2.0/releases/roadmap.md new file mode 100644 index 00000000..a1b89425 --- /dev/null +++ b/site/versioned_docs/version-2.2.0/releases/roadmap.md @@ -0,0 +1,21 @@ +--- +title: Roadmap +sidebar_position: 1 +--- + +# Exporter Roadmap + +Planned and upcoming features for the exporter. + +We welcome input on community-driven features you'd like to see supported. Please open an issue in this repository with your suggestions. + +Currently, we plan to address the following key features: + +- Provide default Oracle Exadata metrics +- Provide default GoldenGate metrics +- Enhance database alert logging and alert log metrics +- Provide the option to have the Oracle client outside of the container image, e.g., on a shared volume, +- Implement the ability to update the configuration dynamically, i.e., without a restart +- Implement support for tracing within the database, e.g., using an execution context ID provide by an external caller +- Provide additional pre-built Grafana dashboards, +- Integration with Spring Observability, e.g., Micrometer diff --git a/site/versioned_sidebars/version-2.2.0-sidebars.json b/site/versioned_sidebars/version-2.2.0-sidebars.json new file mode 100644 index 00000000..caea0c03 --- /dev/null +++ b/site/versioned_sidebars/version-2.2.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/site/versions.json b/site/versions.json index 5bce6f0c..0e85851a 100644 --- a/site/versions.json +++ b/site/versions.json @@ -1,4 +1,5 @@ [ + "2.2.0", "2.1.0", "2.0.4", "2.0.3"