zz$manage

From zzat
Jump to: navigation, search

zz$manage is the core of zztat and offers all the functionality needed to customize it to leverage its full power.

For a quick overview on common tasks and how to accomplish them, please refer to the quick guides.

Operational Notes

DBIDs and Default Objects

In zztat, most objects (metrics, gauges, reactions or reaction chains) are uniquely identified by a combination of their name and the DBID of the database they are attached to. This allows, for example, the same metric to exist multiple times but with different attributes for different databases. By default, and if no DBID is specified when creating an object, it is assigned a DBID of -1, which designates a default object. This object will run on every database if it's enabled. If an object with a specific database's DBID exists, that object takes precedence. For example if you have 10 databases in your zztat environment, and you create a new default metric called LATCH_CHECK, that metric will then run on all databases. If you don't want it to run on a specific database, copy the metric to that databases' DBID, and disable the copy. The database-specific copy will always take precedence, and if the copy was disabled, it will therefore not run on that database, but on all the others.

Changing Gauges

When you're changing a gauge via any of the gauge_*edit procedures that has outstanding (unprocessed) alerts pending on a target database, those alerts are automatically acknowledged.

Object Changes

Please note that this package is intended for zztat administration: changes to metrics, gauges and reactions can only be done on the repository database!

zztat will automatically synchronize changes with the target databases. This happens either:

Constants

The package zz$manage defines the following constants:

Constant Usage Metric Gauge Reaction Reaction Chain Reaction Source Blackout Description
AUTOSYNC Flag X X Enable auto-sync mode on a metric or gauge
CORRECTIVE X Marks a reaction as a corrective action. For future use to provide recommendations.
CURRENT X Marks a user reaction source version as the current version.
DISABLE X X X Disable an object.
DISABLE_ON_FAIL (not yet implemented)
REPLICATE_ONLY X Designate a metric as replicate-only
INTERNAL X X Designate a metric as internal
LOGICAL_AND X Switches the gauge to combine multiple gauge columns with the logical AND operator, instead of the default (OR)
ON_DEMAND X Marks the metric to be executed only on demand.
ON_UPGRADE X Marks the metric to be executed on installs, patches or when zztat detects a database upgrade
REP_READ_ONLY X Causes REPLICATE to act in a read-only manner and leaves the data in the target's staging tables.
REPOSITORY_ONLY X X X Marks the object to only be executable on the zztat repository database
SILENT X Marks a blackout as a silent blackout.
SKIP_FAILED X Instructs a reaction chain to continue when a reaction failed. Default behavior is to stop the entire chain on error.
SNAP_TWICE X Causes the metric to take two snapshots whenever it is executed.
STAGE_LATEST X Causes REPLICATE to always retain the latest snapshot on targets.
SYNC_REACT X For auto-sync metrics, causes REPLICATE to wait for reactions to complete before replicating.
TARGET_ONLY X X X Marks the object to only be executable on target databases
TRUNC_ON_SNAP X Marks the metric to empty the staging table before taking a snapshot
USE_QUEUES X Internal use only.
OPER_LT Operator Gauge column operator "less than"
OPER_GT Gauge column operator "greater than"
OPER_EQ Gauge column operator "equal to"
OPER_NE Gauge column operator "not equal to"
OPER_BW Gauge column operator "between"
OPER_NB Gauge column operator "not between"

Procedures and Functions

Summary of procedures and functions in zz$manage:

Procedure Description
metric_add Add a new metric
metric_copy Create a database-specific copy of a default metric
metric_edit Change attributes of a metric
metric_refresh Refresh metric metadata from the repository.
metric_run Manually start a metric's snapshot job.
metric_remove Remove a metric
metric_set_flag Set a flag on a metric
metric_reset_flag Remove a flag from a metric
gauge_add Add a new gauge
gauge_edit Change attributes of a gauge
gauge_remove Remove a gauge
gauge_run Manually start a gauge job.
gauge_set_flag Set a flag on a gauge
gauge_reset_flag Remove a flag from a gauge
gauge_col_add Add a column to a gauge
gauge_col_edit Change thresholds and message for a gauge
gauge_col_remove Remove a column from a gauge
gauge_ignore_add Add an ignore to a gauge
gauge_ignore_remove Remove an ignore from a gauge
gauge_override_add Add an override to a gauge
gauge_override_remove Remove an override from a gauge
reaction_add Add a new reaction
reaction_edit Change attributes of a reaction
reaction_remove Remove a reaction
reaction_chain_add Add a new reaction chain
reaction_chain_remove Remove a reaction chain
reaction_config Configure reaction parameters
reaction_config_copy Create database-specific reaction parameters
validate_reaction Validate a reaction
clear_tasks Clears the task staging table. Useful for testing.
enable_trace Enables tracing in a specified zztat module
disable_trace Disables tracing in a specified zztat module
deregister Removes a database from the zztat repository, freeing up a license slot.
mail_recipient_add Adds an email address to receive emails from zztat.
mail_recipient_remove Removes an email address from zztat's email recipient list.

