Werk #22245: mk-oracle: New experimental agent plug-in for Oracle databases
| Component | Checks & agents | ||||
| Title | mk-oracle: New experimental agent plug-in for Oracle databases | ||||
| Date | Oct 15, 2026 | ||||
| Level | Prominent Change | ||||
| Class | New Feature | ||||
| Compatibility | Compatible - no manual interaction needed | ||||
| Checkmk versions & editions |
|
mk-oracle is a new but experimental agent plug-in for Oracle databases. It is an executable binary, unlike the legacy plug-in, which is a set of Bash and PowerShell scripts. Instead of SQL*Plus, it queries your databases through the Oracle Instant Client. It sends the same agent sections as the legacy plug-in, so the same check plug-ins create the same services.
As of this release, most of what you need to switch from the legacy plug-in is available.
You can configure the plug-in with the agent bakery rule: Oracle databases (Experimental), or manually with the main configuration file, mk-oracle.yml.
A host can run only one of the two plug-ins, the legacy plug-in or mk-oracle. If both rule-sets are applied to a host, the agent bakery refuses to bake its agent.
The User Guide article Monitoring Oracle databases explains the setup, and the plug-in's README describes every setting in detail.
Requirements
- Linux, AIX, Solaris or Windows.
- The Oracle Instant Client libraries, which Checkmk does not ship. The plug-in uses a client in its subfolder
oic, the client of an Oracle installation on the host, or a path that you set withuse_host_client. See Deploying Oracle Instant Client. - Oracle 12.1.0.2 or later. Older releases are not supported.
Features
One Implementation, Multiple Platforms
Instead of bespoke shell scripts which have diverging features on each platform, we have a single, unified plug-in which uses one configuration format across all supported platforms.
mk-oracle.yml is the primary configuration file and is the same no matter which platform you use, unlike the legacy plug-in which had bash variables on Unix-like platforms and PowerShell on Windows.
The bakery rule for the new plug-in has minimal platform specific settings, with the most common settings having the same effect on each platform. If there are platform differences for these settings, they are clearly documented.
Configuration Migration
There are two migration paths for users of the legacy plugin.
Firstly, for Agent Bakery users, we have a command line tool to migrate bakery rules called cmk-migrate-oracle-rulesets. It is run on a site and provides a method for bringing legacy rules forward, while preserving those rules in case of trouble.
Secondly, on the host side, the new plug-in itself has a migration flag which allows conversion of legacy shell scripts to the new yaml configuration format.
No matter the method chosen, each command will list warnings for any unsupported settings or differences in meaning.
See Migration from mk_oracle to mk-oracle and MIGRATION.md for more details.
Override settings with mk-oracle.user.yml
Every agent update replaces mk-oracle.yml with the latest baked version, so you lose any changes made locally to it. Put your changes into mk-oracle.user.yml instead. The baked agent does not contain this file, so agent updates don't touch it.
The mk-oracle.user.yml file has the same format as mk-oracle.yml, except every key in it is optional. The plug-in merges settings from the file on top of mk-oracle.yml.
If the plug-in cannot read the file, it logs a warning and ignores the file. A typo in the file therefore does not stop the monitoring of configured instances.
This is in stark contrast to the legacy plug-in, which used multiple shell files for overriding values, possibly executing arbitrary code, and had no good way of flagging failure.
For all merge rules, see User Configuration File in the README.
Override built-in queries
The legacy plug-in stored the queries it used to monitor the database within each shell script. They could not be overridden in any way, except by making volatile edits to the shell scripts themselves.
The new plug-in allows its built-in queries to be overridden, in cases where you want to write a query with more speed (or more context) which emits the same section.
There are two ways of achieving this: either you can store the SQL as a file in the orasql folder of the plug-in or you can place the SQL text directly in the mk-oracle.user.yml configuration. This feature is not currently supported by the Agent Bakery rule.
With the file-based approach, you can target different versions of Oracle.
To do this, add variants named <name>@<version>.sql, with the version written as eight digits. The plug-in picks the variant with the highest version that the database has reached. For older databases, it uses the plain file. The following two files show an example:
orasql/sessions.sql # Oracle 12.1 to 18c
orasql/sessions@19000000.sql # Oracle 19c and later
When the plug-in runs as root or as administrator, it skips SQL files that other users can modify and logs a warning.
The feature is described in much more detail in the plug-in README under External SQL files.
Custom SQL metrics
The legacy plug-in could only run custom metrics queries on Linux, AIX and Solaris. Windows had no support for this feature.
With the new plug-in, every supported platform can run SQL queries to generate custom metrics. You can define these queries either for all instances or for a single instance.
Just like Override built-in queries, it is not supported in the Agent Bakery rule.
To configure a query for every instance, in mk-oracle.user.yml you can specify either an inline sql query or the path to a SQL file under the custom_metrics entry.
To configure a query for a single instance, add an instances list to the file, and put the query under custom_metrics in that instance's entry.
It's important to note that specifying instances in mk-oracle.user.yml replaces the full instance list of mk-oracle.yml, so make sure to duplicate the instances that you wish to keep.
The name of an entry is used to derive its service name. For each instance, one service is created per query. For example: if your instance is called "WAREHOUSEDB" and yaml name is "product_price", a service with the name ORA WAREHOUSEDB SQL PRODUCT_PRICE is created.
Because we no longer use SQL*Plus, only plain SQL queries will work. This is the biggest difference between the legacy plug-in and the new one.
The User Guide explains simple and advanced custom SQL queries and has a reference for custom SQL queries.
Pluggable databases
On a container database (CDB), the new plug-in finds open pluggable databases (PDBs) itself and can run queries inside them. Setting up a connection for each PDB is not needed. The legacy plug-in had PDB support for its built-in sections, but for custom metrics you had to configure each PDB connection explicitly.
A custom metric runs in the root of the CDB by default. To run it on PDBs instead, list them under pdbs. Each entry is a regular expression that has to match the whole name of a PDB, regardless of case. The query then runs in every open PDB that matches, but not in the root.
Each PDB gets its own service. The name consists of the instance, the PDB and the configuration name, in that order. For example: if your instance is called "WAREHOUSEDB", the PDB is called "SALES" and the configuration name is "product_price", the service is ORA WAREHOUSEDB_SALES SQL PRODUCT_PRICE.
Built-in sections accept the same pdbs setting. They then run in the root and in the matching PDBs. The performance section already does this for every open PDB without any setting, as did the legacy plug-in.
The monitoring user needs the SET CONTAINER privilege, and the plug-in has to connect to the service of the CDB root, not to the service of a PDB.
The User Guide describes how to grant access rights, including for users of multi-tenant databases. For more information on SET CONTAINER or targeting PDBs, check the README under Targeting Pluggable Databases (PDBs).
Cache age of custom metrics
By default, a custom metric runs on every agent run. To run a slow query less often, set is_async: yes on its entry. The plug-in then reuses the last result until it is older than the cache age. Cached custom metrics use the same cache age as the asynchronous built-in sections. It is 600 seconds unless you change the cache age in the agent bakery rule.
The legacy plug-in cached a custom query whenever SQLS_MAX_CACHE_AGE was set, and each query could have its own age. In the new plug-in, you cache a metric with is_async, and all cached metrics use the same age.
The User Guide describes the cache age in its configuration options. The README explains how asynchronous sections work in Synchronous and Asynchronous Execution.
Limitations
- No ARM support. The plug-in does not run on
aarch64(64-bit ARM). On those hosts, keep the legacy plug-in. If you install a baked DEB or RPM package on an ARM host, the package prints a warning. - Oracle 12.1.0.2 or later. The plug-in's queries use columns that Oracle introduced in 12.1 and 12.1.0.2. On an older instance, the Instance service reports an error instead of monitoring the database.
- Agent bakery rule. The rule Oracle databases (Experimental) has no settings for custom SQL metrics or for replacing built-in queries, so you define them in
mk-oracle.user.yml. - No SQL*Plus features in custom SQL.
- Settings that the migration cannot convert. For some legacy settings, the migration only warns or leaves a comment.