Oracle AI Database Metrics Exporter

The Oracle AI Database Metrics Exporter is a tool designed to monitor the health, performance, and availability of Oracle AI Database instances. It allows you to collect metrics from one or more databases using a single exporter instance and provides multiple delivery paths:

• Prometheus Format: Exposes metrics on the default /metrics endpoint.
• OpenTelemetry (OTLP/gRPC): Publishes metrics directly to an OpenTelemetry backend.

The exporter is designed to work across various environments, including on-premises, cloud, and Kubernetes, supporting single instances, clusters, or Autonomous Oracle AI Database instances. It ensures that if one database goes offline for maintenance, other monitored databases remain active.

The exporter watches its configuration file for changes. When the file is modified, the exporter will dynamically restart while maintaining the same PID.

Safety Mechanism: If a new configuration file is invalid or cannot be parsed, the exporter will continue running using the previous valid configuration until a valid file is provided.

You can override properties of an existing metric (like scrapeinterval, querytimeout, or labels) by providing a new definition in a custom metrics file that uses the exact same context and metricsdesc values. This allows you to refine existing metrics without redefining the entire logic.

[[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, 'val' as label_1, 'val' as label_2 FROM DUAL"
scrapeinterval = "30s"
querytimeout = "10s"

When scraping multiple databases, it is recommended to set log.perDatabaseFiles: true. This prevents all databases from writing to a single shared file and instead creates individual files following the pattern alert-<db>.log.

For example, if log.destination is set to /opt/exporter/alert.log and a database is named db2, the log will be written to /opt/exporter/alert-db2.log.

By default, every metric is scraped from all connected databases. You can restrict a metric to specific databases by defining a databases array within the metric configuration.

• If databases is an array of names (e.g., [ "db2", "db3" ]), the metric is only scraped from those specific databases.
• If databases is empty or omitted, the metric is scraped from all connected databases.

[[metric]]
context = "db_platform"
labels = [ "platform_name" ]
metricsdesc = { value = "Database platform" }
request = '''
SELECT platform_name, 1 as value FROM gv$database
'''
databases = [ "db2", "db3" ]

For mutual TLS (mTLS) connections, you must use an Oracle Wallet.

1. Set the TNS_ADMIN environment variable to the directory containing your unzipped wallet.
2. In your configuration, use the TNS name from the wallet's tnsnames.ora file as the url.

Example Configuration:

databases:
  mydb:
    username: admin
    password: <REPLACE ME>
    url: <TNS Name>

Docker Usage: If running as a container, mount the wallet directory as a volume:

docker run -it --rm \
    -e DB_USERNAME=pdbadmin \
    -e DB_PASSWORD='<your-password>' \
    -e DB_CONNECT_STRING=devdb_tp \
    -v ./wallet:/wallet \
    -p 9161:9161 \
    container-registry.oracle.com/database/observability-exporter:2.5.0

You can deploy the website using yarn deploy with different configurations depending on your hosting method:

• Using SSH: Set USE_SSH=true.
• Using GitHub Pages: Provide your GitHub username via the GIT_USER environment variable. This will build the site and push it to the gh-pages branch.

# Using SSH
USE_SSH=true yarn deploy

# Using GitHub Pages
GIT_USER=<Your GitHub username> yarn deploy