Package Documentation

Parameters listed in italic font indicate optional parameters. See the description to find the default values or behavior if those optional parameters are omitted.

zz$manage package specification
Type Name Parameters Data Type Description
procedure clear_tasks
Clears the task staging table zz$sync_staging. Useful when testing your own metrics, gauges or reactions.
procedure deregister
dbid

purge_history

number

boolean

dbid: Identify the database to remove from zztat.

purge_history: Defaults to true. Controls whether or not to also delete all history data for the database to be removed.

The deregister procedure removes a database from the zztat repository. To complete de-registration, run deinstall.sql on the target database. If the target database will be dropped or has been dropped already, this step can be skipped.

Set purge_history to false to retain the historic metric data. For a database that has a lot of archived data, this procedure might take a long time to complete.

procedure disable_trace
facility

module

varchar2

varchar2

Deactivates extended SQL tracing for the given facility / module.
procedure enable_trace
facility

module

level

varchar2

varchar2

number

Activates extended SQL tracing for the given facility / module.

Use under the supervision of zztat support only.

procedure gauge_add
dbid

name

metric

query

comments

gauge_interval

gauge_unit

gauge_volume

warn_reaction

crit_reaction

warn_message

crit_message

flags

number

varchar2

varchar2

clob

varchar2

number

varchar2

interval_day_to_second

varchar2

varchar2

varchar2

varchar2

number

Adds a new gauge to a zztat metric.

dbid + name: A gauge is uniquely identified by the dbid + name parameters. Specifying NULL or omitting the dbid will create a default gauge, which can be executed against data from any database. This is the intended default - you should only create database-specific gauges if you have a specific need to override the default gauge. Note that the gauge name cannot exceed 13 characters.

metric: Specify the metric that this gauge will be running against. A metric can have multiple gauges running against the data it produces, but a gauge can only be mapped to a single metric.

query: Enter the query that will serve as the baseline SQL for this gauge. The query must adhere to certain standards. For specifications on what types of queries are supported, see here.

comments: Enter a descriptive comment that identifies what this gauge is for. Use this field instead of the name field to describe your gauge.

gauge_interval: For standard gauges, this is the interval that the scheduler will run the gauge at. If specified, must be combined with gauge_unit.

gauge_unit: For standard gauges, this specifies the unit to use for the gauge_interval. Valid values are: SECOND, MINUTE, HOUR, DAY, MONTH, YEAR.

gauge_volume: For standard gauges, this specifies the volume of data to analyze during each run. zztat will automatically adjust this if it detects that the gauge has missed runs and will increase the volume up to a maximum of 7 days.

warn_reaction: The reaction to trigger if any of the gauge's warning thresholds are exceeded by a data point created by the metric.

crit_reaction: The reaction to trigger if any of the gauges's critical thresholds are exceeded by a data point created by the metric.

warn_message: The title message to pass to the reaction when a warning is triggered. Supports substitution variables.

crit_message: The title message to pass to the reaction when a critical is triggered. Supports substitution variables.

flags: Flags alter the behavior of the gauges and control their execution. Use the constants provided in the zz$manage package.

Notes:

  • You can specify either a warn_reaction & warn_message, a crit_reaction & crit_message, or both
  • When creating an auto-sync gauge, gauge_interval, gauge_unit and gauge_volume must not be specified
  • Omit the dbid to create a default gauge. This is the recommended way to do it unless you have specific requirements for database-specific gauges.
  • You can combine multiple flags by simply adding them together. For example zz$manage.REPOSITORY_ONLY + zz$manage.LOGICAL_AND
