Rule Definition Record Clause

RULE <rule-name> {PRIMARY | SECONDARY} [DISABLED]

	[<initialization>]

	RECORD <rec-id>
	[WHERE <where-clause>]
	[REFRESH <n> {SECONDS | MINUTES | HOURS | DAYS}]
	[NODE {* | (<node>, <node> ...)}]
	[NAME {* | (<assoc-name>, ...)}]
	[PARAM (<param-name>, ...)]
	[SORT {DESCENDING | ASCENDING} <field> [LIMIT <n>]]
	[AFTER <n> OCCURRENCES]
	[BETWEEN {<hh:mm> <hh:mm> | <hhmm> <hhmm>}]
	[EVERY <n> {SECONDS | MINUTES | HOURS | DAYS}]
	[RETRY [<n> TIMES] WHEN_NO_MATCH]
	[NOTEXIST]
	[ACK_REQUIRED]
	[CLOSE_WHEN_OFF]
	
	[<action-clause>]
	[<action-clause>]
	...

END_RULE

Syntax

RECORDName of the record that this rule uses for analysis. <rec-id> is the short name of the record e.g. CPU, PHYSVOL, etc.
WHERE

Specifies the triggering condition for the Analyst rule.  See the Where Clauses section for further details.

The following defaults and restrictions apply to Analyst Where Clauses:

  • If no Where Clause is specified, WHERE ALL will be the default. This allows all entities of the RECORD type being used to be passed to the Analyst for analysis.

  • In addition to field names and literals, Analyst Where Clauses can also include references to variables. In PRIMARY rules, global variables are the only variable type that can be accessed. In SECONDARY rules, global variables, local variables, system variables and field variables are all accessible in a Where Clause.

  • Except for field variables there is no need to specify the record name for a field. The record name of the current rule is the default, for example, the following Where Clauses are the same:

RULE RULE-1 PRIMARY
	RECORD CPU
	WHERE CPU.CPUNO=1
	WHERE CPUNO=1

In contrast, the following example is incorrect:

RULE RULE-1 PRIMARY
	RECORD CPU
	WHERE @CPU.CPUNO=1 <------- Incorrect


The @ makes @CPU.CPUNO a field variable reference. This means that the current known value of CPU.CPUNO will be substituted into the Where Clause prior to activating it. This is not valid for a Primary rule (since there is by definition, no known value for that field at the time we are looking for a matching record), and even in a secondary rule it is unlikely to produce the desired result.

In a secondary rule, it is likely that field variables will be used, but only to substitute known values from a parent rule. For example:

RULE GetBusyJobsForCpu SECONDARY
	RECORD JOBS
	WHERE JOBS.CPUNO = @CPU.CPUNO

When comparing timestamps in <where-clause> or <action-where-clause>, there are some special considerations. Especially when one of the timestamps has been stored in a global or local variable. For more information, see Use of Timestamps in Analyst Where Clauses.

REFRESHSpecifies the refresh rate or interval at which data will be delivered to the rule from the collector. You can use any refresh interval from 10 seconds to 32000 days. The default is 60 seconds. In a Secondary rule, the rule will not process data until 20 seconds have passed from the time the rule was activated; this is to ensure that the data being received is for the newly reconfigured view. This extra delay will be more evident when specifying a short refresh interval in the Secondary rule.
NODE

Defines the nodes from which the record should be gathered. <node> can be either a node name or a Node Group name. Node names are always preceded with a \ character. Node group names should be preceded with a #. Prognosis must be running on each of the specified nodes. or Secondary rules, it is only valid to specify a single node in the NODE clause. If the NODE clause is omitted from a Primary rule, data will be collected from the local node only. If the NODE clause is omitted from a Secondary rule, data will be collected from the node that the data was received from in the calling rule. As shown in the example below, there must be a space after the opening parenthesis and before the closing parenthesis.

