In zztat the gauge is where the measurements take place. The gauge acts as a filter for the data produced by your metric and only lets data points pass which we consider "not good". In other words, the gauge's filters are to be set up in such a way that they match the problematic values.
To use the all-too-familiar example of tablespaces - you want your gauge to return the tablespaces which are running full so that it can act on it; you don't want it to return the tablespaces that have enough free space. The metric's job is to capture "all the data" that you'd like to collect (and archive). The gauge just filters the data that needs further attention.
- 1 Overview
- 2 Supported Gauge Types
- 3 Gauge Metadata
Like zztat's metrics, a gauge can operate in different modes, controlled by the flags which are assigned to it. Without any flags, a gauge is referred to as a standard gauge and is executed normally through the Oracle scheduler.
A gauge name must adhere to the following rules:
- Maximum 13 characters in length.
- Only characters which are valid Oracle unquoted identifiers for object names such as table names can be used (A-Z, a-z, 0-9, $, #, _ ).
- No reserved zztat words may be used to name a gauge.
- Gauge names are automatically converted to uppercase when a metric is added.
Default and Database-Specific Gauges
A gauge in zztat is uniquely identified by a combination of the DBID and the gauge name. This allows a gauge to exist multiple times, but with different attributes (for example different filters or override values) for different databases. Out of the box, all zztat gauges ship with a DBID of -1 which represents all databases, and is referred to as a default gauge.
New gauges created can be specified as default gauges by not specifying a DBID, or as database-specific gauges by assigning them a given DBID. Default gauges can be copied to create database-specific gauges without having to re-create the gauges. Copying a gauge will copy all of its columns, ignore values and overrides. Gauge columns, ignores or overrides may not be individually made database-specific. They are bundled as a single entity with the gauge itself.
Supported Gauge Types
There are currently two major types of gauges, corresponding to the respective metric types.
A standard gauge is defined by the following characteristics:
- The gauge is assigned to a standard metric.
- A gauge job is scheduled and executed by the Oracle scheduler.
- The gauge is assigned a default volume, expressed in a temporal fashion.
An auto-sync gauge is defined by the following characteristics:
- The gauge is automatically triggered by the SYNC process when the corresponding metric has completed its snapshot.
- The gauge volume is ignored - all data collected by the metric is scanned.
- If there are multiple gauges defined for the metric in question, they will fire in alphabetical order, but asynchronously (virtually at the same time).
Please note that there is currently no means to establish dependency between multiple auto-sync gauges - e.g. they will always fire at the same time and you can't (yet) instruct zztat to let one gauge complete before the next one fires. This may change in future versions.
There are various components which make up the definition of a gauge:
- The gauge DBID
- The gauge name
- The metric the gauge is for
- The gauge interval, if applicable
- The gauge volume, if applicable
- The reaction to fire when the a warning or critical alert is raised
- The message to submit to the reaction
- Flags to control the gauge's behavior
Additionally, a gauge can contain the following components:
- Gauge columns which specify the values to check for (every gauge must have at least one gauge column).
- Gauge ignores which specify values to disregard and ignore (optional).
- Gauge overrides which can override the column's filters for specific values (optional).
Logic Brings Order to Chaos
By default when you are creating a gauge, any columns that you will add to the gauge which will act as filters for your data, will be combined using the logical OR operator. For example, if you are defining a gauge to monitor tablespace free space, you may want to check if the percentage free space falls below a certain threshold OR the amount of space available falls below a certain threshold. In these cases, logical OR makes perfect sense.
You may however have a requirement to combine the filters with the logical AND operator instead. This is supported and can be achieved by setting the LOGICAL_AND flag on the gauge. An example of this would be the default session wait gauge SES_LATCH, which filters the events by type and then has gauge columns that act only if the type matches the desired type (in this case latches) AND the threshold exceeds the warning or critical limits.
The gauge volume provides a means to ensure the gauge query completes fast. In most cases, gauges that run on target databases will be reading small amounts of data, that corresponds to the last one or two snapshots taken. But when a gauge runs on the zztat repository it may have access to the entire history of metric snapshots. Potentially months worth of data. The gauge volume can be used to instruct the gauge to only read the amount of data specified - for example the last 3 days.
Gauge & Metric Compatibility
Please note that certain modes are incompatible. This means that if you are defining a standard metric, the gauges must be standard gauges as well. And, if you are defining an auto-sync metric, the gauges must be auto-sync gauges. This may change in future versions to allow for more flexible combinations.
When writing SQL queries to analyze the snapshot data you must adhere to the following guidelines:
- The first two columns must be BEGIN_TIME (TIMESTAMP) and SNAP# (NUMBER).
- BEGIN_TIME MUST be an actual TIMESTAMP - it cannot be a TIMESTAMP WITH TIME ZONE or TIMESTAMP WITH LOCAL TIME ZONE data type. Use the following expression if you want to use SYSTIMESTAMP: "cast (systimestamp as timestamp)".
- If your data source does not have a snapshot number, use the static number 1.
- You can access zz$snap to retrieve the begin_time and snap# of the corresponding metric's snapshots.
- The length of all columns concatenated can't exceed 4000 bytes
- Your gauge query may not include LOB, XMLTYPE or UDT (user defined data types). If you require this functionality for a specific gauge, let us know: send an email to firstname.lastname@example.org.
- Column names in your gauge query may not include non-alphanumeric characters. This includes the special characters # and $ which are legal in Oracle column names. Use aliases to correct this when selecting such columns.
- Your gauge query may not contain duplicate columns. Use column aliases to ensure column names are unique.
- Your gauge query cannot contain bind variables.
- Your gauge query cannot include an ORDER BY clause; analytic window functions using the order by clause are ok.
Gauge columns are what filters the data returned by the base gauge query. For your gauge to execute, you must define at least one gauge column. For all the various options, please see the pages on Gauge Columns.
To eliminate certain data points from the checks the gauge is doing (for example if you do not wish to monitor certain tablespaces) you may add ignores to the gauge. These act as preliminary filters and are injected into the gauge query before the gauge column filters. For all the details on ignores, please see the pages on Gauge Ignores.
The final gauge component is the gauge overrides. They may be used when a certain data point requires a different warning or critical threshold, for example if a specific tablespace is highly critical and you want to immediately react if it ever reaches 50%, whereas for your other "normal" tablespaces you may want to use the default thresholds of, for example, 80% or 85%. For details on how to use and define overrides, please see the pages on Gauge Overrides.