procedure gauge_col_add
dbid

gauge

column_name

informational_column

column_operator

warn_limit_numeric

crit_limit_numeric

warn_message

crit_message

number

varchar2

varchar2

varchar2

number

number

number

varchar2

varchar2

Adds a new numeric threshold value for the gauge to watch for.

dbid + gauge: To specify the gauge to add the new column to.

column_name: Specify which column to set the threshold for. The column must be a valid column used in the query when creating the gauge. The values in this column are where the warning and critical thresholds are checked against. For example, this would be space_used or pct_free when creating a gauge to monitor tablespace space usage.

informational_column: Specify which column identifies what the value is that we are watching in column_name. For example, this would be tablespace_name when creating a gauge to monitor tablespace space usage.

column_operator: Specify the operator to use when checking the values. Valid operators are: OPER_LT, OPER_GT, OPER_EQ, OPER_NE, OPER_BW, OPER_NB.

warn_limit_numeric: Specify the numeric value that triggers a warning alert when the column condition evaluates to true.

crit_limit_numeric: Specify the numeric value that triggers a critical alert when the column condition evaluates to true.

warn_message: A supplemental message that is passed to the reaction when a warning is triggered. Supports substitution variables.

crit_message: A supplemental message that is passed to the reaction when a critical is triggered. Supports substitution variables.

Notes:

  • You can specify either a warn_limit_numeric & warn_message, a crit_limit_numeric & crit_message, or both.
  • To add a database-specific column, a database-specific gauge must exist. You can't add a database-specific column to a default gauge.
procedure gauge_col_add dbid

gauge

column_name

informational_column

column_operator

warn_limit_string

crit_limit_string

warn_message

crit_message

number

varchar2

varchar2

varchar2

number

varchar2

varchar2

varchar2

varchar2

An overload of gauge_col_add for string values instead of numeric values.
procedure gauge_col_add dbid

gauge

column_name

informational_column

column_operator

warn_limit_date

crit_limit_date

warn_message

crit_message

number

varchar2

varchar2

varchar2

number

varchar2

varchar2

varchar2

varchar2

An overload of gauge_col_add for date values instead of numeric values.
procedure gauge_col_edit
dbid

gauge

column_number

warn_limit_numeric

crit_limit_numeric

warn_message

crit_message

cascade

number

varchar2

number

number

number

varchar2

varchar2

boolean

Allows you to change the limits or messages of a gauge column. If you only specify the warning limit, the critical limit will remain unchanged. Use for numeric values.

dbid + gauge: Specify the gauge the column belongs to.

column_number: Specify the gauge column number to edit.

warn_limit_numeric: Specify the new warning threshold.

crit_limit_numeric: Specify the new critical threshold.

warn_message: Specify the new warning message text.

crit_message: Specify the new critical message text.

cascade: Only has an effect if you omit the DBID or specify -1 and set cascade to TRUE. The specified gauge will be edited for all databases. If cascade is false, only the default gauge will be edited. Cascade can't be set when editing a database-specific gauge.

procedure gauge_col_edit dbid

gauge

column_number

warn_limit_string

crit_limit_string

warn_message

crit_message

cascade

number

varchar2

number

varchar2

varchar2

varchar2

varchar2

boolean

procedure gauge_col_edit dbid

gauge

column_number

warn_limit_date

crit_limit_date

warn_message

crit_message

cascade

number

varchar2

number

date

date

varchar2

varchar2

boolean

procedure gauge_col_edit dbid

gauge

column_number

remove_warn_limit

remove_crit_limit

number

varchar2

number

boolean

boolean

procedure gauge_col_remove dbid

gauge

column_number

number

varchar2

number

Removes a threshold column from a gauge.
procedure gauge_edit dbid

gauge

query

gauge_interval

gauge_unit

gauge_volume

warn_reaction

crit_reaction

warn_message

crit_message

cascade

number

varchar2

clob

number

varchar2

interval_day_to_second

varchar2

varchar2

varchar2

varchar2

boolean

Updated the properties of a gauge. All parameters are optional - those who are not specified to be changed retain their current values.

dbid + gauge: To specify the gauge to edit.

query: To replace the gauge query.

gauge_interval: Specify a new interval to schedule the gauge at.