RULE CpuBusy PRIMARY
	RECORD CPU
	WHERE BUSY > 90
	NODE ( \PROD1, \PROD2, #NodeGroup1 )
NAME

Corresponds to the Associate Names tab in Windows Client Displays. Only available for selected records, it specifies a comma-separated list of names that act as pre-filters to limit the number of record instances monitored. Records implementing pre-filtering via names, include AVMON, SUBVOL and USER. <assoc-name> can be either a literal or a field variable. In Primary rules, only literals are allowed. Field variables should be prefixed with an @. String literals should NOT be surrounded by quotes.

For example:

RULE RULE-7 SECONDARY
	RECORD SUBVOL
	WHERE ALL
	NAME ( @VOLUME.VOLUME, $DATA01 )
PARAMSpecifies a comma separated list of parameters that limit the amount of data returned for records that support Subsystem parameters. This works the same way as the PARAM keyword used in Where Clause processing for Displays, Databases Thresholds etc. <param-name> can be either a literal string or a field variable. Field variables should be prefixed with an @. String literals should NOT be surrounded by quotes.
SORT

Causes any data that satisfies the subsequent Where Clause in the rule to be sorted by the value of a particular field in that record. This gives some control over the Analyst's order of processing exception data.

Valid sort values are ascending or descending.

Omitting the SORT keyword leaves the data in the order that the collector sent it. You can also use the limit keyword to limit the number of entities processed by the rule. For example, if you had a Where Clause that filtered the JOBS record on jobs busier than 5% (where jobs.busy > 5), and there were 10 jobs busier than 5%, using SORT DESCENDING BUSY LIMIT 5 will only pass the 5 busiest jobs through the rest of the rule.

AFTERSpecifies that the rule should only be triggered after the set number of consecutive occurrences of the same symptom for the same record instance have occurred. This is only valid for Primary rules. The occurrence count is reset when the rule actually triggers or when an interval of data is received where the condition is no longer met. The default is 1, meaning that the rule will trigger on the first occurrence.
BETWEENSpecifies that the rule should only trigger if it occurs between the hours set. This is based on a 24-hour clock and is only valid for Primary rules. The hour interval can wrap over midnight, for example 23:00 to 02:00. The default is all day.
EVERY

After an instance of a Primary rule is triggered (because the source has been found), this specifies the period of time to wait before the same record instance will trigger again. This is only valid for Primary rules.

For example, if the following rule triggers at 11:00 for disk $DATA01 and the disk remains full, the rule will not trigger again for $DATA01 until at least 23:00.

RULE DiskFull PRIMARY
	RECORD VOLUME
	WHERE DISCUSE% > 90
	EVERY 12 HOURS
RETRYSpecifies that the Secondary rule should continue to wait for data for up to <n> refresh intervals if the Where Clause is not satisfied. If the optional clause, <n> TIMES is omitted, the current rule will wait until the Where Clause is satisfied. This is only valid in Secondary rules. The default is 3 if the RETRY clause is omitted entirely.
NOTEXIST

Reverses the meaning of the Where Clause within an Analyst rule. For any condition defined in the Where Clause this will cause the Analyst to log a message if that condition is NOT met.

For example:  WHERE NTJOBS.NAME = "notepad"
With 'Not Exist' selected this condition will trigger when there are no notepads running on the machine.

In NOTEXIST rules, the use of field variables referring to the local record is not permitted. For instance, for the above NTJOBS example, references to @ntjobs.name anywhere in the <action-clause> would be rejected.
ACK_REQUIREDThis optional statement is used to enable the 'Operator Acknowledgement' function. This means that when the Analyst rule triggers an alert the operator will need to manually acknowledge that alert through one of the Alerts Displays in the Windows Client. To trigger the Operator Acknowledgement on a PRIMARY rule it is necessary to include an ACTION clause that will log to either the PROBLEM or PROBLEM_SUMMARY record. The Operator Acknowledgement feature can also be added to SECONDARY rules provided that an ACK_REQUIRED statement has already been applied to the PRIMARY rule and that the SECONDARY rule contains an ACTION clause to log to either the PROBLEM or PROBSUM records. Please refer to the Operator Acknowledgement for Thresholds in the Thresholds section for further details about this functionality.
CLOSE_WHEN_OFFCauses the Analyst rule instance to stay open until the triggering condition is no longer true. Normally an Analyst rule instance closes when it reaches the end of all its ACTION clauses and any non-WAITed Secondary rules that it started are closed. Mostly, the CLOSE_WHEN_OFF option works on top of this regular behavior and additionally holds the Analyst rule open until the triggering data instance no longer matches the Where Clause. The exception to this is that if an Analyst rule is waiting for an OPER_ACK command to be acknowledged when the off event is received the command will be cancelled and the rule instance will be closed immediately.

Provide feedback on this article