gauge_unit: Specify a new unit to form the schedule with gauge_interval.

gauge_volume: Change the default data volume that the gauge analyzes.

warn_reaction: Replace the warning reaction the gauge will trigger.

crit_reaction: Replace the critical alert reaction the gauge will trigger.

warn_message: Change the warning message the gauge will send to the reaction.

crit_message: Change the critical alert message the gauge will send to the reaction.

cascade: Only has an effect if you omit the DBID or specify -1 and set cascade to TRUE. The specified gauge will be edited for all databases. If cascade is false, only the default gauge will be edited. Cascade can't be set when editing a database-specific gauge.

procedure gauge_ignore_add dbid

gauge

column_name

ignore_value_numeric

comments

number

varchar2

varchar2

number

varchar2

Add a specific expression to a gauge column that is ignored and you do not want alerts triggered for. To use the tablespace space example once more, you would specify a tablespace here that is always full, and is supposed to be full and you don't want alerts or warning raised because of it.

dbid + gauge: To specify the gauge to add the new column to.

column_name: Specify the column to add an ignored value to. The specified column must exist in the gauge query.

ignore_value_numeric: Specify the value to ignore.

comments: Enter a descriptive comment to identify why this is ignored (or by whom, for example).

procedure gauge_ignore_add dbid

gauge

column_name

ignore_value_string

comments

number

varchar2

varchar2

varchar2

varchar2

An overload of gauge_ignore_add for string values instead of numeric values.
procedure gauge_ignore_add dbid

gauge

column_name

ignore_value_date

comments

number

varchar2

varchar2

date

varchar2

An overload of gauge_ignore_add for date values instead of numeric values.
procedure gauge_ignore_remove
dbid

gauge

column_name

ignore_value_numeric

number

varchar2

varchar2

number

Removes an ignore value from a gauge.
procedure gauge_ignore_remove dbid

gauge

column_name

ignore_value_string

number

varchar2

varchar2

varchar2

An overload of gauge_ignore_remove for string values instead of numeric values.
procedure gauge_ignore_remove dbid

gauge

column_name

ignore_value_date

number

varchar2

varchar2

date

An overload of gauge_ignore_remove for date values instead of numeric values.
procedure gauge_override_add
dbid

gauge

column_name

informational_column

override_name

value_numeric

override_warn_limit_numeric

override_crit_limit_numeric

override_warn_limit_string

override_crit_limit_string

override_warn_limit_date

override_crit_limit_date

comments

number

varchar2

varchar2

varchar2

varchar2

number

number

number

varchar2

varchar2

date

date

varchar2

Adds an override value for a threshold column.

dbid + gauge: Specify the gauge to add the override to.

column_name: Specify the gauge threshold column to override. The specified column must be a valid column for the specified gauge.

informational_column: Specify the informational_column of the gauge to check the override value against. The specified column must be a valid column for the specified gauge.

override_name: A unique identifier for this override. This name must be unique per gauge column.

value_numeric: This value is checked against the informational_column to determine whether or not to apply the override, or use the base column thresholds. Use the correct overload based on the data type of the informational_column in the base query.

override_warn_limit_numeric: Specify the new threshold value. This can be used only if the base column has warn_limit_numeric set.

override_crit_limit_numeric: Specify the new threshold value. This can be used only if the base column has crit_limit_numeric set.

override_warn_limit_string: Specify the new threshold value. This can be used only if the base column has warn_limit_string set.

override_crit_limit_string: Specify the new threshold value. This can be used only if the base column has crit_limit_string set.

override_warn_limit_date: Specify the new threshold value. This can be used only if the base column has warn_limit_date set.

override_crit_limit_date: Specify the new threshold value. This can be used only if the base column has crit_limit_date set.

comments: Describe the need for this override.

Notes:

  • Overrides are currently only supported for columns which use OPER_LT or OPER_GT operators.
  • Take care that the value_numeric, value_string or value_date (depending on the overload of this procedure) matches the data type of the informational_column specified in the gauge.
  • The warn_limit_numeric, warn_limit_string or warn_limit_date values must match the data type used in the gauge column. The same goes for the three critical limits.
procedure gauge_override_add dbid

gauge

column_name

informational_column

override_name

value_string

override_warn_limit_numeric

override_crit_limit_numeric

override_warn_limit_string

override_crit_limit_string

override_warn_limit_date

override_crit_limit_date

comments

number

varchar2

varchar2

varchar2

varchar2

varchar2

number

number

varchar2

varchar2

date

date

varchar2

An overload of gauge_override_add for informational_column string values instead of numeric values.
procedure gauge_override_add dbid

gauge

column_name

informational_column

override_name

value_date

override_warn_limit_numeric

override_crit_limit_numeric

override_warn_limit_string

override_crit_limit_string

override_warn_limit_date

override_crit_limit_date

comments

number

varchar2

varchar2

varchar2

varchar2

date

number

number

varchar2

varchar2

date

date

varchar2

An overload of gauge_override_add for informational_column date values instead of numeric values.
procedure gauge_override_remove
dbid

gauge

column_name

informational_column

override_name

number

varchar2

varchar2

varchar2

varchar2

Removes an override value.

dbid + gauge: Specify the gauge to remove the override from.

column_name: Specify the gauge column to remove the override from.

informational_column: Specify the informational column to remove the override from.

override_name: Specify the name of the override to remove.

procedure gauge_remove
dbid

name

number

varchar2

Removes a gauge.

dbid + name: Specify the gauge to remove.

procedure gauge_run
name

force

use_current_session

varchar2

boolean

boolean

Immediately runs the specified gauge job.

The job will not run if the gauge is disabled. Set the force parameter to true to override this.

By default the job will run in the user's current session. Set use_current_session to false to override this.

procedure gauge_reset_flag
dbid

guage

flag

number

varchar2

varchar2

Remove a flag from a gauge.

dbid + gauge: Specify the gauge to remove the flag from.

flag: Specify the name of a flag. Valid values for gauges are: DISABLE, AUTOSYNC, REPOSITORY_ONLY, TARGET_ONLY, LOGICAL_AND

procedure gauge_set_flag
dbid

gauge

flag

number

varchar2

varchar2

Add a flag to a gauge.

dbid + gauge: Specify the gauge to add the flag to.

flag: Specify the name of a flag. Valid values for gauges are: DISABLE, AUTOSYNC, REPOSITORY_ONLY, TARGET_ONLY, LOGICAL_AND

procedure mail_recipient_add
dbid

type

email_address

comments

number

varchar2

varchar2

varchar2

Adds a new email address to receive specific emails from zztat.

dbid: If specified, the given email address will only receive emails related to that database.

type: Specify WARNING, CRITICAL, REPORT or ALL to indicate which type of email to send to that address.

email_address: The email address to send emails to.

comments: Specify a comment indicating the purpose of this email, or indicate the owner or owning team.

procedure mail_recipient_remove
dbid

type

email_address

number

varchar2

varchar2

Remove an email address from zztat's list of mail recipients.

dbid: If specified, remove a database-specific email recipient.

type: Specify the type of recipient to remove.

email_address: The email address to remove.

procedure metric_add
dbid

name

snap_interval

snap_unit

replicate_interval

replicate_unit

part_interval

metric_table

query

comments

hints

flags

number

varchar2

number

varchar2

number

varchar2

varchar2

varchar2

clob

varchar2

varchar2

number

Adds a new metric to zztat.

dbid + name: A metric is uniquely identified by the dbid + name parameters. Specifying NULL or omitting the dbid will create a default metric, which can be executed on any database. This is the intended default - you should only create database-specific metrics if you have a specific need to override the default metric. Note that the metric name cannot exceed 12 characters.

snap_interval: For standard metrics, specify the interval at which to trigger the snapshot for this metric.

snap_unit: For standard metrics, specify the unit to apply the snap_interval to. Valid values are: SECOND,MINUTE,HOUR,DAY,MONTH,YEAR

replicate_interval: For standard metrics, specify the interval at which to trigger the replication of this metric.

replicate_unit: For standard metrics, specify the unit to apply the replicate_interval to. Valid values are: SECOND,MINUTE,HOUR,DAY,MONTH,YEAR

part_interval: Specify the soft-partition interval to use when archiving this metric. zztat automatically maintains the partition views in the repository. Choose one of: DAY, WEEK or MONTH. The default value is MONTH. To disable soft-partitioning, specify NONE.

metric_table: The table name the metric is populating with data. Do not change this unless you have a compelling reason to do so. Must always start with 'ZZ$'.

query: The metric query. The query must adhere to certain standards. For specifications on what types of queries are supported, see here.

comments: Specify a description of what the metric does.

hints: This field is provided to give you a means of altering the execution plan if it causes problems on certain databases. The intended use is for database-specific metrics. Hints are injected in the query as specified by the ##ZZHINT## substitution variable. For more information, see here.

flags: Specify a flag to alter the behavior of the metric. Use the constants provided in the zz$manage package.

procedure metric_copy
to_dbid

name

snap_interval

snap_unit

replicate_interval

replicate_unit

query

hints

flags

comments

number

varchar2

number

varchar2

number

varchar2

clob

varchar2

flags

varchar2

Create a database-specific metric. Uses the baseline metric as a source (where the DBID = -1 ).

to_dbid: Specify the database you want to create the specific metric for.

name: Identifies the metric you want to edit. This metric must exist as a default metric. You cannot copy another database-specific metric.

snap_interval: For standard metrics, specify the interval at which to trigger the snapshot for this metric.

snap_unit: For standard metrics, specify the unit to apply the snap_interval to. Valid values are: SECOND,MINUTE,HOUR,DAY,MONTH,YEAR

replicate_interval: For standard metrics, specify the interval at which to trigger the replication of this metric.

replicate_unit: For standard metrics, specify the unit to apply the replicate_interval to. Valid values are: SECOND,MINUTE,HOUR,DAY,MONTH,YEAR

query: The metric query. The query must adhere to certain standards. For specifications on what types of queries are supported, see here.

flags: Specify the flags to assign to the copy. Use the constants provided in the zz$manage package.

Notes:

  • Updating of scheduler jobs will be done automatically by zztat when this procedure is used.
  • Any parameters you omit, will retain their values from the original metric.
procedure metric_edit
dbid

name

snap_interval

snap_unit

replicate_interval

replicate_unit

query

cascade

number

varchar2

number

varchar2

number

varchar2

clob

boolean

Edit the attributes of a metric.

dbid + name: Identifies the metric you want to edit.

snap_interval: For standard metrics, specify the interval at which to trigger the snapshot for this metric.

snap_unit: For standard metrics, specify the unit to apply the snap_interval to. Valid values are: SECOND,MINUTE,HOUR,DAY,MONTH,YEAR

replicate_interval: For standard metrics, specify the interval at which to trigger the replication of this metric.

replicate_unit: For standard metrics, specify the unit to apply the replicate_interval to. Valid values are: SECOND,MINUTE,HOUR,DAY,MONTH,YEAR

query: The metric query. The query must adhere to certain standards. For specifications on what types of queries are supported, see here.

cascade: Only has an effect if you omit the DBID or specify -1 and set cascade to TRUE. The specified metric will be edited for all databases. If cascade is false, only the default metric will be edited. Cascade can't be set when editing a database-specific metric.

Notes:

  • Updating of scheduler jobs will be done automatically by zztat when this procedure is used.
  • Changes to metric queries are subject to the following restrictions:
    • The number of columns returned by the query cannot be changed
    • The data types of the columns returned by the query cannot be changed

If you require changes to be done that alter the structure of the data, you must remove and re-add the metric. Removing the metric will automatically cause the staging table on targets to be dropped.

procedure metric_refresh
Triggers an immediate metric refresh from the repository. Can only be used on a target database in PULL mode.
procedure metric_run
name

force

use_current_session

varchar2

boolean

boolean

Immediately runs the snapshot job of the specified metric.

The job will not run if the metric is disabled. Set the force parameter to true to override this.

By default the job will run in the user's current session. Set use_current_session to false to override this.

procedure metric_remove
dbid

name

number

varchar2

Removes a metric.

dbid + name: Identifies the metric you want to remove.

procedure metric_reset_flag
dbid

name

flag

number

varchar2

varchar2

Removes a flag from a metric.

dbid + name: Identifies the metric you want to edit.

flag: Specify the flag as a string identifier. For metrics, valid flags are: DISABLE, REPLICATE_ONLY, AUTOSYNC, REPOSITORY_ONLY, TARGET_ONLY, ON_DEMAND, ON_UPGRADE, TRUNC_ON_SNAP, SNAP_TWICE

procedure metric_set_flag
dbid

name

flag

number

varchar2

varchar2

Sets a flag for a metric.

dbid + name: Identifies the metric you want to edit.

flag: Specify the flag as a string identifier. For metrics, valid flags are: DISABLE, REPLICATE_ONLY, AUTOSYNC, REPOSITORY_ONLY, TARGET_ONLY, ON_DEMAND, ON_UPGRADE, TRUNC_ON_SNAP, SNAP_TWICE

procedure reaction_add
dbid

name

max_runs_per_interval

interval

description

flags

number

varchar2

number

interval_day_to_second

varchar2

number

Adds a new reaction.

dbid + name: A reaction is uniquely identified by the dbid and name parameters. Specifying NULL or omitting the dbid creates a default reaction that's eligible to run on any database. The reaction name cannot exceed 64 characters.

max_runs_per_interval: For throttled reactions - the maximum number of times this reaction can be fired during the specified interval.

interval: For throttled reactions - the duration of the interval to limit the number of executions to max_run_per_interval.

description: Enter a description to define what the reaction does.

flags: Specify a flag to alter the behavior of the reaction. Use the constants provided in the zz$manage package.

procedure reaction_chain_add
dbid

name

reactions

description

flags

number

varchar2

varchar2

varchar2

number

Adds a new reaction chain.

dbid + name: A reaction chain is uniquely identified by the dbid and name parameters. Specifying NULL or omitting the dbid creates a default reaction chain that's eligible to run on any database. The reaction chain name cannot exceed 64 characters.

reactions: Enter a comma-separated list of reactions to fire, in the order specified.

description: Enter a description to define what the chain's purpose is.

flags: Specify a flag to alter the behavior of the reaction chain. Use the constants provided in the zz$manage package.

procedure reaction_chain_remove
dbid

name

number

varchar2

Removes a reaction chain.

dbid + name: Specify the reaction chain to remove. This does not remove the reactions - but only the chain itself.

procedure reaction_config
dbid

parameter

value

number

varchar2

varchar2

Change the reaction configuration for a database.

dbid: Identify the database to change the configuration for.

parameter: Specify which parameter to alter.

value: Specify the new value for the parameter.

Notes:

procedure reaction_config_copy
to_dbid number Create a database-specific reaction configuration set by copying the default parameters and their values. Use the reaction_config procedure to customize the values after the copy is created.
procedure reaction_edit
dbid

name

max_runs_per_interval

interval

number

varchar2

number

interval_day_to_second

Change the attributes of a reaction.

dbid + name: Identify the reaction to edit.

max_runs_per_interval: For throttled reactions - the maximum number of times this reaction can be fired during the specified interval.

interval: For throttled reactions - the duration of the interval to limit the number of executions to max_run_per_interval.

procedure reaction_remove
dbid

name

number

varchar2

Remove a reaction.

dbid + name: Specify the reaction to remove. Note that the reaction cannot be part of an existing reaction chain. The reaction chain must be removed prior to removing the reaction.

procedure validate_reaction
name varchar2 Validate a reaction and enable it if validation succeeds.

TBD

Exceptions

The following table lists the errors that zz$manage can raise.

Error Number Description
20600 ZZTAT Internal error

This normally shouldn't happen and indicates a problem with zztat's code or the data. Please do the following:

  • Review the contents in zz$log around the time of the error
  • Run the zzdiag.sql script and review the output for any problems
  • Contact zztat support
20800 Duplicate metric name. Please choose another.

The metric you attempted to create or copy already exists with the same database DBID. Review the output of zz_report_metric.sql and adjust your input as necessary, or delete the existing metric you intend to replace.

20801 Metric name not found. Please correct and re-try.

The metric you attempted to edit, remove or copy was not found with the specified DBID. Review the output of zz_report_metric.sql and adjust your input as necessary.

20803 Bad unit. Please use one of second,minute,hour,day,month,year.

You attempted to create or edit a metric and specified an invalid value for the interval's unit. Please use one of the suggested units. Units are not case-sensitive and can be entered in upper-, lower-, or mixed-case.

20804 These jobs can only run on a target. Do not attempt to run them on the repository

You attempted to start a snapshot, replicate, gauge, or reaction that was flagged to be target-only on the repository. Run the process on the target database or alter the object's attributes to remove the target-only flag.

Note that certain jobs - for example snapshots - can never run on the repository.

20807 Bad partition interval. Please use one of DAY,WEEK,MONTH.

You attempted to create or edit a metric and specified an invalid partitioning interval. zztat's partition views functionality supports daily, weekly and monthly partitioning. Set to NONE to disable partitioning.

20819 Duplicate gauge name. Please see the log for details.

The gauge you attempted to create or copy already exists with the same database DBID. Review the output of zz_report_gauge.sql and adjust your input as necessary, or delete the existing gauge you intend to replace.

20820 Invalid column definition. Please see the log for details.

The gauge column you attempted to create or edit used incompatible or invalid settings. Use zz_report_error.sql to view the details of where the problem is.

Common scenarios that raise this error are:

  • A warning or critical threshold was defined, but no corresponding warning or critical message was specified.
  • Neither a warning or critical threshold was specified when adding the column
20821 Invalid ignore rule. Please see the log for details.

The gauge ignore you attempted to create or edit used invalid settings. Use zz_report_error.sql to view the details of where the problem is.

Common scenarios that raise this error are:

  • The specified column to add an ignore value to does not exist on the specified gauge
  • The specified informational column to add an ignore value to does not exist on the specified gauge
20822 Invalid rule specification. Please see the log for details.

When removing a gauge ignore rule, the specified gauge column was not found.

Review the output of zz_report_gauge.sql and adjust your input as necessary.

20823 Rule removal encountered unexpected result. Please see the log for details.

zztat failed to remove the gauge ignore rule due to an unexpected mismatch. Review the output of zz_report_gauge.sql and adjust your input as necessary.

If all else fails, please contact zztat support.

20824 Invalid override specification. Please see the log for details.

This can occur when an invalid override rule is added to a gauge column. Common scenarios include:

  • A warning threshold override was added for a column that does not have a warning threshold defined
  • A critical threshold override was added for a column that does not have a critical threshold defined
  • The specified column to add an override for was not found.

Review the output of zz_report_gauge.sql and adjust your input as necessary.

20825 Override removal encountered unexpected result. Please see the log for details.

zztat failed to remove the gauge ignore rule due to an unexpected mismatch. Review the output of zz_report_gauge.sql and adjust your input as necessary.

If all else fails, please contact zztat support.

20826 Invalid metric flag. Choose one of DISABLE, REPLICATE_ONLY, AUTOSYNC, ON_DEMAND.

You specified an invalid flag in metric_set_flag or metric_reset_flag. Please note that these procedures use plain text identifiers to specify the flags.

20827 Invalid gauge flag. Choose one of DISABLE, AUTOSYNC, REPO_ONLY, TARGET_ONLY

You specified an invalid flag in gauge_set_flag or gauge_reset_flag. Please note that these procedures use plain text identifiers to specify the flags.

20828 Cannot enable gauge without the metric also being enabled. Please see the log for details.

You attempted to enable a disabled gauge but the metric the gauge depends on is disabled. Enable the metric before enabling the gauge.

20829 Cannot toggle auto-sync if the metric does not have it enabled. Please see the log for details.

You attempted to switch a gauge to the auto-sync mode but the metric the gauge depends on is a standard metric. Switch the metric to auto-sync mode before switching the gauge.

Alternatively, use the CASCADE option when switching the metric to auto-sync mode.

20830 Invalid column operator. Please see the log for details.

You attempted to create a gauge column with an invalid column operator. Specify a valid operator. See the documentation on constants in the zz$manage package.

20831 Unable to determine metric for gauge. Please see the log for details.

When trying to set a flag on a gauge, the metric the gauge references was not found. This error should not occur anymore. Please contact zztat support.

20834 This gauge column does not support overrides. Gauge column operator must be "less than" or "greater than" to support overrides.

You attempted to add an override on a gauge column that does not support overrides. Only gauge columns with the less than or greater than operators currently support overrides.

20836 Invalid parameter. Please choose one of ALERT_PREFIX,LOG_TABLE,LOG_DIRECTORY,LOG_FILE,WARN_EMAIL,CRIT_EMAIL,DATAFILE_ADD_LOCATION.

You attempted to define a reaction configuration that does not exist. Use one of the values specified in the error message.