Upload
others
View
0
Download
0
Embed Size (px)
Citation preview
Geneos Rules, Actions, and AlertsTechnical Reference
Functional Area: Geneos Rules, Actions, and Alerts
Geneos Release: v4.6.0.
Document Version: v1.0.0
Date Published: 16 March 2018
Copyright 2018. ITRSGroup Ltd. All rights reserved.
Information in this document is subject to change without notice. The software described in this document is furnished under a license agreement
or nondisclosure agreement. The softwaremaybe used or copied only in accordance with the termsof those agreements. No part of this
publicationmaybe reproduced, stored in a retrieval system, or transmitted in any form or anymeanselectronic or mechanical, including
photocopying and recording for anypurpose other than the purchaser's personal use without the written permission of ITRSGroup Ltd.
ITRSGroup Ltd
6th Floor, The Bonhill Building, 15 Bonhill Street,
London, EC2A4DN, UK
t: +44 (0)20 7638 6700
f: +44 (0)20 7256 5760
Table of Contents
Geneos Gateway Core - Rules, Actions And Alerts 16
Rules 16
Introduction 16
Rule Code 16
Data Types 17
String 17
Integer 17
Double 17
Boolean 17
Null 18
Severity 18
Conversion Between Types 18
Properties 19
Data Items And Paths 22
Other Live System Data 22
Variables 23
Variable Active Time 23
Target Names 24
Operators 25
Comparison 25
Logic 26
Arithmetic 26
Order Of Precedence 27
Functions 28
Control Statements 28
If/else 28
Updates And Actions 30
Updates 30
Actions 30
Action Throttle 30
User Data 31
ValuesOf The Variables 31
Data Item PropertiesSuch AsValue, Active, Snoozed Etc. 32
ASelection Of PropertiesFromSeveralData ItemsBasedOn An Xpath. 32
Whether We AreWithin AParticular Active Time. 32
The ValueOfManaged EntityAttributes 32
Current TimeseriesValues 33
Delay 33
Rules 34
Targets 34
Priority 35
ActiveTime 35
Rule Evaluation 35
Single Property Updates 36
Transactions 36
Applying Updates 36
Re-Evaluating Rules 37
Disabling Rules At Start Up 38
Rule Groups 38
Rule Defaults 38
Transaction Defaults 39
Nested Rule Groups 40
Common Pitfalls 40
If Without Else 40
Overlapping Defaults 40
Configuration 41
Rules 41
Rules>RuleGroup 41
Rules>RuleGroup >Name 41
Rules>RuleGroup >Default 41
Rules>RuleGroup >Default >Name 41
Rules>RuleGroup >Default >Rule 41
Rules>RuleGroup >Default >Rule >Contexts 41
Rules>RuleGroup >Default >Rule >PriorityGroup 42
Rules>RuleGroup >Default >Rule >ActiveTime 42
Rules>RuleGroup >Default > Transaction 42
Rules>RuleGroup >Default > Transaction >Match 42
Rules>RuleGroup >Default > Transaction >Data 42
Rules>Rule 42
Rules>Rule >Name 42
Rules>Rule >Contexts 42
Rules>Rule >Targets 43
Rules>Rule >PriorityGroup 43
Rules>Rule >Priority 43
Rules>Rule >ActiveTime 43
Rules>Rule >ActiveStateAffectsCell 43
Rules>Rule >StopFurtherEvaluation 43
Rules>Rule >PathVariables 43
Rules>Rule >PathAliases 44
Rules>Rule >EvaluateOnDataviewSample 44
Rules>Rule >DisableRateWarning 45
Rules>Rule >Block 45
Rules>StartupDelay 45
Rules>StartupDelay> Interval 45
Functions 45
NumericFunctions 45
Abs 45
Sqrt 46
Pow 46
String Functions 46
StringBefore 46
StringAfter 47
ToUpper 47
ToLower 47
Concat 48
Replace 48
InList 48
Substr 49
Trim 49
Ltrim 49
Rtrim 50
Strpos 50
Strrpos 50
RegMatch 50
Time Functions 51
Now 51
StartOfMinute 51
StartOfHour 51
StartOfDay 52
StartOfMonth 52
StartOfYear 52
ParseDate 52
PrintDate 53
Compute Engine 54
Introduction 54
Adding To Existing Dataviews 55
Creating New Views 55
Populating Cells With Data 56
Extended Rule Syntax 57
Using Functions With Ranges Of Items 57
Using Historic Time-based Functions 58
Local Variables 58
Tips 59
Conditions 59
Setting Other Properties In Addition 59
Feedback 60
Configuration 60
History Periods 60
Rules>HistoryPeriod 60
Rules>HistoryPeriod >CalculationPeriod 61
Rules>HistoryPeriod >CalculationPeriod >RollingPeriod 61
Rules>HistoryPeriod >CalculationPeriod >RollingPeriod >Measure 61
Rules>HistoryPeriod >CalculationPeriod >RollingPeriod > Length 61
Rules>HistoryPeriod >CalculationPeriod >RollingPeriod >MaxValues 61
Rules>HistoryPeriod >CalculationPeriod >FixedPeriod 62
Rules>HistoryPeriod >CalculationPeriod >FixedPeriod > Length 62
Rules>HistoryPeriod >CalculationPeriod >FixedPeriod >Start 62
Rules>HistoryPeriod >CalculationPeriod >FixedPeriod >Start >Month 62
Rules>HistoryPeriod >CalculationPeriod >FixedPeriod >Start >DayOfMonth 63
Rules>HistoryPeriod >CalculationPeriod >FixedPeriod >Start >DayOfWeek 63
Rules>HistoryPeriod >CalculationPeriod >FixedPeriod >Start >WeekDay 63
Rules>HistoryPeriod >CalculationPeriod >FixedPeriod >Start >Hour 63
Rules>HistoryPeriod >CalculationPeriod >FixedPeriod >Start >Minute 63
Rules>HistoryPeriod >CalculationPeriod >FixedPeriod >Start >Second 63
Rules>HistoryPeriod >ActiveTime 63
Functions 64
String Functions 64
Format 64
Statistical Functions 64
Maximum 65
Minimum 65
Average 65
Total 65
Count 66
StandardDeviation 66
Duration-Weighted Statistical Functions 66
DurationWeightedAverage 67
DurationWeightedTotal 67
DurationWeightedStandardDeviation 68
Handling Of Non-numericValues 69
Other Functions 69
Rate 69
First 70
Persistence 72
Persistence Configuration 72
Persistence 72
Persistence > WritePeriod 72
Persistence > RewritePeriod 72
Actions 72
Introduction 72
Operation 73
Action Configuration 73
Basic Configuration 73
Script Actions 73
User Assignment Script Actions 76
Shared LibraryActions 77
Command Actions 78
Effect Actions 80
Advanced Features 80
Repeating Actions 80
Escalating Actions 81
Restricted Actions 82
Active Times 83
Configuration Settings 84
Grouping Settings 84
Actions 84
Actions>ActionGroup 84
Actions>ActionGroup >Name 84
Common Action Settings 84
Actions>Action 84
Actions>Action >Name 85
Actions>Action >EscalationAction 85
Actions>Action >EscalationInterval 85
Actions>Action >RepeatInterval 85
Actions>Action >ActiveTime 85
Actions>Action >QueueUntilActive 85
Actions>Action >Restrictions 85
Actions>Action >Restrictions>Snoozing 85
Actions>Action >Restrictions> Inactivity 86
Actions>Action >Restrictions>QueueUntilUnrestricted 86
Actions>Action >Restrictions>Throttle 86
Script Action Settings 86
Actions>Action >Script 86
Actions>Action >Script >ExeFile 86
Actions>Action >Script >Arguments 87
Actions>Action >Script >CommandLine 87
Actions>Action >Script >RunLocation 87
Actions>Action >Script >Probe 87
Shared LibraryAction Settings 87
Actions>Action >SharedLibrary 87
Actions>Action >SharedLibrary> LibraryFile 87
Actions>Action >SharedLibrary>FunctionName 87
Actions>Action >SharedLibrary>RunThreaded 88
Actions>Action >SharedLibrary>StaticParameters 88
Actions>Action >SharedLibrary>StaticParameters>StaticParameter >Name 88
Actions>Action >SharedLibrary>StaticParameters>StaticParameter >Value 88
Command Action Settings 88
Actions>Action >Command 88
Actions>Action >Command >Ref 88
Actions>Action >Command >Args 88
Actions>Action >Command >Args>Arg 88
Actions>Action >Command >Args>Arg >Target 89
Actions>Action >Command >Args>Arg >Static 89
Actions>Action >Command >Args>Arg >Text 89
Actions>Action >Command >Args>Arg >StdAES 89
Actions>Action >Command >Args>Arg >Parameter 89
Effect Action Settings 90
Actions>Action >Effect 90
Actions>Action >Effect >Ref 90
Advanced Action Settings 90
Actions>FireOnComponentStartup 90
Actions>FireOnConfigurationChange 90
Actions>FireOnCreateWithOkSeverity 91
Actions>EscalateIfFiringSuppressed 91
Action Throttling 91
Basic Configuration 92
Actions>Throttle >Name 93
Actions>Throttle >NoOfActions 93
Actions>Throttle >Per 93
Actions>Throttle > Interval 93
Configuring Grouping 93
Examples 93
Throttling Per Dataview. 94
Throttling SeparatelyFor One SpecificPlugin. 94
Throttling ByRow For One SpecificPlugin. 94
Throttle Each Data Item Separately 94
Throttling BySet Of Plugin Types. 95
Throttling ByFkmDataviewsPer Filename. 95
Valid Grouping Paths 95
Actions>Throttle >Grouping 95
Actions>Throttle >Grouping >Paths 96
Actions>Throttle >Grouping >Paths>Path 96
Summarising Throttling 96
Actions>Throttle >Summary 96
Actions>Throttle >Summary>Send 96
Actions>Throttle >Summary> Interval 96
Actions>Throttle >Summary>Strategy 96
Actions>Throttle >Summary>Action 96
Action Examples 96
Script 96
Multi Line Variables In Actions 97
Windows 97
Solaris 98
Linux 98
Shared Library 99
Libemail 100
Overview 100
Configuration 100
Message Formats 103
Default _FORMAT 103
Default _ALERT_FORMAT 103
Default _CLEAR_FORMAT 104
Default _SUSPEND_FORMAT 104
Default _RESUME_FORMAT 105
Default _SUMMARY_FORMAT 105
Alerting 106
Overview 106
Hierarchies 106
Notifications 107
Distribution Lists 107
Effects 107
VariablesPassed To Effect 107
Alert Information 107
Data Item Information 108
Distribution Lists 109
Libemail 110
Repeating Notifications 110
Escalation 111
Clears 111
Severity Transition Example 1 111
Severity Transition Example 2 111
Suspended Alerts 112
Example 1: Repeating 112
Example 2: Escalations 113
Example 3: Resetting Escalations 113
Example 4: Clears 113
Example 5: Cells Changing State While Alert Is Suspended 114
Example 6: Intervals That Span Entire Suspended Period 114
Active Times 114
Restricted Alerts 114
Alert Throttling 115
Summaries 115
SummaryEffect 115
Alert Information 115
DataItem Information 116
Throttling Information 116
Distribution Lists 117
Grouping 117
Examples 118
Throttling Per Dataview. 118
Throttling SeparatelyFor One SpecificPlugin. 118
Throttling ByRow For One SpecificPlugin. 118
Throttle Each Data Item Separately 118
Throttling BySet Of Plugin Types. 119
Throttling ByFkmDataviewsPer Filename. 119
Valid Grouping Paths 119
Alert Commands 120
Show Alerts 120
Evaluate Alerts 120
Configuration 121
Alerting > Hierarchy 121
Alerting > HierarchyGroup 121
Alerting > HierarchyGroup > Name 121
Alerting > Hierarchy > Name 121
Alerting > Hierarchy > Priority 121
Alerting > Hierarchy > Levels 121
Alerting > Hierarchy > Levels > Level > Match 122
Alerting > Hierarchy > Levels > Level > Match > ManagedEntityAttribute 122
Alerting > Hierarchy > Levels > Level > Match > ManagedEntityName 122
Alerting > Hierarchy > Levels > Level > Match > RowName 122
Alerting > Hierarchy > Levels > Level > Match > ColumnName 122
Alerting > Hierarchy > Levels > Level > Match > HeadlineName 122
Alerting > Hierarchy > Levels > Level > Match > DataviewName 122
Alerting > Hierarchy > Levels > Level > Match > SamplerName 122
Alerting > Hierarchy > Levels > Level > Match > SamplerType 122
Alerting > Hierarchy > Levels > Level > Match > SamplerGroup 122
Alerting > Hierarchy > Levels > Level > Match > PluginName 122
Alerting > Hierarchy > Alert 123
Alerting > Hierarchy > Alert > Name 123
Alerting > Hierarchy > Alert > Alert 123
Alerting > HierarchyProcessing 123
Alerting > HierarchyProcessing > ProcessAll 123
Alerting > HierarchyProcessing > StopWhenMatched 123
Alerting > Hierarchy > ActiveTime 123
Alerting > Hierarchy > Restrictions > Snoozing 123
Alerting > Hierarchy > Restrictions > Inactivity 124
Alerting > FireOnComponentStartup 124
Alerting > FireOnConfigurationChange 124
Alerting > Hierarchy > Throttle 124
Alerting > Hierarchy > Alert > Warning 125
Alerting > Hierarchy > Alert > Warning > Level 125
Alerting > Hierarchy > Alert > Warning > Level > EscalationInterval 125
Alerting > Hierarchy > Alert > Warning > Level > Notification 125
Alerting > Hierarchy > Alert > Warning > Level > Notification > Clear 125
Alerting > Hierarchy > Alert > Warning > Level > Notification > Repeat 125
Alerting > Hierarchy > Alert > Warning > Level > Notification > Repeat > Interval 125
Alerting > Hierarchy > Alert > Warning > Level > Notification > Repeat > Behaviour 126
Alerting > Hierarchy > Alert > Warning > AlwaysNotify 126
Alerting > Hierarchy > Alert > Critical 126
Alerting > Hierarchy > Alert > Critical > Level 126
Alerting > Hierarchy > Alert > Critical > Level > EscalationInterval 126
Alerting > Hierarchy > Alert > Critical > Level > Notification 126
Alerting > Hierarchy > Alert > Critical > Level > Notification > Clear 126
Alerting > Hierarchy > Alert > Critical > Level > Notification > Repeat 127
Alerting > Hierarchy > Alert > Critical > Level > Notification > Repeat > Interval 127
Alerting > Hierarchy > Alert > Critical > Level > Notification > Repeat > Behaviour 127
Alerting > Hierarchy > Alert > Critical > AlwaysNotify 127
Alerting > Hierarchy > Alert > Warning > Level > Notification > Effect 127
Alerting > Hierarchy > Alert > Critical > Level > Notification > Effect 127
Alerting > Hierarchy > Alert > Warning > Level > Notification > User 127
Alerting > Hierarchy > Alert > Warning > Level > Notification > User > User 127
Alerting > Hierarchy > Alert > Warning > Level > Notification > User > InfoType 128
Alerting > Hierarchy > Alert > Warning > Level > Notification > User > List 128
Alerting > Hierarchy > Alert > Warning > Level > Notification > Group 128
Alerting > Hierarchy > Alert > Warning > Level > Notification > Role 128
Alerting > Hierarchy > Alert > Warning > Level > Notification > Role > Role 128
Alerting > Hierarchy > Alert > Warning > Level > Notification > Role > InfoType 128
Alerting > Hierarchy > Alert > Warning > Level > Notification > Role > List 129
Alerting > Hierarchy > Alert > Warning > Level > Notification > Role > Include 129
Alerting > Hierarchy > Alert > Critical > Level > Notification > User 129
Alerting > Hierarchy > Alert > Critical > Level > Notification > User > User 129
Alerting > Hierarchy > Alert > Critical > Level > Notification > User > InfoType 129
Alerting > Hierarchy > Alert > Critical > Level > Notification > User > List 130
Alerting > Hierarchy > Alert > Critical > Level > Notification > Group 130
Alerting > Hierarchy > Alert > Critical > Level > Notification > Role 130
Alerting > Hierarchy > Alert > Critical > Level > Notification > Role > Role 130
Alerting > Hierarchy > Alert > Critical > Level > Notification > Role > InfoType 130
Alerting > Hierarchy > Alert > Critical > Level > Notification > Role > List 130
Alerting > Hierarchy > Alert > Critical > Level > Notification > Role > Include 130
Alerting > Hierarchy > Alert > Throttle 131
Alerting > Throttle 131
Alerting > Throttle > Name 131
Alerting > Throttle > NoOfAlerts 131
Alerting > Throttle > Per 131
Alerting > Throttle > Interval 131
Alerting > Throttle > Grouping 131
Alerting > Throttle > Grouping > Paths 132
Alerting > Throttle > Grouping > Paths > Path 132
Alerting > Throttle > Summary 132
Alerting > Throttle > Summary > Send 132
Alerting > Throttle > Summary > Interval 132
Alerting > Throttle > Summary > Strategy 132
Alerting > Throttle > Summary > Effect 132
Effects 133
Introduction 133
Operation 133
Effect Configuration 133
Basic Configuration 133
Script Effects 133
Shared Library 134
Command Effects 134
Configuration Settings 135
Common Effect Settings 135
Effects >Effect 136
Effects >Effect >Name 136
Script Effect Settings 136
Effects >Effect >Script 136
Effects >Effect >Script >ExeFile 136
Effects >Effect >Script >Arguments 136
Effects >Effect >Script >RunLocation 136
Effects >Effect >Script >Probe 136
Shared LibraryEffect Settings 136
Effects >Effect >SharedLibrary 137
Effects >Effect >SharedLibrary> LibraryFile 137
Effects >Effect >SharedLibrary>FunctionName 137
Effects >Effect >SharedLibrary>RunThreaded 137
Effects >Effect >SharedLibrary>StaticParameters 137
Effects >Effect >SharedLibrary>StaticParameters>StaticParameter >Name 137
Effects >Effect >SharedLibrary>StaticParameters>StaticParameter >Value 137
Command Effect Settings 137
Effects >Effect >Command 137
Effects >Effect >Command >Ref 138
Effects >Effect >Command >Args 138
Effects >Effect >Command >Args>Arg 138
Effects >Effect >Command >Args>Arg >Target 138
Effects >Effect >Command >Args>Arg >Static 138
Effects >Effect >Command >Args>Arg >Text 138
Effects >Effect >Command >Args>Arg >Parameter 139
Annotations 139
Conditional Text In Email Templates 139
Optional Environment Settings For Executable Actions 140
Annotations > Annotation > Name 140
Annotations > Annotation > Key 140
Annotations > Annotation > Value 140
Annotations > Annotation > Targets 140
Annotations > Annotation > Targets > Targets 141
Geneos Gateway Core - Rules, Actions andAlerts
Rules
IntroductionRules are a key part of the Geneos monitoring system. They allow run-time information to be updated andactions to be fired in response to specific gateway events. Typically the updates will apply to the severityof cells, reflected in the ActiveConsole by red, amber and green cell backgrounds.
The rules top-level section contains a number of named rule groups, which can be nested. These in turncontain a number of named rules. The rule groups, apart from grouping the rules, can provide defaults toapply to all the rules they contain. If no defaults are required then rules may also be placed directly into therules top-level section.
Rules can vary in complexity. A 'Show Rules' command can be run by right clicking on any cell, or anyitem in the directory (Gateway, Probes, Managed Entities etc.). This will show the rules that have beendefined for that item in the order that the gateway will execute them.
The rule code - the heart of a rule - is described first. This is followed by a description of how to apply therule to items in the system.
Additional functionality can be used with Rules that is not part of the basic Gateway operation. This isdescribed in the Compute Engine section.
Rule CodeHere is an example of a rule that might be set on the CPU utilisation of a host.
if value > 90 thenseverity criticalelseif value > 70 thenseverity warningelseseverity okendif
The following sections describe how to construct a rule.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 16 of 141
Data TypesThere are a number of primitive data types that can be used with the rules. These are string, integer,double (floating point/decimal), Boolean and null. Severity can also be used.
StringStrings represent textual items. When they are being used in rules, they must always be enclosed indouble quotes:
"the quick brown fox"
If you need to use double quotes inside a string then they must be escaped with a backslash. To use aliteral backslash it must be escaped with a second backslash. Forward slashes do not need escaping:
"he said \"I like foxes\" and \"I like cats\"""C:\\Program Files\\ActiveConsole""/usr/local/geneos/gateway"
IntegerIntegers are whole numbers:
0234-45
DoubleDoubles are floating point numbers - numbers that have a decimal point:
0.115.187623.42
BooleanBooleans are logical true/false values:
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 17 of 141
truefalse
NullNull is nothing:
null
SeverityLiterals can be used to indicate the severities an item can have:
undefinedokwarningcritical
Note: Severities are simply aliases for readability, and internally are treated the same asintegers. The values are: undefined 0, ok 1, warning 2 and critical 3. This allows rules such as
if severity > ok then ...
Conversion between typesData types will automatically be converted between types as necessary. The following table shows howthe conversion takes place:
To String To Integer To Double To Boolean
From String "10" => 10"10.3" => 10"10 x" => 10"-10" => -10"x 3" => 0"x" => 0
"10.5" => 10.5"74" => 74.0"-1.3e3" => -1.3e3"10.3 x" => 10.3".45" => 0.45"x" => 0.0
"" => false"0" => false"x" => true
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 18 of 141
To String To Integer To Double To Boolean
From Integer 1 => "1"-1 => "-1"
1 => 1.0-1 => -1.0
0 => falsex => true-x => true
From Double 3.2 => "3.2"1.0 => "1"-5.0 => "-5"-5.1 => "-5.1"
5.1 => 55.9 => 5-5.1 => -5-5.9 => -5
0.0 => falsex.x => true-x.x => true
From Boolean true => "1"false => ""
true => 1false => 0
true => 1.0false => 0.0
From null null => "" null => 0 null => 0.0 null => false
Where x indicates any other value
Note: Nothing will ever convert to a null - null will always be converted to the relevant datatype during comparisons.
PropertiesIt is possible to query the properties of the item that the rule is set on.
if value > 10 then...if severity = critical then...if attribute "LOCATION" = "London" then...
The following properties are available:
Property Target Description
value Cells Returns the current value of the cell(Any)
severity DataItem Returns the severity of the DataItem(Severity)
active Cells Returns the active status of the cell(Boolean)
snoozed Data-items Returns the snooze state of theDataItem (Boolean)
state "userAssigned" Data-items Returns the userAssigned state ofthe DataItem (Boolean)
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 19 of 141
Property Target Description
attribute "<name>" Managed Entities Replace <name> with the name ofthe managed entity attribute youwish to query. e.g. attribute"LOCATION". If the managed entityhas this attribute it's value isreturned otherwise it evaluates to ablank string.
param "HostName" Gateways, Probes Returns the hostname on which thegateway/probe is running (String)
param "Port" Gateways, Probes Returns the port on which thegateway/probe is listening. (Integer)
param "HotStandbyRole" Directory Returns the role of the gateway.(One of "Stand Alone", "Primary" or"Secondary")
param "Group" Directories, Probes, ManagedEntities,Samplers
Returns the group name of the data-item. There is not a group name fordataviews or cells. (String)
param "Description" Managed Entities,Samplers Returns the description of the data-item. (String)
param "BannerVar" Managed Entities Returns the path to the bannervariable define on the entity. (String)
param "Virtual"param "Floating"param "SelfAnnounced"
Probes Returns true if the probe is of thetype specified. (Boolean)
param "Secure" Probes Returns true if the probe isconnected to Gateway securely.(Boolean)
param "Imported" Probes Returns true if the probe is imported.(Boolean)
param "ExportingGateway" Probes Returns the name of the exportinggateway which the probe isimported from (if it is). (String)
param "PluginName" Samplers Returns the plugin name of thesampler. (String)
param "SampleInterval" Samplers Returns sample interval of thesampler in seconds (Integer)
param "UsingSampleInterval"param "UsingFileTrigger"param "UsingSampleTime"
Samplers Returns true if the sampler is usingthe specified sample type.(Boolean)
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 20 of 141
Property Target Description
rparam "ConState" Probes Returns the connection state of theprobe ("Unknown", "Up" , "Down","Unreachable", "Rejected","Removed", "Unannounced","Suspended", "WaitingForProbe")
rparam "ImportedConState" Probes Returns the imported connectionstatus of the probe ("Unknown","Up", "Down", "Suspended","Rejected", "Unreachable")
rparam "Rejection Reason" Probes Returns a numerical code passedby the probe to the gateway toexplain the reason that it rejectedthe connection from the gateway(Integer)
rparam "Rejection Message" Probes Returns a human readable stringthat explains the reason that proberejected the connection from thegateway (String)
rparam "Version" Probes Returns the version of the probe(String)
rparam "OS" Probes Returns the OS string as reported bythe operating system. (String)
rparam "AssignedUser" Data-items Returns the name of the person thatitem has been assigned to. (String)
rparam "SampleIntervalActive" Sampler Returns true if the sampler is active(otherwise false) (Boolean)
rparam "SampleTime" Dataview Returns the time of the last Samplein a human readable form (String)
rparam "SampleInfo" Sampler Returns human readable stringpublished by the probe about thesampling. This is normally blank(String)
rparam“ImportingConnectionName”
Probes Returns the configured connectionname for importing Gateway toGateway connections.
Additionally, the keyword previousmay be used to refer to the previous value of a property. For example:
if value > previous value + 10 then...
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 21 of 141
if severity <> previous severity then...
Only one property changes at a time, so it is not possible to use the previous keyword to refer to multipleproperties, like this:
if value > previous value and severity <> previous severity then...
but it is possible to refer to the same property multiple times
if value > previous value or value < previous value - 10 then...
When an item is first created, or when a rule is first added, then the previousvalue of any property will benull.
Note: previous allows access to the value the last time the rules were run, and not the last timethe value changed.For a given rule evaluation, previous will access the previous value of the attrib-ute whose change triggered that rule evaluation. For any other attribute, previous will access thecurrent value of the attribute. For more details and an example of the implications of this, pleasesee the Re-evaluating Rules section.In general, a rule should not use previous for attributeswhich the rule itself changes.
Data Items and PathsPaths can also be used to refer to the properties of other data-items, termed secondary variables. Thepaths themselves are defined separately in the path aliases section of the rule, and are each given names.
if value > path "mypath" value then...
The paths may be absolute, in that they refer to an exact item in the system. They can also be relative, forexample "the same row, but column X". More information about properties and paths can be found in theXPath User Guide.
Other live system dataIt is also possible to check the state of other parts of the Geneos system.
It is possible to test against the time of the gateway:
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 22 of 141
if within activetime "time1" then...
This may be used for changing the thresholds at different times of the day, for example:
if value > 70 and within activetime "trading hours" then...elseif value > 90 then...else...endif
VariablesManaged Entity variables are accessible from within rules. If a variable does not exist, an empty value willbe returned (the empty value converts to 0 if used as a numeric value). In most cases using a non simplevariable will not work in rules. The simple variable types are boolean, string, integer, and double. The inList() function is a special case as this function can reference stringList variables as well as simple variables.
if value > $(variable) then ...
Local variables can also be set, which are then accessible as per the above.
set $(variable) "literal string value"
If repeatedly using a path lookup value (e.g. in a sequence of if statements) it is more efficient to store thelooked-up value in a variable and reference this instead.
set $(variable) path "aliasName" value
Variable Active TimeIt is possible to use variable active time within rules.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 23 of 141
if within activetime $(vTime) then...
where "vTime" may be defined as a variable of type active time and have different values per managedEntity.
This may be used for changing the thresholds at different times of the day for each geographic locations,for example:
if within activetime $(vTime) thenif value > 90...elseif value > 90 then...else...endif
Target NamesParts of a unique name can be extracted from the target data-item when a rule is executed. These namescan then be used for comparison as for a normal value. For example, to set a variable to the row name ofthe target item, use the following:
set $(row) target "rowName"
The names which can be extracted are as follows:
l gatewayName
l netprobeName
l netprobeHost
l netprobePort
l managedEntityName
l samplerName
l samplerType
l dataviewName
l rowName
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 24 of 141
l headlineName
l columnName
OperatorsThere are a number of operators that can be used tomanipulate the data. Operators typically appearbetween two expressions (called the left hand side and right hand side), for example
5 + 3true and false
Some operators only operate on a single expression, for example:
not true
ComparisonComparison operators allow two values to be compared. The result will be a Boolean.
Operator Description
= Equality operator. The result is true if both sides areequivalent. Both sides will be converted to the sametype before comparison. Text comparisons are casesensitive.
<> Not equal operator. The result will be true if = wouldreturn false.
> The result will be true if the left hand side is greaterthan the right hand side. Both sides are converted tonumbers before the comparison takes place.
< The result will be true if the left hand side is less thanthe right hand side. Both sides are converted tonumbers before the comparison takes place.
>= The result will be true if the left hand side is greaterthan or equal to the right hand side. Both sides areconverted to numbers before the comparison takesplace.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 25 of 141
Operator Description
<= The result will be true if the left hand side is less thanor equal to the right hand side. Both sides areconverted to numbers before the comparison takesplace.
like Similar to =, but the right hand side should contain a
string which may have wildcards in it. An asterisk (*)
matches 0 or more characters and a question mark
(?) matches a single character. The comparison is
case insensitive.
e.g.'hello' like 'h*o'
unlike The result will be true if like would return false.
LogicThe logical operators operate on Boolean values and result in Boolean values.
Operator Description
and The result will be true if both sides evaluate to true.
If the left hand side evaluates to false then the right
hand side will not be evaluated, because it is
irrelevant to the outcome. This is called short
circuiting.
or The result will be true if either side evaluates to true.
If the left hand side evaluates to true then the right
hand side will not be evaluated, because it is
irrelevant to the outcome. This is called short
circuiting.
not The result will be true if the right hand side is false,false if the right hand side is true.
ArithmeticThe arithmetic operators operate on numbers and produce numbers as results.
Operator Description
+ Adds two numbers together. If either side is a doublethen the result will be a double, otherwise it will be aninteger.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 26 of 141
Operator Description
- Subtracts the right hand side from the left hand side. Ifeither side is a double then the result will be adouble, otherwise it will be an integer.
* Multiplies two numbers together. If either side is adouble then the result will be a double, otherwise itwill be an integer.
/ Divides the left hand side by the right hand side. Will
always result in a double value.
Note: Dividing by zero will result in 0.0.
% Modulo operator. Gets the remainder after the left
hand side is divided by the right hand side. Will
always result in an integer value.
Note: Modulo 0 will result in 0.
Order of precedenceNormal mathematical order of precedence rules apply, so given the following:
5 + 3 * 6
3 * 6 will be evaluated first, producing 18. 5 will then be added to this, producing 23. The order of evaluationcan be controlled using parentheses, for example:
(5 + 3) * 6
This will cause 5 + 3 to be evaluated first, producing 8. This will then bemultiplied by 6, producing 48.
The following table shows the order of precedence for all the operators. Items nearer the top of the tablewill bind tighter (will be evaluated first). This explains the above example, as * appears higher than + in thetable. Items at the same level will evaluate from left to right.
not
* / %
+ -
< > <= >=
= <> like unlike
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 27 of 141
and
or
FunctionsA range of functions exist to manipulate the data. Functions take one or more parameters, depending onthe function being used. The parameters are enclosed in parentheses and separated by commas:
function(parameter1)function(parameter1, parameter2)function(parameter1, parameter2, ...)
For example:
abs(-8)
The list of available functions is available in the Functions configuration section.
Control Statements
if/elseThe if/else construct allows choices to bemade based onmultiple conditions. One of the following formscan be used:
if [condition] then[optional additional if/else statements][updates and actions] or [set variables][optional additional if/else statements]endif
if [condition] then[optional additional if/else statements][updates and actions] or [set variables][optional additional if/else statements]else[optional additional if/else statements]
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 28 of 141
[updates and actions] or [set variables][optional additional if/else statements]endif
if [condition 1] then[optional additional if/else statements][updates and actions] or [set variables][optional additional if/else statements]elseif [condition 2] then[optional additional if/else statements][updates and actions] or [set variables][optional additional if/else statements]else[optional additional if/else statements][updates and actions] or [set variables][optional additional if/else statements]endif
The conditions are expressions that must evaluate to a Boolean value. Typically this will be the casebecause a comparison operator will be used.
The code block for each if or else condition in an if/else construct can contain [updates and actions] or itcan [set variables]. It cannot do both. However, it can contain as many other if/else constructs as needed.Each code block in an if/else construct is independent so the contents of one block will not enforce anyrequirements on the contents of any other block. For example:
if value <> previous value thenset $(changed) "true"if value > 75 thenseverity criticalelseseverity warningendifendif
Here the outer if block contains a [set variables] operation, but this does not restrict the inner if/else fromperforming an [updates and actions] operation.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 29 of 141
Updates and actions are grouped in a transaction that all occur together. This is detailed further in the RuleEvaluation section. The set statements are not part of the transaction and so to avoid confusion, theycannot be included in the same if block as the transaction. If the same boolean expression should be usedto set variables and fire a transaction then two separate if statements are required.
Updates and ActionsIf the condition of a rule is true then a number of updates or actions can be applied to the system.
UpdatesUpdates have the following format
[property] [value]
e.g.
severity critical
Themost common property to set is severity, but it is also possible to change the active properties ofitems and, with the compute engine, the value.
It is only possible to change properties of the target of a rule. This is similar to the behaviour of MicrosoftExcel, where the result of a calculation is shown in the cell where the formula is defined.
ActionsActions have the following format:
run [action name]
e.g.
run "email support team"
Action ThrottleThe default throttles for an action can be overridden in rules where the action is called. An example wouldbe in rules where a single action "email" may be throttledmore for CPU problems than for securityproblems with UNIX-USERS. A rule set on CPU utilizationmay look like:
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 30 of 141
if value > 10 thenseverity warningrun "email support" throttle "ten aminute"run "email managers" throttle "three in fivemins"endif
Whereas a rule on a security issuemight look like:
if value > 10 thenseverity criticalrun "email support" throttle "twenty aminute"run "email managers" throttle "ten in fivemins"endif
Although the same could be achieved by creating several actions, allowing the throttles to be overriddenlike this prevents duplication of data in the setup file.
For more information on throttling, refer to Action Throttling.
User DataWhen actions are specified, then additional data can be passed. This will be set as environment variableswhen the script runs. You can set the following types of information:
name / value pairs
e.g.
For shared libraries environment variables are passed as arguments. See Shared Library Actions.
values of the Variables
userdata "variable" $(var)
The value of the variable named var will available to the environment variable "variable"
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 31 of 141
Data item properties such as value, active, snoozed etc.
DataItem userdata "dataItem" value
The environment variable "dataitem" will contain the value of the dataitem that is the subject of the rule
A selection of properties from several data items based on an xpath.
userdata "dataItems" %%//cell value
The environment variable data item will contain a list of cell values in the form.
[false, 1, 2.3, "four"]
A target such as a dataview name
userdata "view_of" target "dataviewName"
The environment variable "view_of" will be set to the name of the dataview
whether we are within a particular active time.
userdata "active" within activetime "timeActive"
The environment variable "active" will be set to true or false depending on the if we are within theactivetime or not
The value of managed entity attributes
userdata "failover_attribute" attribute "FAILOVER"
Sets the environment variable "failover_attribute" to the value of themanaged entity attribute"FAILOVER".
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 32 of 141
Current timeseries values
userdata "usual-at-this-time" timeseries "MyTimeSeries"
The environment variable "usual_at_this_time" is set to the value of the time series at the presentmoment.
DelayA delay may be specified that will queue the updates and actions for the specified number of seconds orsamples. If the condition is no longer true before the end of the delay then the updates and actions will becancelled. This allows rules such as "if the value is greater than 70 for more than aminute then theseverity is critical". By default there is no delay. The format is:
delay [length] (seconds/samples)
e.g.
delay 60delay 60 secondsdelay 2 samples
The delay can be specified in terms of seconds or samples. If no unit is specified, then seconds isassumed. When the delay is specified in samples, this refers to the sampling of the target of the rule.
Note: It is pointless setting a delay as a number of seconds less than the sample interval ofthe sampler producing the data. This is because the value doesn't have a chance to changeand so the delay will not prevent the severity change. If a delay is set in seconds then it istherefore recommended to be at least two and a half times the sample interval. This issue canbe avoided altogether by setting the delay in terms of samples.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 33 of 141
RulesAn individual rule contains the rule code (whichmay contain multiple if statements), and has a number ofother attributes such as the targets that it applies to and the priority within the system.
TargetsRules must specify one or more targets that they apply to. A target is an XPath expression which specifiesone or more parts of the system, for example individual cells, all cells in a column, the same cell on allmanaged entities, the samplingStatus headline of every dataview, etc.
Rules may optionally have additional XPath expressions, called contexts, which are typically used torestrict the targets of a rule to particular managed entities or types. These are particularly useful when setusing rule group defaults (see rule group defaults below).
For example, if a rule's target was "all headlines named samplingStatus" and it had a context selecting "allheadlines in the FixedIncomeLondonmanaged entity", then the rule would apply only to sampling statusheadlines in that entity. It could be extended to other managed entities by addingmore context XPaths orto other named headlines by addingmore target XPaths.
Briefly, if no contexts exist, a rule applies to a particular item if it matches this expression:
(target1 or target2 or target3 ...)
If contexts do exist for a rule, the rule applies to items that match this expression:
(target1 or target2 or target3 ...) and (context1 or context2 or context3 ...)
So at least one target and at least one context must match an item for the rule to apply to it.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 34 of 141
PriorityMultiple rules can apply to a single item. Priority is used to determine the order that the rules are evaluated.Rules with a higher overall priority are evaluated first. Every rule must set a priority andmay optionallyspecify a priority group. 1 is the highest priority that can be set, 2 is lower than this, etc.
The overall priority of a rule is determined first by its priority group and then by its priority. If no group is setthen it is treated as 0, i.e. the priority will be higher than any rule where a priority group is set. Prioritygroups may be set using rule group defaults (see rule group defaults below).
An optional setting on each rule, 'Stop further evaluation', allows lower priority rules to be ignoredaltogether. The 'Show Rules' command shows all rules applying to an item in order of priority; if the 'Stopfurther evaluation' setting applies, a dividing line with the text 'EVALUATION STOPS HERE' is shown sothat you can see which are being used and which are not.
When priority is displayed (for example by the 'Show Rules' command), it will be shown as group:priority,so a rule with a priority group of 7 and a priority of 3 will be shown as 7:3.
Here are some examples of some priorities, shownwith the highest priority first and lowest priority last:
0:2 0:5 0:6 1:1 1:8 3:4 4:2
If two rules have the same overall priority (that is the same priority and priority group) then the systemmayevaluate them in any order; this order may vary between target items andmay change when theconfiguration is changed or reloaded.
ActiveTimeThe active time of a rule determines when it applies to the system. Outside of the active time it will be as ifthe rule did not exist at all. Multiple active times can apply to each rule, and these will be combinedtogether using the same rules as other active times. See the Active Times chapter for more details.
By default the active times set on rules also affect the active state of the rule's target cells. The target cellwill go inactive when all rules that apply to it go inactive (the cells active state is a logical OR of the activestate of all rules that have activeTimeAffectsCell set true). This can be turned off on a rule by rule basisusing the activeTimeAffectsCell setting, or overridden by explicitly setting the active state of a cell fromwithin a rule.
Rule EvaluationAs has already beenmentioned, rules will be evaluated from top to bottom in priority order. However it isimportant to understand what happens when updates to the system are applied and actions are fired.
Themost important factors to remember are:
l Each property can only be set once per rule evaluation.
l Updates are transactional
l Updates are applied once rules have finished evaluating
l Rules are evaluated whenever necessary
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 35 of 141
Single Property UpdatesConsider a rule like:
if value > 20 thenseverity warningendifif value > 30 thenseverity criticalendif
If the value is greater than 30 then the two updates conflict. The first 'if' will set the severity to warning; thesecond 'if' will also try to set the severity, but will not be able to, because it is already being set. (There isalso a problem here in that the rule has no 'else' clause to reset severity to 'ok' or undefined when thevalues falls below 20, see if without else)
TransactionsThe transactional element means that updates and actions that are grouped together will either all beapplied, or none of them will be applied. Expanding on the problematic rule from the previous section:
if value > 20 thenseverity warningrun "email support"endifif value > 30 thenseverity criticalrun "email boss"endif
Since the severity has been set to warning, the action "email support" can fire, but since the severitycannot be set to critical, the action "email boss" will not fire.
Note: As long as the value remains over 20 then the first transaction is 'reachable' or 'active'(i.e. if you run the rule again then you will still set severity to warning and run email support).This means that 'email support' will be eligible for escalation/repetition (see the Actionssection for more details).
Applying UpdatesTake the following rule
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 36 of 141
if severity = critical thenseverity warningendif
if severity = critical thenrun "email support"endif
If the severity turns critical then it will be changed to warning, but only after the rule has finishedevaluating. That means that the second condition will also still be true, and support will be emailed.
Re-Evaluating RulesWhenwriting rules, it should be assumed that they can run at any point, and will be run whenever the stateof the system changes. Take the following rule:
if value <> previous value thenseverity criticalelseseverity okendif
When the value of the item changes then the severity will be set to critical. As soon as the rule hasfinished and the state of the system has been changed then the rule will be re-evaluated, and since thevalue has not changed, the severity will be immediately returned to ok. In this case the severity changemay not be visible to the user, but an event will be generated that can be seen in the event ticker.
Actions can also be applied to the above:
if value <> previous value thenseverity criticalrun "email support"
elseseverity ok
endif
In this case, as well as the ticker event being generated, the action will fire whenever the value of thetarget changes.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 37 of 141
Note: Since the rule will be re-evaluated the action will not be eligible for escalation orrepetition.
Note: It is important to understand that when part of a rule is triggered and fires, resets anaction or changes some attribute, the rule will be re-evaluated. This is of particularsignificance when using the previous keyword, as it will only access the previous value of theattribute whose change triggered the rule evaluation. For any other attribute, previous willaccess the current value. Using the previouskeyword for attributes in a rule which are changedby the rule itself may cause duplicate actions as the rule will be re-evaulatedmultiple times.
Disabling Rules at Start UpIn a large Gateway setup, the overall time taken for the Gateway to start up can sometimes be reduced bydelaying the application of rules. This is controlled by the startup delay setting, which allows you tospecify an interval in seconds between theGateway becoming active and the rules being applied.
This may be useful because, when a data item is added to the Gateway, all existing rules must bechecked to determine whether they apply to that item. Conversely, when a rule is added, all existing dataitems must be checked to see whether the rule applies to them. In some cases - for instance if there are ahuge number of data items andmany rules, most of which only apply to a few items - it is faster to checkeach rule against all the data items than vice versa. The startup delay setting lets the gateway start withno rules and wait until most of the data items are present before applying them.
The length of the delay interval, and whether an interval is useful at all, must be determined by experimentin a non-production environment. This is because it is not possible for the Gateway to detect when it hasfinished connecting to all available Netprobes, since it does not know which Netprobes are about to comeup, or to determine when all samplers have finished sending their initial data, since this depends on thenature of each sampler and its configuration.
When rules are enabled after a startup delay, the 'fire on configuration change' settings for Actions, Alerts,Ticker Events and database logging are respected. The initial application of a rule is considered to takeplace in the context of a configuration change so that, by default, any actions, events or alerts triggered asthe rule is first applied will be suppressed.
Rule GroupsRule groups may be used to group rules together in logical sets for display purposes in the setup editor.However, they can also be used to set defaults that apply to all rules that they contain.
Multiple sets of defaults can also be specified, usually using contexts so that each set of defaults appliesto a different set of items. For example, different default active times could be used for separate sets ofmanaged entities.
Rule defaultsDefaults can be set for contexts, priority group and active times. These will each be set on any rules thatdo not have these set already.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 38 of 141
For example, if a set of defaults is configured, with default priority group 5, active time "London businesshours" and a context of 'managed entities with attribute "Region" set to "London"';
l A rule in the group with priority group 3, no active time and no context would get the active time andcontext specified in the defaults
l A rule with no priority group, active time "London evenings" and no context would get the priorityand context specified in the defaults
l A rule with priority group 2, no active time and the context of 'managed entites with attribute"Division" set to "Fixed Income"' would get the active time "London business hours" from thedefaults. Since the default context would not apply, this rule would apply to all managed entities inthe "Fixed Income" division, regardless of their "Region" attribute. This may not be what wasintended: contexts should be specified either via defaults or directly on rules, but not both ways inthe same rule group.
Transaction defaultsTransaction defaults can extend some or all of the transactions in all the rules in the group. Thespecification for transaction defaults has two parts: a 'match' section and a 'data' section; both consist ofstatements in the rule language.
The 'match' section specifies which transactions will be extended, based on the updates they perform. Forexample, it could specify "severity critical" or "active false". If nomatch conditions are specified then thedefaults will apply to all transactions. If multiple match conditions are specified then the defaults will applyonly to transactions whichmeet all the conditions.
The 'data' section specifies one or more statements, each of which will be added to thematchingtransactions, as long as it does not conflict with a statement already present in the transaction.
l An update statement specified as a default will be added tomatching transactions which do notupdate any properties.
l A delay statement specified as a default will be added tomatching transactions which do not set adelay.
l A run action statement specified as a default will be added tomatching transactions which do notrun an action.
l A userdata statement specified as a default will be added to all matching transactions. If atransaction sets the same user data variable, its setting will take priority over the default.
For example, consider a transaction default whichmatches "severity critical" and sets "run "emailsupport"": this will add the "email support" action to any transactions that set the severity to critical and donot already run any actions.
A set of defaults can contain multiple transaction defaults, each with their own 'match' and 'data' sections.If a transaction in a rule matches more than one transaction default, each 'data' section is applied in turn.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 39 of 141
Nested rule groupsRule groups can be nested and sets of defaults can be specified at each level of nesting. Defaults ongroups at an inner level of nesting are not merged with defaults on the groups that contain them: if a set ofdefaults defined on a group has the same name as a set defined at an outer level, the innermost set ofdefaults apply; otherwise it as if the sets of defaults defined at the outer level were copied to the innerlevel.
Common Pitfalls
if without elseIt is not necessary to put an else in an if statement, but in most cases it is sensible to do so. A rule such asthe followingmay cause problems:
if value > 10 thenseverity criticalendif
If the value starts off as 5 then the cell will be grey. If the value becomes 11 then the cell will go red. If itgoes back to 5 then it will still be red, because it has not been told to do anything different. In fact, it willcontinue to be red until the gateway or Netprobe are restarted, or the rule is changed. What was probablymeant was:
if value > 10 thenseverity criticalelseseverity okendif
Overlapping defaultsIf two or more sets of rule group defaults apply to to the same rule, it is as if the rule was specified twice,once for each set of defaults.
For example, suppose Rule GroupG contains these two sets of defaults and a relevant rule:
l Default "x": In transactions that set severity critical, run action X
l Default "y": In transactions that set severity critical, run action Y
l Rule 1: When value > 90 then severity critical
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 40 of 141
In this scenario, both defaults will apply to Rule 1, effectively creating two instances of rules within thegateway:
l Rule 1, defaults "x": When value > 90 then severity critical, run action X
l Rule 1, defaults "y": When value > 90 then severity critical, run action Y
Both the rules will apply to the rule targets, and the "Show Rules" output for a given target will show bothrules. Because both rule transactions set severity, only one will run. If the priority group is the same ineach case, then the choice of rule is unpredictable.
To avoid this ambiguity, if multiple sets of defaults apply to a group of rules, each set of defaults shouldspecify a different set of contexts. As long as these contexts do not overlap and as long as none of therules to which they apply specifies any contexts, at most one rule will apply to each item.
Alternatively, (if some overlap of contexts is unavoidable) each set of defaults could specify a differentpriority group, or they could have different (and non-overlapping) active times. As long as none of the rulesspecifies a priority group (or an active time), this will ensure that at most one rule applies at a time.
Configuration
Rules
rules > ruleGroupRule groups allow rules to be grouped together, and can also provide default values for a number ofsettings. See the Rule Groups section for more details.
rules > ruleGroup > nameSpecifies the rule group name.
Mandatory: Yes
rules > ruleGroup > defaultSpecifies defaults that apply to rules (rather than the rule code block contained within a rule), for examplesetting an active time. More than one default setting can be configured.
rules > ruleGroup > default > nameSpecifies the default setting name.
Mandatory: Yes
rules > ruleGroup > default > ruleSpecifies defaults that apply to rules (rather than the rule code block contained within a rule), for examplesetting an active time.
rules > ruleGroup > default > rule > contextsSpecifies default contexts that will apply to any rules that don't already have at least one context. Thistarget cannot include any runtime information in its filters. If it does then you will see an error like;
WARN: RuleManager Ignored context for default 'Broken default' as XPath contains non-
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 41 of 141
identifying predicate
Mandatory: No
rules > ruleGroup > default > rule > priorityGroupSpecifies a default priority group that will apply to any rule that doesn't already have a priority group set.
Mandatory: No
rules > ruleGroup > default > rule > activeTimeSpecifies an active time that will apply to any rule that doesn't already have at least activetime set. It canbe specified using active time name or a variable active time.
Mandatory: No
rules > ruleGroup > default > transactionSpecifies defaults that apply to transactions. For example, setting a default action to run.
rules > ruleGroup > default > transaction > matchSpecifies which transactions will receive the defaults. Any parts specified heremust be present andmatch those in the rule for the defaults to be applied.
Mandatory: NoDefault: All transactions will receive the defaults.
rules > ruleGroup > default > transaction > dataSpecifies the defaults to apply to the transactions that match. Each part specified here will be added toeachmatching transaction, as long as it does not conflict with the existing content of the transaction.
rules > ruleAn individual rule provides all the relevant information necessary to provide alerting on parts of the Geneossystem. See the Rules section for more details.
rules > rule > nameSpecifies the name of the rule.
Mandatory: Yes
rules > rule > contextsSpecifies the data-items that this rule applies to. These are normally more general than targets, andtypically restrict the targets (e.g. a context may specify all cells inside twomanaged entities, and thetargets may specify all cells in a particular column). This target cannot include any runtime information inits filters. If it does then you will see an error like;
WARN: RuleManager Ignored context for rule 'Broken rule' as XPath contains non-identifyingpredicate
Mandatory: No
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 42 of 141
Default: All items are valid (if no rule group defaults apply)
rules > rule > targetsSpecifies the data-items that this rule applies to - the items that will be affected by property updates. Thistarget cannot include any runtime information in its filters. If it does then you will see an error like;
Rule 'Broken rule' ignored as a target contains non-identifying predicate
More information about identifying predicates and non-identifying predicates can be found in XPaths -User Guide especially in the section on Predicates. | Mandatory: Yes
rules > rule > priorityGroupThe priority group of the rule. Higher priority (lower numbered) rules will be evaluated before lower priorityones. A rule with a priority group of 2 and priority of 3 has a higher overall priority than (and will beevaluated before) a rule with a priority group of 3 and a priority of 2.
Mandatory: NoDefault: 0 (if no rule group defaults apply)
rules > rule > priorityThe priority of the rule. Higher priority (lower numbered) rules will be evaluated before lower priority ones.Rules with the same priority may be evaluated in any order.
Mandatory: Yes
rules > rule > activeTimeActive times specify when this rule is active. When the rule is outside the active times then it is as if therule was not in the setup file at all. By default the active times set on a rule will also affect the active stateof the rule's targets. See activeStateAffectsCell for details.
Mandatory: NoDefault: Active all the time (if no rule group defaults apply)
rules > rule > activeStateAffectsCellIf set then the active state of the rule affects the active state of the cell. The active state of the cell is setfrom a logical OR of all the rules that apply to it that have this setting set. If this setting is set false then theactive state of the rule will not affect the active state of its target cells in any way.
Mandatory: NoDefault: true
rules > rule > stopFurtherEvaluationIf set then any lower priority rules on the same item will not be evaluated. This is indicated in the 'ShowRules' commandwith a horizontal line with the text 'EVALUATION STOPS HERE'.
Mandatory: NoDefault: false
rules > rule > pathVariablesPath variables are used in pathAliases to dynamically specify parts of a path.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 43 of 141
Themost common usage of path variables is to extract the row name from a data-item, and then use thisin a path alias to extract the value of a cell in a different dataview, which has a corresponding name.
To do this, configure a path variable named pathVar to reference the row name using the following syntax:
target "rowName"
Then configure a path alias (e.g. by dragging a cell from the relevant dataview) and alter the row name toreference the path variable above by setting the name comparison value to $pathVar.
Mandatory: No
rules > rule > pathAliasesPath aliases may be used in rules to refer to secondary data-items.
Mandatory: No
rules > rule > evaluateOnDataviewSampleEnabling this would cause this rule to evaluate only when the data view of the item specified in "target"does a sample.
This would be useful in a situation where a rule is being used to populate the value of a cell. Typically sucha rule would populate the value of a cell based on a calculation involving the values from a number of cells.E.g.:
value total(wpath "s" value)
In the above rule, the rule target is being populated with the total of the values from the cells denoted bywildcarded path "s". (For example, "s" might refer to all the cells in a column).
By default, the rule evaluates whenever the value of any of the cells denoted by "s" changes. If this flag isenabled, the rule will only be evaluated when the dataview of the "target" of the rule does a sample.
Enabling this flag has two advantages:
l Performance: As the rule is guaranteed to be evaluated only once per sample interval.The benefits aremore apparent in rule that calculated a value based on a large number ofcells. E.g. The total of a 100 cells.
l When performing a rate calculation based on a computed cell: The rate function uses thecurrent and previous value of a cell to calculate the rate of change per second. When arate is calculated based on a computed cell, let's say a total, the calculated rate wouldnot be particularly useful if the total is updated each time one of the source cells for thetotal changes. Enabling this flag on the rule that calculates the total wouldmake the rulethat calculates the rate produce amore useful value. (In fact the gateway will produce awarning if the gateway spots that the above described situation has occurred. This can
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 44 of 141
be disabled using disableRateWarning rules > rule > disableRateWarning on the rulethat does the rate calculation.)
Mandatory: NoDefault: false
rules > rule > disableRateWarningDisables the warningmentioned in evaluateDataviewSamples.
Mandatory: NoDefault: false (i.e. produce a warning if needed)
rules > rule > blockThis is where the rule code goes. This gets evaluated each time any relevant data changes. The right-clickmenu provides some of themost common keywords and functions that can be used. For a full list of whatcan appear in a code block, and details of how each can be used, please refer to the Rule Code section.
Mandatory: Yes
rules > startupDelayThis section controls whether the Gateway will delay applying rules for a number of seconds after it isstarted or becomes active in the course of a Hot Standby failover or failback. See the Disabling Rules atStart Up section for more details.
rules > startupDelay > intervalThe number of seconds that the Gateway will wait after becoming active before it applies the ruleconfiguration.
Mandatory: NoDefault: 0 (i.e. no delay)
FunctionsThis section contains the standard function definitions. Compute Engine functions are listed separately.
Numeric Functionsabs
abs(number)
Absolute value operator. Any negative values are converted to positive values.
abs(3) => 3abs(-3) => 3
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 45 of 141
sqrt
sqrt(number)
Calculates the square root of the given number. Negative inputs result in null being returned.
sqrt(4) => 2
pow
pow(base, exponent)
Raises the given base to the power of the given exponent.
pow(10, 2) => 100
String FunctionsstringBefore
stringBefore(string: haystack, string: needle)
Gets the substring of haystack that starts at the beginning and ends immediately before the first instanceof needle. If needle is not in haystack then the whole of haystack will be returned.
stringBefore("abcdefg", "d") => "abc"stringBefore("abcabcabc", "ca") => "ab"stringBefore("abcdefg", "p") => "abcdefg"
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 46 of 141
stringAfter
stringAfter(string: haystack, string: needle)
Gets the substring of haystack that starts at the immediately after the first instance of needle. If needle isnot in haystack then the whole of haystack will be returned.
stringAfter("abcdefg", "d") => "efg"stringAfter("abcabcabc", "ca") => "bcabc"stringAfter("abcdefg", "p") => "abcdefg"
toUpper
toUpper(string)
Converts all the characters of string to upper case. Non-alphabetic characters are not changed.
toUpper("hello") => "HELLO"toUpper("HELLO") => "HELLO"toUpper("HelloWorld") => "HELLOWORLD"toUpper("Hello 123") => "HELLO 123"
toLower
toLower(string)
Converts all the characters of string to lower case. Non-alphabetic characters are not changed.
toLower ("hello") => "hello"toLower("HELLO") => "hello"toLower("HelloWorld") => "hello world"toLower("Hello 123") => "hello 123"
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 47 of 141
concat
concat(string: left, string: right)
Joins two strings together, returning a string value. Function arguments which are not strings (i.e. numericvalues) will be converted to a string tomake the function call.
concat("hello", " world!") => "hello world!"concat(123, 456) => "123456"
replace
replace(string:original, string:replaceWhat, string:replaceWith)
(i.e. numeric values) will be converted to a string tomake the function call.
Replaces string replaceWhat with string replaceWith in the original string.
replace("1,000",",","") =>"1000"replace("1,000,000",",",".") =>"1.000.000"
inList
inList(String:needle, String:haystack1, String:haystack2, ...)
Returns true if the first string (the needle) is found in any of the other strings provided to inList(). Thestrings can be passed using geneos variables as well as static strings. The variables that are supported ininList() are integer, double, string and stringList. If a stringList variable is used, inList() will test the needleagainst all the strings that have been defined in the stringList.
if inList(value, "one","two","three") then ...if inList(value, $(string1), $(string2)) then ...
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 48 of 141
if inList(value, $(stringList)) then ...
substr
substr(String:source, int:start[,int:end])
Extracts part of a string given the start and end position within the string. The end is optional and defaultsto the length of the source. String indexes start at 1 (one).
substr("Mary had a little lamb",1,4) =>"Mary"substr("Mary had a little lamb",19) =>"lamb"
trim
trim(String:source)
Removes whitespace from either side of a string.
trim(" Hello ") =>"Hello"
ltrim
ltrim(String:source)
Removes whitespace from the left side of a string.
ltrim(" Hello ") =>"Hello "
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 49 of 141
rtrim
rtrim(String:source)
Removes whitespace from either side of a string.
rtrim(" Hello ") =>" Hello"
strpos
strpos(String:hackstack, String:needle)
Returns the position of the first occurance of needle in haystack or 0 (zero) if not found.
strpos("one,two, three","one") => 1
strrpos
strpos(String:hackstack, String:needle)
Returns the position of the last occurance of needle in haystack or 0 (zero) if not found.
strrpos("one,two, three and back to one","one") => 27
regMatch
regMatch(string:haystack, string: needle, [string:flags])
Returns whether the given regular expression (needle) matches the given string (haystack). Accepts PerlCompatible Regular Expressions. The following optional flag can be specified:
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 50 of 141
iCase Insensitive comparison
Function arguments which are not strings will be converted to a string tomake the function call. If aninvalid regular expression is specified then null will be returned.
regMatch("One Two Three", ".*Two.*") => true
Time Functionsnow
now()
Gets the current time at the point of execution expressed as seconds since the UNIX epoch.
startOfMinute
startOfMinute(dateTime: time)
Gets the datetime timestamp representing the start of theminute in the given datetime timestamp. If nodatetime timestamp is provided, current timestampwill be used for evaluation.
startOfMinute(1298937659) => 1298937600
startOfHour
startOfHour(dateTime: time)
Gets the datetime timestamp representing the start of the hour in the given datetime timestamp. If nodatetime timestamp is provided, current timestampwill be used for evaluation.
startOfHour(1298941199) => 1298937600
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 51 of 141
startOfDay
startOfDay(dateTime: time)
Gets the datetime timestamp representing the start of the day in the given datetime timestamp. If nodatetime timestamp is provided, current timestampwill be used for evaluation.
startOfDay(1299023999) => 1298937600
startOfMonth
startOfMonth(dateTime: time)
Gets the datetime timestamp representing the start of themonth in the given datetime timestamp. If nodatetime timestamp is provided, current timestampwill be used for evaluation.
startOfMonth(1301615998) => 1301612400
startOfYear
startOfYear(dateTime: time)
Gets the datetime timestamp representing the start of the year in the given datetime timestamp. If nodatetime timestamp is provided, current timestampwill be used for evaluation.
startOfYear(1304121600) => 1293840000
parseDate
parseDate(string format, string date, [string:timezoneRegion])
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 52 of 141
Returns a time value, expressed as the number of seconds since the UNIX epoch, generated by parsingthe specified string using the format provided. Any components of the date that cannot be determined fromthe format will be populated using a value as would be returned from startOfDay (now()). A full list of theavailable Time Formatting Parsing Codes is available in the Time Formats Technical Reference.
parseDate("%d%B%Y%H:%M:%S", "1 January 2010 15:42:59") => 1262360579parseDate("%H", "14") => the timestamp corresponding to 14:00 on the day of execution of therule
An optional third parameter can be used to specify the timezone region of the date. A full list of timezoneregions with their GMT offsets is available in the Time Formats Technical Reference. This will overrideany use of the%Z specifier in the format.
parseDate("%d%B%Y%H:%M:%S%Z", "25 February 2013 13:14:15 KST")parseDate("%d%B%Y%H:%M:%S%Z", "25 February 2013 13:14:15 KST", "Asi-a/Qyzylorda")
If the%Z specifier is used it is important to remember that many common timezone abbreviations cancollide. A list of how the gateway interprets abbreviations can be obtained by running it with the -display-timezone-defaults command line switch, users can override the default meanings, or create new onesabbreviations, by specifying them in Operating Environment section of the gateway configuration. In allcases, if the third optional parameter is provided, it will over-ride any timezone parsed from the date.
parseDate("%d%B%Y%H:%M:%S%Z", "25 February 2013 13:14:15", "Asia/Qyzylorda")
If no %Z is specified but the optional third parameter is specified you can interpret a date as if were fromthe region specified and got the Gateway's timezone.
printDate
printDate(string format, [dateTime timestamp, [string:timezoneRegion]])
Formats the dateTime value timestamp, expressed as a count of seconds since the UNIX epoch,according to the format format. If no timestamp value is specified, or an invalid value provided, the timereturned from startOfDay(now()) will be used. The format conforms to the list of the Time FormattingPrinting Codes found here.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 53 of 141
printDate("%d%B%Y%H:%M:%S", 1262360579) => "01 January 2010 15:42:59"printDate("%d%B%Y") => the timestamp corresponding to day of execution of ruleprintDate("%d%B%Y%H:%M:%S", "InvalidTimeStamp") => "01 January 1970 00:00:00"
An optional third parameter can be used to specify the timezone region for which to format the date. Ifeither the%Z or%z format specifiers are used then the timezone abbreviation or UTC offset respectivelywill be printed in accordance with this parameter. A full list of timezone regions with their GMT offsets isavailable in the Time Formats Technical Reference. If the third parameter is not specified then the datewill be formatted according to the timezone of the gateway operating environment.
printDate("%d%B%Y%H:%M:%S%Z", 1262360579, "America/Panama") => "01 January2010 10:42:59 EST"
Compute Engine
IntroductionThe Compute Engine functionality allows additional value to be added to themonitored data from theGeneos system. It includes the ability to add additional rows, columns and headlines to existing dataviewsand to populate the new cells with calculated data. Additional dataviews can also be created to allowsummaries across multiple parts of the system.
Some possible uses are:
l Create a new column in the CPU plugin that shows a 1-minutemoving average of the%usertimecolumn.
l Create a new headline in the PROCESSES plugin that counts the number of process instancesbeing run by user 'fidessa'
l Create a new total row in a plugin that adds up all the values in relevant columns.
l Create a new view, summarising the lines to the exchanges, with a column that will be green if allthe lines are up, amber if some of the lines are down and red if all the lines are down.
l Create a new view using data from other views via the Gateway-sql plugin (see Section GatewaySQL plugin).
There are also a number of extensions to the rules that are part of the compute engine functionality. Theseare explained below.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 54 of 141
Adding to existing dataviewsTo add rows, columns and headlines to existing dataviews, the relevant sampler must be selected fromthe samplers section of the setup file. A dataview must then be added (in the Advanced tab) with the samename as the view you wish to add to.
Pressing the additions button will then result in the following dialog, which can be used to add theadditional information:
Creating new viewsTo create entirely new views, the following steps should be taken:
l Create a new sampler
l Do not set a plugin type
l Add a dataview row (as above)
l Use "Create on gateway" and set the name of the first column.
l Press "additions" and define the rows and columns that you want
l Add the sampler to amanaged entity
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 55 of 141
Populating cells with dataNewly created cells are populated using rules. This means that any rule operators and functions can beused.
The target of the rule should be one or more cells to populate.
The format of the rule code is:
value [value to set]
e.g. to set a cell to always have the value 7, the rule would be
value 7
Paths can also be used to get the value of another cell. The paths themselves are defined separately, andare each given names.
value path "other cell" value
The paths may be absolute, in that they refer to an exact item in the system. They can also be relative, forexample "the same row, but column X". Please refer to the path editor documentation for details of how toset up paths.
To perform a calculation simply specify it as you do with normal rules:
value path "other cell" value / 2
or
value path "other cell" value + path "third cell" value
Many more calculations can be performed, which are described below.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 56 of 141
The values returned from calculations will typically be Integer or Double values, but these will normallyhavemeaning (units) associated with them such as MB, MB/s, %, etc. When writing values out, thenumbers can be formatted with the format function. The number of decimal places can also be specified.
For example:
value format("%.2f Mb", path "other cell" value)
whichmay output
3.15Mb
rather than simply
3.15242
Extended Rule SyntaxThe following sections describe somemore functions and features that are enabled as part of the computeengine.
Using functions with ranges of itemsSome useful functions exist to help summarise data, such as average, total, max, min, count and standarddeviation. As well as normal parameters, these operate on wildcard paths which return sets of items ratherthan a single item.
Note: 'wpath' (wildcard path) is used instead of 'path'.
value total(wpath "line throughput" value)
or
value count(wpath "lines up" value)
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 57 of 141
These functions can takemultiple parameters if required:
value average(path "cell a" value, path "cell b" value)
or
value average(wpath "line throughput" value, path "additional" value)
Available functions are listed in the Statistical Functions configuration section, and includemaximum,minimum, average, total, count, standard deviation and rate.
Using historic time-based functionsUsing the normal rule syntax, previous values can be compared against the current value. The time-basedfunctions allow a summary to be created from a period of time.
For example, to populate a cell with the highest the CPU has been over the last minute:
valuemaximum(path "cpu" value for "1minute")
The "1minute" refers to a namedHistory Periods. These are defined at the top level of the rules section -at the same place as rule groups.
Note: 'wpath' cannot be used with historical functions.
All the functions mentioned under sections Statistical Functions and Duration-Weighted StatisticalFunctions can be used in this manner.
Local VariablesIn addition toManaged Entity variables, temporary local variables can be set and then accessed using thesame syntax:
set $(temp) value + 1if $(temp) > 0 then ...
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 58 of 141
Local variables overrideManaged Entity variables. Once a rule sets a variable with the same name as aManaged Entity variable then theManaged Entity variable will no longer be accessible from within thatrule. Local variables have global scope but cease to exist at the end of each rule evaluation.
Tips
ConditionsIt is also possible to use the conditional functionality of rules when setting values. For example:
if path "other cell" value > 10value path "other cell" valueelsevalue path "third cell" valueendif
Setting other properties in additionAlthough this section has dealt simply with values, it is possible to set other properties at the same time inthe same rule, just like with normal rules. e.g.
value path "other cell" valueseverity path "other cell" severity
Note: Items outside 'if' blocks are independent of each other (i.e. they each have their owntransaction). For the above example, this means that the value will be set, even if a previousrule has already set the severity. If you need them to be in the same transaction you canenclose them in an if like this:
if true thenvalue path "other cell" valueseverity path "other cell" severityendif
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 59 of 141
Feedback
Some dramatic behaviour can be seen if rules are written incorrectly. Take a counter, for example:
if path "my cell" severity = critical thenvalue value + 1else
This will increase the value of the current cell whenever "my cell" is red rather than when "my cell" turnsred. This will cause the cell to continually increase in value. Some kind of stop or exit condition is neededto fix it, for example:
if path "my cell" severity = criticaland path "my cell" previous severity <> critical thenvalue value + 1else
Configuration
History Periods
rules > historyPeriodHistory periods provide themeans to aggregate values from a target from a given period in time. Thiscollection of values can then be used with historic time based functions.
History periods are named, so for example if you are collecting values on a daily basis it may make senseto simply call your history period "day". This gives you the ability to refer to themaximum (or any otheraggregate function) value for a day on a given target.
Alternatively youmay be responding to a particular event such as an extremely slow network and want toanalyse the data from when the incident occurred. In which case you can configure a one off history periodand call it something like "The day the earth stood still".
There are two types of history periods - "rolling" and "fixed". The following example illustrates thedifference.
Say you are calculating the average of a cell for a period of a day. You can either use a "rolling period" or a"fixed period".
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 60 of 141
"Rolling period of 1 day":
The calculation will always be done based on the values of the last 24 hours. E.g. At 2 pm today, theaverage will be calculated using the values collected between 2 pm yesterday and now. The average willnever be reset as such at any point. Of course, at 2.30pm today, we will no longer consider the valuescollected before 2.30pm yesterday.
"Fixed period of 1 day":
The calculation will be based on the values collected between 12.00am today andmidnight. At midnightthe average will reset and the calculation will start again based on the values collected from that pointonwards. (You can optionally change the start time of the period).
Mandatory: No
rules > historyPeriod > calculationPeriodThis is a choice between a rolling period of time e.g. day, month, quarter… and a fixed period such as aparticular day starting at a particular time.
See rules > historyPeriod for a detailed explanation.
Mandatory: Yes
rules > historyPeriod > calculationPeriod > rollingPeriodA rolling period allows you to define intervals such as days, months, past 3months, etc. So for example ifyou had an historical period called quarter, you could refer to the average value for a target over the lastquarter, two quarters, etc.
See rules > historyPeriod for a detailed explanation.
rules > historyPeriod > calculationPeriod > rollingPeriod > measureThis is the unit of time by which this period is measured. A choice of month, week, day, hour, minute orsecond.
Mandatory: YesDefault: Month
rules > historyPeriod > calculationPeriod > rollingPeriod > lengthThis is the number of measure units that make up an individual period.
Mandatory: YesDefault: 1 unit
rules > historyPeriod > calculationPeriod > rollingPeriod > maxValuesThis is themaximum number of values to record for the purpose of a given historical calculation.
In the case of historical calculations using rolling periods, the gateway must record the historical valuesused as input. This is needed so that outdated values can be dropped out of the calculation when needed.
For example, say we are calculating the average over an hour, for a rule target that is sampled every 3seconds. If we were to store each input value, we would have to store 1200 values (1 Hour / 3). Onceevery 3 seconds, we would have to drop off the oldest input value recorded, and recalculate the average bygoing through all 1200 stored values. If we run this rule for a large number of targets, the resource costcould be significant.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 61 of 141
Hence, instead of recording each and every input value in the period, the gateway breaks down the periodinto a set of sub-periods and records just a single representative value for each of those periods. ThemaxValues setting denotes themaximum such values to record (i.e. themaximum number of sub-periods).
For example, in the previous example, if we set maxValues to 120, the gateway will store only a singleinput value for each 30-second period (1 hour / 120). More importantly, the gateway will only need torecalculate the average every 30 seconds, and would only need to go through 120 values for therecalculation.
This setting should be set according to the accuracy required. For example, for the case of averages, thedefault setting of 100 would generally result in computed values that are accurate to the first 2 digits.
This setting would be ignored if the number of samples collected during the period is less than thespecified value. For example, for a 5-minute period on a 10-second sample interval, only 60 values willever be stored. Typically, there would be no need tomodify this setting for shorter periods.
Mandatory: NoDefault: 100
rules > historyPeriod > calculationPeriod > fixedPeriodA fixed period defines a fixed period in time from which you want to reference values.
See rules > historyPeriod for a detailed explanation.
rules > historyPeriod > calculationPeriod > fixedPeriod > lengthThis is the unit of time by which this period is measured. A choice of month, week, day, hour or minute isavailable for selection. Here is an example that calculates the average of a cell for a fix time period usingthe above choices:
l Minute option: Average will reset at the boundary of eachminute and calculation of Average willstart again based on the values collected from that point onwards.
l Hour option: Average will reset at the boundary of each hour and calculation of Average will startagain based on the values collected from that point onwards.
l Day option: Average will reset eachmidnight and it will start again based on the values collectedfrom that point onwards.
l Week option: Average will reset each Sunday midnight and it will start again based on the valuescollected from that point onwards.
l Month option: Average will reset at end of eachmonthmidnight time and it will start again based onthe values collected from that point onwards.
See rules > historyPeriod for a detailed explanation.
Mandatory: Yes
rules > historyPeriod > calculationPeriod > fixedPeriod > startSpecifies when the time period starts.
Mandatory: No
rules > historyPeriod > calculationPeriod > fixedPeriod > start > monthA non-negative integer value representing themonth that the historical period started.
Mandatory: No
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 62 of 141
Default: January
rules > historyPeriod > calculationPeriod > fixedPeriod > start > dayOfMonthWhich day of themonth did the fixed period start? This is represented as a non-negative integer.
Mandatory: NoDefault: 1st day of month
rules > historyPeriod > calculationPeriod > fixedPeriod > start > dayOfWeekDeprecated: Use rules > historyPeriod > calculationPeriod > fixedPeriod > start > weekDay instead.
Which day of the week did the fixed period start? This is represented as a non-negative integer.
Mandatory: NoDefault: 1st day of week i.e. Sunday
rules > historyPeriod > calculationPeriod > fixedPeriod > start > weekDayWhich day of the week did the fixed period start? This should be one of the values:
l Monday
l Tuesday
l Wednesday
l Thursday
l Friday
l Saturday
l Sunday
Mandatory: NoDefault: Sunday
rules > historyPeriod > calculationPeriod > fixedPeriod > start > hourThis allows you to further specify to the hour when the fixed period started.
Mandatory: NoDefault: 00 hours (00-23 being the range)
rules > historyPeriod > calculationPeriod > fixedPeriod > start > minuteThis allows you to further specify to theminute when the fixed period started.
Mandatory: NoDefault: 00mins (00-59 being the range)
rules > historyPeriod > calculationPeriod > fixedPeriod > start > secondThis allows you to further specify to the second when the fixed period started.
Mandatory: NoDefault: 00 secs (00-59 being the range)
rules > historyPeriod > activeTimeThis is a reference to an active time to determine when this historical period is in use.
Mandatory: No
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 63 of 141
FunctionsThis section details the functions specific to compute engine. The standard function definitions are alsoavailable.
String Functionsformat
format(string, anything, ...)
The string specifies a format and then, depending on the format, more arguments may be present.
The format is composed of zero or more directives: ordinary characters (excluding%) that are copieddirectly to the result; and conversion specifications, each of which requires an additional argument to bepassed to the format function.
Each conversion specification consists of a percent sign (%), followed by the following in order:
l An optional precision specifier that says how many decimal digits should be displayedfor floating point numbers. This consists of a period (.) followed by the number of digits todisplay.
l A type specifier that says what type the argument data should be treated as. Possibletypes:
l d - the argument is treated as an Integer, and presented as a (signed) decimalnumber.
l f - the argument is treated as a Double, and presented as a floating-point number.
l s - the argument is treated and presented as a String.
l % - a% followed by another% character will write% to the output. No argumentis required for this.
This function is most useful when writing values into cells.
format("%dMb", 5) => "5Mb"format("%d%%", 6) => "6%"format("%f Mb", 5.346) => "5.346Mb"format("%.2f Mb", 5.348) => "5.35Mb"format("%.5f Mb", 5.348) => "5.34800Mb"format("There are%d files with%d in error", 6, 4) => "There are 6 files with 4 in error"
Statistical Functions
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 64 of 141
maximum
maximum(number, ...)
Gives the highest value from a set of values. Can be used with ranges or history periods.
maximum(1, 8, 2, -10, 6) => 8maximum(3) => 3
minimum
minimum(number, ...)
Gives the lowest value from a set of values. Can be used with ranges or history periods.
maximum(1, -8, 2, 10, -6) => -8minimum(3) => 3
average
average(number, ...)
Gives themean average of a set of values. Can be used with ranges or history periods.
average(1, 8, 2, -10, 6) => 8average(3) => 3
total
total(number, ...)
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 65 of 141
Gives the total (sum) of a set of values. Can be used with ranges or history periods.
total(1, 3, 2, 2, 4) => 12total(3) => 3
count
count(anything, ...)
Gives the number of items in the list. Can be used with ranges or history periods.
standardDeviation
standardDeviation(anything, ...)
Calculates the population standard deviation from a set of values. Can be used with ranges or historyperiods.
See evaluateOnDataviewSample on increasing performance of rules with statistical calculations.
Duration-Weighted Statistical FunctionsThe following statistical functions perform calculations while weighting each historical value by theduration for which the particular value was present. Only historical items can be used as parameters tothese functions. E.g.:
The following is valid:
value durationWeightedAverage(path "cpu" value for "1minute")
The following is not:
value durationWeightedAverage(wpath "cpu" value)
One point to note about weighting by duration is that at the point a new value is seen by the gateway, thatvalue will has an associated duration of 0 and hence would effectively not be considered for thecalculation.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 66 of 141
For example, consider the case of a rule calculating a duration-weighted average of a cell X. As with allrules containing historical functions, the rule will be re-evaluated each time the dataview containing cell Xsamples. However, when this happens and a new value is seen for cell X, the associated duration for thatnew value will be 0 seconds as cell X only changed to that new value at this very point in time. Therefore,the new value will not be reflected in the calculated result.
At a later point in time, when the rule is evaluated again (e.g. at the next sample) the previously-mentionedvalue will now have an associated duration and hence will be reflected in the calculated result.
This effectively means that the results of duration-weighted calculations would appear to be "one samplebehind" - however this is the expected behaviour according to the way such rule calculations are invoked.
durationWeightedAverage
durationWeightedAverage(historical item)
Calculates the average, but with each source value weighted according to the duration for which the valuewas present.
E.g.
Value Duration
100 10 seconds
200 10 seconds
300 40 seconds
The duration-weighted 1minute average for the above values would be:
(100*10 + 200*10 + 300*40) / (10 + 10 + 40)
durationWeightedTotal
durationWeightedTotal(historical item)
Calculates the total, but with each source value weighted according to the duration for which the valuewas present.
E.g.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 67 of 141
Value Duration
100 10 seconds
200 10 seconds
300 40 seconds
The duration-weighted 1minute total for the above values would be:
(100*10 + 200*10 + 300*40)
durationWeightedStandardDeviation
durationWeightedStandardDeviation(historical item)
Calculates the population standard deviation, but with each source value weighted according to theduration for which the value was present.
E.g.
Value Duration
100 10 seconds
200 10 seconds
300 40 seconds
The duration-weighted 1minute standard deviation for the above values would be calculated as follows:
Total duration = 10 + 10 + 40= 60
Average = (100*10 + 200*10 + 300*40) / 60= 250
Standard deviation = square-root (((100 - 250)^2 * 10 + (200 - 250)^2 * 10 + (300 - 250)^2 * 40) /60)
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 68 of 141
Handling of non-numeric valuesFor statistical functions mentioned above, textual values will be treated as a valid number if they beginwith a numerical value. All other textual values, except for blanks, will be considered as 0.
E.g.:
"10kb" will be considered as 10."number10" will be considered as 0.Blank values (including white-space only values of any length) will be ignored.
E.g.:
minimum(20, "10boxes", " ") will be 10.average(20, "10boxes", " ") will be (20 + 10) / 2
The above logic will apply to historical calculations as well. A blank value will be considered as a lack of avalue for that particular duration.
E.g.:
Value Duration
100 10 seconds
15 seconds
300a 30 seconds
Average = (100 + 300) / 2Duration weighted average = (100*10 + 300*30) / 40
Other Functionsrate
rate(item)
Calculates the rate of change of an individual item. It can be applied to only one data-item. E.g.
rate(path "s" value)
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 69 of 141
The rate of value change is calculated at a particular point in time as: (new value - previous value) /sampling interval (in secs)
The following table gives an example of rate change for cell values:
Time (in secs) 0 2 4 6 8 10
Cell Value 1 2 8 4 3 5
Rate 0 0.5 3.0 -2.0 -0.5 1.0
Note: When the new value is lower than previous value, the rate of change is in negative.
This function cannot be used with history periods or ranges as it only deals with current value change. Thefunction recalculates the rate of value change whenever a new sample is seen e.g. at sample intervals,sample times or duringmanual sampling.
Normally, rules are evaluated for computed cells whenever any secondary variable changes or the targetdata-items change. This function (rate) is an exception in this case. For computed cells, the rate of valuechange for a target data-item is calculated only at sample intervals. For this to happen, one needs to setthe evaluateOnDataviewSample flag on that rule. Otherwise, the gateway issues a warning. For moredetails, refer evaluateOnDataviewSample.
first
first(path/wpath/literal, ...)
Returns the first concrete item encountered when evaluating the function parameters in the orderspecified.
E.g.
Function Return value
first(wpath "p" value) Returns the value of the first cell that matches path"p". If no matching cell, returns empty.
first(wpath "p" value, wpath "q" value, …) Returns the value of the first cell that matches path"p". If no matching cell, then checks path "q" and soon.
first(wpath "p" value, 10) Returns the value of the first cell that matches path"p". If no matching cell, then returns 10.
Note: For a given wpathmatchingmultiple items it's not possible for the user to predict whichitem will be considered as 'first' by the gateway. For example, for a wpathmatching all thecells in a particular column, the item returned from this functionmay not necessarily be theone from the first row as seen by the user, nor from the row that was created first.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 70 of 141
Hence, for a deterministic outcome this function should only be used with paths that at most wouldmatchone item at run time:
One use case would be to access the first matching item from a set of unique paths in a user-specifiedorder. E.g.:
first(path "x" value, path "y" value, path "z" value).
This path would return the value of "x" if it exists, otherwise the value of "y" if it exists, and so on, returningempty if none of them exist.
Note: The example uses the prefix "path"instead of "wpath" as in the previous examples.
The above rule can be further enhanced to return a pre-determined value if none of the cells exists:
first(path "x" value, path "y" value, path "z" value, 100).
Another use case for this function is to bypass a path uniqueness warning as explained below:
For example, take a rule that applies to table cells.
Rule contents:
value path "s" value
Path alias "s" defined as:
../../row/[(wild(@name,"row1_*"))]/ /cell[(@column='c')]
Given this rule the gateway will produce a validation warning saying path "s" is not uniquely specified as itcan potentially matchmultiple cells (as row1_* can theoretically matchmultiple rows). However, if it'sknown by the user that at runtime there will only ever be at most a single row that matches the patternrow1_*, then the rule can be changed as follows:
value first(wpath "s" value)
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 71 of 141
This rule will not produce the samewarning as by saying wpath we are explicitly declaring the path canmatchmultiple items and then asking the gateway to take the first match.
Note: You cannot use a historical path (i.e. path "p" value for "period") as a parameter to thisfunction.
PersistenceThe compute engine component of the gateway adds value tomonitoring data, by allowing the publishingof additional data-items which contain derived (computed) values. Some of these values may becomputed from historical data, such as an average value over a period of time.
The persistence feature of compute engine ensures that if the gateway is restarted for some reason, thenthese values are restored and that the data required to perform a computation is still accessible.
Persistence Configuration
persistenceThis top level section contains the configuration necessary for data persistence. If this section is notenabled, then no persistence data will be saved between gateway restarts.
persistence > writePeriodThis is the frequency in seconds in which the persistence store will be updated. The update is a differencebetween what was stored before and what has changed.
Mandatory: NoDefault: 10.
persistence > rewritePeriodThis is the frequency in seconds with which the persistence store will be completely rewritten. A rewrite ofa persistence store that has grown over time will most likely result in a smaller file.
Mandatory: NoDefault: 60.
Actions
IntroductionActions provide further processing to be performed on gateway events, as controlled by a user-definedconfiguration. At present, events which can trigger an action are currently limited to rules but may beextended at a later date.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 72 of 141
Actions allow the gateway to interface with other external systems, so that monitoring data can triggerother events in addition to being displayed in ActiveConsole. For instance using actions gateway can sendemails or pager messages to inform users of events, or add a failure to a user-assignment system to beinvestigated.
Actions can also be used to automatically resolve problems. For example, an action could be configured torestart a process when it is detected the process is not running (e.g. by Geneos process monitoring), andif this fails then the action can notify a user.
OperationActions are fired in response to gateway events, according to the configuration. When an action is fired itis run in the context of the specific data-item which caused the event, such as aManaged Variable thattriggered a rule.
The value and other attributes of this item are thenmade available to the action, which allows for an actionto have a customised operation depending upon these values. Depending upon the type of action beingfired, the values will be passed to the action in different ways. Please refer to the appropriate actionconfiguration section for further details.
Values passed to actions include the following:
l Data identifying the data-item and action being fired.
l If the data-item is from a dataview table, then additional values from the dataview row.
l Any managed entity attributes which have been configured.
l Additional user data as configured in an environment.
l A list of knowledge-base articles which apply to the data-item.
Action Configuration
Basic ConfigurationActions are configured within the Actions top-level section of the gateway setup. Configuration consists ofa list of action definitions, which specifies what will be done when the action is fired. As actions arereferenced by name in other parts of the gateway setup, each actionmust have a unique name among allother actions to prevent ambiguity.
Script actionsA script action can run a shell-script or executable file. Theminimum required configuration for this type ofaction is the executable to run, the command-line (whichmay be empty, but must still be specified) andthe location to run this action.
Depending upon the configured runLocation, this action will run either on the Gateway or Netprobe hosts.Netprobe actions will run on the Netprobe containing the data-item that triggered the action, unless anotherNetprobe has been explicitly specified with the probe setting.
An action run on Netprobe requires that probe encoded password is specified in the probe configuration.If not specified, the Netprobe will return the error: "Remote Command not executed - invalid password". Ifthere is no password to configure, run the Netprobe with -nopassword flag to avoid this problem.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 73 of 141
For an action which executes on theGateway, the value of the exeFile setting is checked to ensure thatthe executable is accessible by the Gateway. If this is not the case, the Gateway will be unable to executethe action and a setup validation error is produced.
Note: This validation cannot be performed by actions which run on Netprobe.
When executing a script action, the script / executable being run is passed the values and attributes of thedata-item which triggered the action. These are passed in environment variables, which the script can thenread and respond as required. The environment variables which are passed are listed below. If there is aname clash, an item that is further down this list will take precedence over an item further up. For example,a userdata setting takes precedence over an entity attribute with the same name and the name of the ruletakes precedence over the value in a column namedRULE.
_ACTION
The name of the action being triggered.
_GATEWAY
The name of the gateway firing the action.
_VARIABLEPATH
The full gateway path to the data-item.
_NETPROBE_HOST
The hostname of the probe the data-item belongs to (if any). This value is provided for backwardscompatibility.
_PROBE
The name of the probe the data-item belongs to (if any).
_MANAGED_ENTITY
The name of themanaged entity the data-item belongs to (if any).
_SAMPLER
The name of the sampler the data-item belongs to (if any).
_DATAVIEW
The name of the dataview the data-item belongs to (if any).
_VARIABLE
Short name of the data-item if it is amanaged variable, in the form <!>name for headlines or row.col for tablecells. This value is provided for backwards compatibility.
<attribute name>
The values of any managed entity attributes which have been specified. Environment variables are namedwith themanaged entity attribute names, and the values contain the attribute values.
_PLUGINNAME
The plugin name of the sampler the data-item belongs to (if any).
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 74 of 141
_SAMPLER_TYPE
The type of the sampler the data-item belongs to (if any).
_SAMPLER_GROUP
The group of the sampler the data-item belongs to (if any).
_<column name>
The values of cells in the same row as the data-item, if it is amanaged variable. Environment variables arenamedwith the column name (prefixed with an underscore), and the values are the values of the cell in thatcolumn.
_ROWNAME
The row name of the dataview cell the data-item belongs to (if any).
_COLUMN
The column name of the dataview cell the data-item belongs to (if any).
_HEADLINE
The headline name of the dataview cell the data-item belongs to (if any).
_FIRSTCOLUMN
The name of the first column of the dataview the data-item belongs to (if any).
_RULE
The rule that triggered this action. This is the full path to the rule including the rule groups i.e. group1 >group 2 > rulename
_KBA_URLS
A list of application knowledge base article URLs, separated by newlines.
_SEVERITY
The data-item severity. One of UNDEFINED, OK,WARNING, CRITICAL orUSER.
_VALUE
The value of the dataview cell the data-item belongs to (if any).
_REPEATCOUNT
The number of times this action has been repeated for the triggering data-item.
rmTransactionId
The unique ID of the rule transaction with the current setup.
<user data>
Additional user data as configured in the rule which triggered the action. Environment variables are namedwith the configured name, and contain the user-specified value.
_HOSTNAME
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 75 of 141
Alias for _MANAGED_ENTITY, provided for backwards compatibility.
_REALHOSTID
Alias for _NETPROBE_HOST, provided for backwards compatibility.
See Appendix A for an example action script file. An example configuration using the setup editor isshown below.
Figure 12-1 Gateway Setup Editor - Script action configuration example
User assignment script actionsIn the authentication section of the set-up you can define actions for user assignment and unassignment ofitems. These actions have the following additional variables.
_ASSIGNEE_USERNAME
The name of the Geneos user assigned this item. The name is taken from the user definition in theauthentication section.
_ASSIGNER_USERNAME
The name of the Geneos user assigning this item to another. The name is taken from the user definition inthe authentication section.
_ASSIGNEE_EMAIL
The email address of the Geneos user assigned this item. The address is taken from the user definition inthe authentication section.
_COMMENT
The comment entered by the assigner of the item.
_PERIOD_TYPE
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 76 of 141
The period for which the item is assigned.
ManualAssigned to the user until unassigned.UntilOkAssigned until severity is OKUntil severity changes to specifiedAssigned until severity changed to one specified by assignerUntil severity changes from specifiedAssigned until severity changed from specified by assignerUntil a specific date / timeAssigned until a specific date / timeUntil severity changes to specified or until a specific date / timeAssigned until severity changed to one specified by assigner or aspecific date / time
Shared library actionsShared library actions execute functions from within a shared library. Library actions aremore versatilethan script actions since they can store state between different executions of an action, however they alsorequire more effort on behalf of the user to create.
Library actions currently only execute on the gateway, and require aminimum of the library file andfunction name to be configured. Like script actions, these settings name are checked by gateway duringsetup validation to ensure the function can be found, so that an invalid configuration is detectedimmediately rather than when the action is run.
Shared library functions must have the following prototype (similar to themain function of a basic Cprogram).
extern "C" int functionName(int argc, char** argv);
When a library action is executed, the values and attributes of the data-item which triggered the action arepassed to it. These are passed as an array of strings of the form NAME=VALUE in the argv parameter. Thenumber of values passed is given in the argc parameter. These variables are named as for script actionsabove.
See Appendix A for an example action shared library function. An example configuration using the setupeditor is shown below.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 77 of 141
Figure 12-2 Gateway Setup Editor - Shared library action configuration example
Command actionsCommand-type actions can run any command supported by gateway. These commands are referenced byname (as commands are uniquely named) and the configurationmust supply all arguments expected bythe command in order to be valid. The number and type of arguments expected will vary according to thecommand being referenced.
Arguments can be specified with a static value, a text value or a parameter value. A static value will havethe same value every time the action is executed. A text value will have variable value depending upon thevalues of the Geneos variables (evaluated to the command target data-item environment). The parametervalue configuration allows users to select a variable value, which will be populated from the data-itemwhich triggered the action similar to environment variables passed to script actions.
An example is shown below using the /SNOOZE:time command. This command snoozes a data-item for aspecified time period, and takes arguments as specified in the table below.
Index Description Argument Type (Default) Value
1 User comment User input: MultiLineString
2 Item severity XPath state/@severity
3 Snooze type Static time
4 Snooze duration User input: Float 24
5 Snooze units User input: Options Hours (3600 - default),minutes (60), days(86400).
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 78 of 141
Of the arguments listed three are user-input arguments - those at indexes 1, 4 and 5. To execute thecommand, these arguments must have values specified. For this command arguments 4 and 5 havedefaults specified, and so will take these values if they are not overridden.
Figure 12-3 Gateway Setup Editor - Command action basic configuration example
Figure 12-4 Gateway Setup Editor - Command action argument configuration example
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 79 of 141
Effect actionsEffect actions call gateway effects. Currently an effect merely duplicate the basic functionality of Script,Shared-library, and Command action types, but allows the same effect to be shared with Alerts.
Calling an effect will have exactly the same effect as calling the same type of action. I.e. there is nodifference from configuring a script action and configuring an action that calls a script effect.
Advanced FeaturesWhen an action is triggered, the action remains valid until it is cancelled by the system. While an action isvalid, it is eligible for execution, repetition or escalation as configured by the user.
In particular an action triggered by a rule will remain valid until the transaction in that rule is no longeractive. For example, the following sequence of events is quite common:
l The value of a variable changes to outside of the allowable range specified in a rule.
l The rule is triggered, and has an associated action. This action now becomes valid.
l The action remains valid until the variable value changes back to inside the allowablerange, at which point the action is then cancelled by the system.
A triggered action is linked to a particular triggering (which for rules is a specific transaction definition) for aparticular variable. For example, if the active transaction in a rule changes to a different transaction butwith the same action, then the current action will be cancelled and the new action triggered. Similarlydifferent data-items which trigger the same transaction of the same rule are considered distinct. Thecancellation of one triggered action for a particular variable will not cancel any other actions (except foractions in an escalation chain).
An action that remains valid for a period of time can be configured to repeat or escalate to another action.These are called repeating and escalating actions respectively. An action can be both repeating andescalating if required.
There are a number of situations where actions will be suppressed by default, such as the Gatewaystarting up (see Advanced Action Settings). In these cases, the initial action will not fire but any repeats orescalations will be scheduled and fire later if the action continues to be valid.
Repeating ActionsA repeating action is an action which repeats (i.e. runs again) after a configured time period, provided theaction remains valid for that time. When an action fires for the first time the _REPEATCOUNTenvironment variable (or equivalent for non-script type actions) has an initial value of 0. This value isincremented for each subsequent repetition.
Repeating actions could be used for example to inform users at regular intervals that a problem still exists,or attempt to fix a problem (e.g. restart a process) before escalating if unsuccessful.
An example configuration for a repeating action is shown below. This action will repeat every 2minutes(120 seconds) until the action is no longer valid.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 80 of 141
Figure 12-5 Gateway Setup Editor - Repeating action configuration example
Escalating ActionsAn escalating action is an action which triggers another action. Each action can be optionally configuredwith one action to escalate to, which is called the escalation action. A valid action will fire this escalationaction once it has been valid for the configured escalation interval, after which is will not escalate again(contrast this with a repeating action which repeats every interval).
Escalation actions are useful for situations where the same action cannot resolve the issue (unlikerepeating actions). For example, an error condition could trigger an action which fires an email. If this erroris not then rectified within the escalation interval (perhaps because a technician is away from their deskunable to receive email) the action could then escalate to fire a pager message.
When an escalation action is triggered an "escalation chain" is formed, with a link from the triggering actionto the escalation action. E.g. if action A escalates to (fires) action B, then the chain is A -> B. If action Bthen escalates to action C, the chain becomes A -> B -> C.
The chain only remains valid so long as all actions in the chain are valid. If an action in the chain isinvalidated then actions in the chain are reset. Typically, it is the first action in the chain which isinvalidated, normally due to a rule transaction changing when a dataview value changes.
In the case of the example above, action A would be invalidated causing actions B and C to be invalidatedalso. Supposing action A is once again fired, then after the escalation interval expired action B would befired, since A had been reset.
When configuring escalating actions, it is a checked error to form a cycle of escalations. For instance, it isinvalid to configure an action A, which escalates to action B (escalation A -> B), and also configureescalations B -> C and C -> A. This is because it would cause a cyclic escalation chain (e.g. A -> B -> C -> A), meaning the actions would escalate indefinitely in an infinite loop. Gateway will resolve this byremoving the last detected escalation during setup validation - in this case the escalation C -> A - as wellas issuing a setup validationmessage.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 81 of 141
An example configuration is shown below. In this example, action escalatingAction escalates to actionmyScriptAction after 10minutes (600 seconds).
Figure 12-6 Gateway Setup Editor - Escalating action configuration example
Restricted ActionsActions can be configured with restrictions which will prevent them from firing, depending upon thecondition of the data-item that the action is fired with. Currently conditions which can be checked includethe snooze and active state of the data-item or parent items. For restrictions configured with multiplerestrictions, the action will fire only if none of the restrictions apply.
Specifying a restriction on items can help prevent unwanted actions from firing. Snoozing is typically usedto ignore an error while it is being investigated, whereas active state changes based on an active time.Depending upon the action, it may be helpful to ignore a condition if either of these conditions is true. Sincethis is a common activity, these are the default restrictions for actions.
For example an action which sends emails could be restricted to firing only if an item is not snoozed, sinceif the item is snoozed someone is investigating the problem. Similarly an action which restarts a processcould be restricted to firing only if an item is active, since the process may not be required outside of theactive time specified.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 82 of 141
Figure 12-7 Gateway Setup Editor - Restricted action configuration example
The queueUntilUnrestricted setting controls what happens when an action which was triggered whilerestricted later has the restrictions lifted (e.g. is unsnoozed). If the action is still valid and this setting is setto true, then the action will then be fired and repeat / escalate as normal. Otherwise the action will remainun-fired until it is invalidated.
Active TimesActions can optionally reference an active time by name using the activeTime setting, allowing time-based control of an action. Similar to an inactivity restriction described above setting an active time willprevent the action from being fired if the time is inactive, however this applies to the entire action ratherthan the item the action is fired upon. See the section on active times for details on this gateway feature.
Using active times on an action can be useful for controlling common / shared actions whichmay be firedon several data-items, for which restrictions are not appropriate or which do not themselves have activetimes configured. For example, an active time could be configured on an action which emails users.Outside of office hours there will be nobody to respond to the alert, and so the action can be disabled atthese times.
The queueUntilActive setting controls what happens when an action which was triggered outside of anactive time later re-enters that time (i.e. becomes active). If the action is still valid and this setting is set totrue, then the action will then be fired and repeat / escalate as normal. Otherwise the action will remain un-fired until it is invalidated.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 83 of 141
Figure 12-8 Gateway Setup Editor - Active time action configuration example
Configuration SettingsActions are configured in the Actions top-level section of the gateway setup. Configuration consists of a listof action definitions, each of which contains theminimum required configuration for their type. Each actionis identified by a user-supplied name, whichmust be unique among all other actions to prevent ambiguity,as actions are referenced by name.
Grouping settingsactionsThe top-level actions section contains configuration for the actions feature of gateway. This consists of alist of action definitions, optionally grouped for easier management.
actions > actionGroupAction groups allow grouping of actions in the gateway setup, allowing for easier management of actions.Grouping has no effect on the function of an action.
actions > actionGroup > nameThe action group name is not used by gateway. It should be used to describe the purpose or contents ofthe actions in the group.
Mandatory: Yes
Common action settingsThe settings below are common to all types of action.
actions > actionAn action definition contains the configuration required for a single action. Theminimum configurationrequired will vary depending upon the type of action being configured.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 84 of 141
actions > action > nameActions are referenced by other parts of the gateway setup by name. In order to avoid ambiguity, actionsare required to have a unique name among all other actions.
Mandatory: Yes
actions > action > escalationActionActions can be configured with an optional escalation action. The escalation action will be fired if theaction remains valid for the escalationInterval. See the section on escalating actions for more details.
Mandatory: NoDefault: (no escalation action)
actions > action > escalationIntervalThe escalation interval controls how long (in seconds) an actionmust remain valid before its escalationaction is called (if configured). See the section on escalating actions for more details.
Mandatory: NoDefault: 300 (5minutes)
actions > action > repeatIntervalThe repeat interval controls how long (in seconds) an actionmust remain valid before it repeats (firesagain). See the section on repeating actions for more details.
Mandatory: NoDefault: Will not repeat
actions > action > activeTimeOptionally specifies an active time for this action. If the action is triggered outside of this time the actionwill not fire. Firingmay optionally be delayed until the time is entered again using the queueUntilActivesetting. For more details see the section regarding active times for actions.
Mandatory: NoDefault: (no associated active time - the action will always fire, subject to restrictions)
actions > action > queueUntilActiveThis Boolean setting allows the firing action to be deferred until the associated active time of an action isactive. For more details see the section regarding active times for actions.
Mandatory: NoDefault: false
actions > action > restrictionsRestrictions can be applied to an action to prevent the action from firing under certain conditions.Conditions currently include the snoozing / active state of the triggering data-item and action throttling.If multiple conditions are configured, the action will only fire so long as no restrictions aremet.
For more details see the restrictions section.
Mandatory: No
actions > action > restrictions > snoozingThe snoozing restriction can be used to prevent an action firing depending upon the snooze state of thedata-item which triggered the action. Allowable values are listed below:
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 85 of 141
Value Effect
alwaysFire The action is always fired, regardless of snooze state.
fireIfItemNotSnoozed The action is fired if the triggering data-item is notsnoozed.
fireIfItemAndAncestorsNotSnoozed The action is fired if the triggering data-item and all ofits ancestor data-items are not snoozed.
Mandatory: NoDefault: fireIfItemAndAncestorsNotSnoozed
actions > action > restrictions > inactivityThe inactivity restriction can be used to prevent an action firing depending upon the active state of thedata-item which triggered the action. Allowable values are listed below:
Value Effect
alwaysFire The action is always fired, regardless of active state.
fireIfItemActive The action is fired if the triggering data-item is active.
fireIfItemAndAncestorsActive The action is fired if the triggering data-item and all ofits ancestor data-items are active.
Mandatory: NoDefault: fireIfItemAndAncestorsActive
actions > action > restrictions > queueUntilUnrestrictedThis Boolean setting allows the firing action to be deferred until all the configured snoozing and inactivityrestrictions have been lifted.
Mandatory: NoDefault: false
actions > action > restrictions > throttleThis is a reference to a configured throttle. See Action Throttling.
Script action settingsThe settings below define a script type action.
actions > action > scriptScript type actions allow the gateway to run a shell-script or executable file in response to gatewayevents. See the script action section above for more details.
Mandatory: Yes (one of script, sharedLibrary, command or effect must be specified for an action)
actions > action > script > exeFileSpecifies the shell script or executable file which will be run when the action is fired. For script actionswhich run on gateway (configured using the runLocation setting) this parameter is checked at setupvalidation time to ensure that the file exists.
Mandatory: Yes
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 86 of 141
actions > action > script > argumentsThis setting specifies the command-line arguments which will be passed to the script or executable whenthe action is run.
Mandatory: Yes
actions > action > script > commandLineDeprecated: Use actions > action > script > arguments instead, which allows the inclusion of definedvariables.
This setting specifies the command-line arguments which will be passed to the script or executable whenthe action is run.
Mandatory: Yes (if the newer actions > action > script > arguments setting is not used instead)
actions > action > script > runLocationThe run location specifies where the action should be run. Valid values are detailed below.
Value Effect
gateway The action is run on the gateway.
netprobe The action is run on the netprobe from which thetriggering data-item came, unless this is overriddenusing the probe setting. An action run on Netproberequires that probe encoded password is specified inthe probe configuration.
Mandatory: Yes
actions > action > script > probeThis setting allows users to configure a specific netprobe to run the action on, when the action has beenconfigured to run on netprobes using the runLocation setting.
Mandatory: No
Shared library action settingsThe settings below define a shared library type action.
actions > action > sharedLibraryShared library type allow the gateway to run a function from a shared library in response to gatewayevents. See the shared library section above for more details.
Mandatory: Yes (one of script, sharedLibrary, command or effect must be specified for an action)
actions > action > sharedLibrary > libraryFileSpecifies the location of the shared library to use for this action. This setting is checked during setupvalidation to ensure that gateway can access this library.
Mandatory: Yes
actions > action > sharedLibrary > functionNameSpecifies the name of the shared library function to run, inside the library specified by the libraryFilesetting. This setting is checked during setup validation to ensure that this function exists within the sharedlibrary.
Mandatory: Yes
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 87 of 141
actions > action > sharedLibrary > runThreadedOptional Boolean setting specifying whether to run the shared library function within a thread or not.Running an action in a thread is slightly less efficient but is recommended for library actions which takesome time to complete, to ensure that execution does not interfere with normal gateway operation.
Note
Shared library functions using this setting whichmaintain state should be written to be thread-safe to avoid potential problems.
Mandatory: NoDefault: false
actions > action > sharedLibrary > staticParametersDefines static parameters which are always passed to the shared library function along with any valuesdefined by the action.
Mandatory: No
actions > action > sharedLibrary > staticParameters > staticParameter > nameName of static parameter. This must be unique, if a parameter of the same name is defined by the actionthen this setting will be overridden.
Mandatory: Yes
actions > action > sharedLibrary > staticParameters > staticParameter > valueValue of static parameter.
Mandatory: Yes
Command action settingsThe settings below define a command type action.
actions > action > commandCommand type actions allow the gateway to run an internal or user-defined command in response togateway events. See the command section above for more details.
Mandatory: Yes (one of script, sharedLibrary, command or effect must be specified for an action)
actions > action > command > refThis setting specifies which commandwill be executed when this command type action is fired.Commands are referenced using the unique command name.
Mandatory: Yes
actions > action > command > argsThis section allows the action to supply arguments to the command. If a command has any argumentswithout default values, then thesemust be specified so that the command can be run. This condition ischecked during setup validation.
Mandatory: No (unless the command has arguments without default values)
actions > action > command > args > argEach arg definition specifies a single argument to pass to the command.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 88 of 141
actions > action > command > args > arg > targetThe target setting specifies which argument in the command this definition applies to. Commandarguments are numbered from one. E.g. A target value of four means that the contents of this definition willbe supplied as the fourth argument to the specified command.
Mandatory: Yes
actions > action > command > args > arg > staticSpecifies a static value for the command argument. This value will be the same for all executions of thisaction.
Mandatory: Yes (mutually exclusive with text or parameter below)
actions > action > command > args > arg > textA variable argument value for the command. This can include static text or Geneos variables which will beevaluated to their respective values depending upon the target data-item the command is being executedon. Example: if a Geneos variable "OS" is defined with different values at 2 different Managed Entities, andthe command is run on both theseManaged Entities data-items, then both command instances will getdifferent value of "OS" depending upon theManaged Entity data-item it is being run on. The argument typeis singleLineStringVar and can consist of static data and/or any number of Geneos variables interleavedtogether with/without static data. E.g. "Host:$(OS)-$(VERSION)" where "OS" and "VERSION" are 2 pre-definedGeneos variables. Currently only the following variables values can be properly converted tostring:
Variable Type Value
boolean "true" is checked, "false" otherwise
double The actual double value specified
integer The actual integer value specified
externalConfigFile The name of an external configuration file.
macro The value of the macro selected - gateway name orgateway port or managed entity name or probe hostor probe name or probe port or sampler name.
Mandatory: Yes (mutually exclusive with static or parameter below)
actions > action > command > args > arg > stdAESA secure password type for commands that take password arguments.
actions > action > command > args > arg > parameterSpecifies a parameterised value for the command argument. This value is obtained from the data-itemwhich triggered the action, and so can change on every execution. Possible values are listed below.
Value Effect
action The name of the action being triggered.
severity The data-item severity. One of UNDEFINED, OK,WARNING, CRITICAL or USER.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 89 of 141
Value Effect
variablePath The full gateway path to the data-item.
gateway The name of the gateway firing the action.
probe The name of the probe the data-item belongs to (ifany).
probeHost The hostname of the probe the data-item belongs to(if any). This value is provided for backwardscompatibility.
managedEntity The name of the managed entity the data-itembelongs to (if any).
sampler The name of the sampler the data-item belongs to (ifany).
dataview The name of the dataview the data-item belongs to (ifany).
variable Short name of the data-item if it is a managedvariable, in the form <!>name for headlines or row.colfor table cells. This value is provided for backwardscompatibility.
repeatCount The number of times this action has been repeatedfor the triggering item.
Mandatory: Yes (mutually exclusive with static above)
Effect action settingsThe settings below define a command type action.
actions > action > effectEffect type actions call a gateway effect. See the effects section below for more details.
Mandatory: Yes (one of script, sharedLibrary, command or effect must be specified for an action)
actions > action > effect > refThis setting specifies which effect will be called when this effect type action is fired. Effects arereferenced using the unique effect name.
Mandatory: Yes
Advanced action settingsThese settings can be found on the advanced tab of the Gateway Setup Editor.
actions > fireOnComponentStartupActions may be fired when a gateway or netprobe is first started.
Mandatory: NoDefault: false
actions > fireOnConfigurationChangeActions may be fired following a change of the gateway configuration file.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 90 of 141
Mandatory: NoDefault: false
actions > fireOnCreateWithOkSeverityActions may be fired as the result of a dataview item being created and transitioning from undefined to OKseverity.
Mandatory: NoDefault : False
actions > escalateIfFiringSuppressedActions may be escalated on component startup or configuration change or on dataview item beingcreated with OK severity only if original action is also firing on those conditions. If the original action issuppressed for these reason(s), then escalation will also be suppressed for same reason(s). If firing ofaction is not suppressed for any reason, then action will always be escalated and this setting will have noeffect.
Mandatory: NoDefault : True
Action ThrottlingIn a number of scenarios it is necessary to throttle the actions that occur, so that some of them are notsent. To do this a throttle needs to be defined and referenced from the restriction settings of an action.
Gateway2 allows you to configure rolling throttles to restrict the number of actions. With a rolling throttle itis possible to say only allow one of these actions to be fired within twenty four hours or five actions withina fiveminute period.
Throttles can be applied to actions through configuration or as part of a rule's transaction. When part of atransaction it overrides an existing throttle.
A throttle can fire a summary action at configurable periods. This action could be used to send an email ortext message summarising the number of actions throttled since the first action was fired or the first actionwas blocked, then subsequently since the last summary was sent. Naturally if no actions were throttledduring this period no summary is sent.
The summary action has the following information set in the environment.
l _SEVERITY
"UNDEFINED"
l _MANAGED_ENTITY
"UNDEFINED"
l _NETPROBE_HOST
"UNDEFINED"
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 91 of 141
l _VARIABLE
"THROTTLER"
l _VALUE
The number of throttled actions
l _THROTTLER
The name of the throttle
l _USERDATA
is not set
This ensures that existing Gateway throttling scripts can be reused without change. New scripts will beable to identify the throttle responsible.
Basic Configuration
Figure 12-9 Gateway2 Setup Editor - Example Throttle Configuration
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 92 of 141
Figure 12-10Gateway2 Setup Editor - Example Throttle Advanced Configuration
actions > throttle > nameThis is a name to uniquely identify the throttle.
Mandatory: Yes
actions > throttle > noOfActionsThis is the number of actions allowed before throttling.
Mandatory: Yes
actions > throttle > perThis is the number of time units used to define throttling duration. For example if you were setting a throttleof one action per tenminute interval. It would be "10".
Mandatory: Yes
actions > throttle > intervalThis is the time interval in use seconds, minutes or hours, allowing the throttle to be defined in number ofactions per interval.
Mandatory: Yes
Configuring GroupingGroupings allow a throttle to keep different counters for different logical groups. Each group is defined by acollection of XPaths which are evaluated when the action is fired. There is also a default group to throttleitems that do not match the grouping criteria.
The result of evaluating each of these XPaths are gathered together to uniquely identify the throttlinggroup.
Note: To be part of a group all of the grouping criteria must bemet. If the grouping criteria arenot all met the default group will be used.
Examples
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 93 of 141
Throttling per dataview.
ancestor::dataview
This will evaluate to the dataview of the data-item that triggered the action. Effectively defining separatethrottling for each dataview as the throttle is applied.
If you have FKM andCPU dataviews triggering actions they would each fire up actions up to theconfigured limited within the configured time period.
Throttling separately for one specific plugin.
ancestor::dataview[@name="cpu"]
This will throttle actions triggered by dataviews named "cpu" separately to all other actions to which thethrottle is applied. There is an implicit default throttle for data-items that do not belong to a configuredgroup.
Throttling by row for one specific plugin.
ancestor::sampler[(param("PluginName")="FKM")]/dataview@rowname
This will throttle actions triggered by each row of an FKM dataview separately. This is useful for throttlingactions on columns like status, where the value is associated with the file. It is not useful for throttlingtrigger rows as these should all be throttled together.
Note: There are two XPaths. Both have to be satisfied. This effectively defines a group foreach row of the FKM dataview. When the action is fired the questions asked are "Is this partof the FKM dataview?" and "which row does it belong to?"
Throttle each data item separately
.
(dot) The current data-item; Throttle every data-item separately.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 94 of 141
Throttling by set of plugin types.
ancestor::dataview[@name="disk"]/ancestor::managedEntityancestor::dataview[@name="cpu"]/ancestor::managedEntityancestor::dataview[@name="network"]/ancestor::managedEntityancestor::dataview[@name="hardware"]/ancestor::managedEntity
This will throttle "system" actions together in one group.
Throttling by fkm dataviews per filename.
ancestor::sampler[(param("PluginName")="FKM")]/dataview../cell[(@column="filename")]/@value
This will throttle actions triggered by each fkm file from each fkm dataview seperately. Actions fired fromcells associated with the same filenamewill be throttled into the same group.
Valid Grouping PathsYoumay receive a warning about parts of a configured grouping path not uniquely identifying a gatewayitem. Going in an upward direction (i.e. ancestor or "...") this is ok and will not generate a warning. Theproblem occurs when going "downwards", let's say your XPath is defined as:
ancestor::probe[@name="Holly"]//sampler
The intention being to throttle actions for all samplers on that probe. This will work for a while, untilsamplers are added or taken away from the probe. When the next action is fired the set of active samplerswill be different to the previous set. This will lead to the action being throttled by a different group. Thisprobably isn't the intended behaviour and is why the gateway issues a warning.
If the configured XPath were simply:
ancestor::probe[@name="Holly"]
This would throttle every action originating from that probe.
actions > throttle > groupingGroupings allow a throttle to keep different counters for different logical groups.
Mandatory: No
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 95 of 141
actions > throttle > grouping > pathsGroupings allow a throttle to keep different counters for different logical groups. Each group is defined by acollection of XPaths which are evaluated when the action is fired. See XPaths - User Guide for moreinformation on XPaths.
Mandatory: No
actions > throttle > grouping > paths > pathGroupings allow a throttle to keep different counters for different logical groups. Each group is defined by acollection of XPaths which are evaluated when the action is fired. There is also a default group to throttleitems that do not match the grouping criteria.
See the Configuring Grouping section for more information. See theGrouping section for moreinformation.
Mandatory: No
Summarising Throttling
actions > throttle > summaryDefines when summary actions should be fired.
Mandatory: No
actions > throttle > summary > sendThis is the number of time units after which the summary action should be fired.
Mandatory: Yes
actions > throttle > summary > intervalThis is the time interval in use seconds, minutes or hours.
Mandatory: Yes
actions > throttle > summary > strategyWhich strategy should be used? Fire the action a configured time after the first allowed action or aconfigured time after the first blocked action.
Mandatory: Yes
actions > throttle > summary > actionThe summary action that should be fired.
Mandatory: Yes
Action examples
ScriptAn example UNIX script which accesses action parameters is shown below.
#!/bin/sh
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 96 of 141
echo _ACTION = ${_ACTION}cho _SEVERITY = ${_SEVERITY}echo _VARIABLEPATH = ${_VARIABLEPATH}echo _GATEWAY = ${_GATEWAY}echo _PROBE = ${_PROBE}echo _NETPROBE_HOST = ${_NETPROBE_HOST}echo _MANAGED_ENTITY = ${_MANAGED_ENTITY}echo _SAMPLER = ${_SAMPLER}echo _DATAVIEW = ${_DATAVIEW}echo _VARIABLE = ${_VARIABLE}echo _REPEATCOUNT = ${_REPEATCOUNT}
An equivalent Windows batch file is as follows:
@echo off
echo _ACTION = %_ACTION%echo _SEVERITY = %_SEVERITY%echo _VARIABLEPATH = %_VARIABLEPATH%echo _GATEWAY = %_GATEWAY%echo _PROBE = %_PROBE%echo _NETPROBE_HOST = %_NETPROBE_HOST%echo _MANAGED_ENTITY = %_MANAGED_ENTITY%echo _SAMPLER = %_SAMPLER%echo _DATAVIEW = %_DATAVIEW%echo _VARIABLE = %_VARIABLE%echo _REPEATCOUNT = %_REPEATCOUNT%
Multi Line Variables In ActionsOutputtingmulti linemessages stored in environment variables are not supported by any of the built-inecho commands forWindows, Solaris and Linux. To work around this issue you could use the followingexamples to output multi linemessages from an environment variable.
WindowsVBScript has been used for this example as it is present inWindows 2000 and up.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 97 of 141
Option Explicit
Dim objWindowsShellDim objEnvironmentSet objWindowsShell = WScript.CreateObject("WScript.Shell")For Each objEnvironment In objWindowsShell.Environment("PROCESS")WScript.Echo objEnvironmentNextSet objWindowsShell = Nothing
Solaris
Note: The " marks are necessary around the variable to interpret it as amulti-line string.
#!/bin/sh
/usr/bin/echo _ACTION = "${_ACTION}"/usr/bin/echo _SEVERITY = "${_SEVERITY}"/usr/bin/echo _VARIABLEPATH = "${_VARIABLEPATH}"/usr/bin/echo _GATEWAY = "${_GATEWAY}"/usr/bin/echo _PROBE = "${_PROBE}"/usr/bin/echo _NETPROBE_HOST = "${_NETPROBE_HOST}"/usr/bin/echo _MANAGED_ENTITY = "${_MANAGED_ENTITY}"/usr/bin/echo _SAMPLER = "${_SAMPLER}"/usr/bin/echo _DATAVIEW = "${_DATAVIEW}"/usr/bin/echo _VARIABLE = "${_VARIABLE}"/usr/bin/echo _REPEATCOUNT = "${_REPEATCOUNT}"/usr/bin/echo _VALUE = "${_VALUE}"
Linux
#!/bin/sh
/bin/echo _ACTION = "${_ACTION}"/bin/echo _SEVERITY = "${_SEVERITY}"/bin/echo _VARIABLEPATH = "${_VARIABLEPATH}"/bin/echo _GATEWAY = "${_GATEWAY}"/bin/echo _PROBE = "${_PROBE}"/bin/echo _NETPROBE_HOST = "${_NETPROBE_HOST}"
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 98 of 141
/bin/echo _MANAGED_ENTITY = "${_MANAGED_ENTITY}"/bin/echo _SAMPLER = "${_SAMPLER}"/bin/echo _DATAVIEW = "${_DATAVIEW}"/bin/echo _VARIABLE = "${_VARIABLE}"/bin/echo _REPEATCOUNT = "${_REPEATCOUNT}"/bin/echo _VALUE = "${_VALUE}"
Shared libraryShared library actions aremore powerful than script or executable actions. This is because shared libraryactions can store state information between invocations of the action, since the library is loaded as a partof gateway and will remain loaded until removed from the gateway configuration.
Gateway can call any function within the library with the correct function signature, which is displayedbelow:
extern "C" int functionName(int, char**);
When called, the function will be passed the number of variable strings in the first parameter, and an arrayof null-terminated strings in the second parameter, each string of the form NAME=VALUE. The return valueis only reported to the gateway log and not used otherwise.
#include <stdio.h>
extern "C" int logAction(int argc, char* argv[]){for (int ix = 0; ix < argc; ++ix){printf("%s\n", argv[ix]);}return 0;}
The example above can be saved to a file (e.g. logAction.cpp) and compiled with the following commandon a Linux system. This produces the library file logAction.so which contains the function logAction.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 99 of 141
g++ logAction.cpp -fpic -Wl,-G -shared -o logAction.so
Libemail
OverviewThe gateway is packaged with a shared library called libemail.so that provides simple SMTP mailfunctionality. It has one exported function SendMail that sends an e-mail via a configured SMTP server.Values are passed into the function using theNAME=VALUE syntax described above and can be set usingthe shared library static parameters settings or from Action user data. Any issues encountered whilerunning are output to stderr.
The library works by having a set of predefined formats (you can think of these as templates) which can beoverridden. The format contains the text of themessage that would be sent when the action is triggered.
The template can contain a number of macros that are substituted when the%(NAME_OF_MACRO) isfound in the text of the the format. Somemacros are defaulted for you and listed in the configurationsection below. The default message formats can be overridden by setting a static parameter with thesame name and supplying the new text. Message formats are listed in themessage format section below.
You can define any macro name you want and use these in your message format. However in addtition thelibrary will be supplied with a number of pre-configuredmacros which are defaulted with useful or defaultsettings. These can be overridden in the static parameters section of the actions configuration.
ConfigurationTo configure libemail set up a sharedLibrary-type action or effect with the libraryFile set to libemail.so andthe functionName set to SendMail. For Alerting this is theminimum set-up required, although typicallyusers will want to specify a server (_SMTP_SERVER) and the return path and name (_FROM and _FROM_NAME). When using the library from an action it will also be necessary to set the _TO field in the user data.
All supported configuration parameters are listed below:
Parameter Effect
_SMTP_SERVER Address of SMTP server to connect to (defaults tolocalhost).
_SMTP_PORT Port of SMTP server (defaults to 25)
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 100 of 141
Parameter Effect
_SMTP_TIMEOUT Timeout value for communications between the
SMTP server and the library. Specifies how long the
library should wait for each interaction with the SMTP
server. e.g. connect, reads and writes. The time is for
each operation and not the overall time.
The time is specified as <seconds.microsections>
e.g. 1.500 which states one second and 500
microseconds.
The default is zero which means wait indefinitely or
until the system timeout (implementation dependent).
_FROM Return path e-mail address (defaults togeneos@localhost)
_FROM_NAME Return path name (defaults to Geneos)
_FORMAT Format of mail message (default below)
_ALERT_FORMAT Format of alert-type Alert mail message (defaultbelow)
_CLEAR_FORMAT Format of alert-type Clear mail message (defaultbelow)
_SUSPEND_FORMAT Format of alert-type Suspend mail message (defaultbelow)
_RESUME_FORMAT Format of alert-type Resume mail message (defaultbelow)
_SUMMARY_FORMAT Format of alert-type ThrottleSummary mail message(default below)
_SUBJECT Subject of mail message (defaults to "Geneos Alert")
_ALERT_SUBJECT Subject of alert-type Alert message (defaults to"Geneos Alert Fired")
_CLEAR_SUBJECT Subject of alert-type Clear message (defaults to"Geneos Alert Cancelled")
_SUSPEND_SUBJECT Subject of alert-type Suspend message (defaults to"Geneos Alert Suspended")
_RESUME_SUBJECT Subject of alert-type Resume message (defaults to"Geneos Alert Resumed")
_SUMMARY_SUBJECT Subject of alert-type ThrottleSummary message(defaults to "Geneos Alert Throttle Summary")
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 101 of 141
Parameter Effect
_TO Comma delimited message of recipient addresses.This has no default and must be set (the Alertingfunctionality of the gateway will set it automatically,along with the CC and BCC lists, and associated infotypes and names)
_TO_INFO_TYPE Corresponding comma delimited list of recipientinformation types. Addresses that do not havecorresponding information types matching "Email" or"e-mail" (case insensitive) will be excised from thelist. This list must be the same length as the _TO list ifit is provided. (If it is absent then all addresses areassumed to be e-mail addresses).
_TO_NAME Corresponding comma delimited list of recipientnames. If present, this list must be the same length asthe _TO list.
_CC As with _TO but for Carbon Copy address list.
_CC_INFO_TYPE As with _TO_INFO_TYPE but for Carbon Copyaddress list.
_CC_NAME As with _TO_NAME but for Carbon Copy address list.
_BCC As with _TO but for Blind Carbon Copy address list.
_BCC_INFO_TYPE As with _TO_INFO_TYPE but for Blind Carbon Copyaddress list.
_BCC_NAME As with _TO_NAME but for Blind Carbon Copyaddress list.
Note: You will see below a number of message formats which useGateway supplied
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 102 of 141
parameters such as %(_VALUE), %(_SEVERITY) and%(_ASSIGNEE_EMAIL) which ispopulated for events triggered by user assignment. You can useGateway suppliedparameters such as these in your configuration options above. This allows you to tailor thesubject, addressing etc.
Note: Youmay also use your ownmacro names in your ownmessage formats.
Message FormatsIf an _ALERT parameter is present libemail assumes it is being called as part of a gateway alert and willuse the appropriate format depending on the value of _ALERT_TYPE (Alert, Clear, Suspend, or Resume). Ifno _ALERT parameter is specified libemail assumes it is being called as part of an action and uses _FORMAT.
A user defined format will always override the default format. If the _FORMAT parameter is specified by theuser then this will override any default formats whether or not _ALERT is present.
Subjects behave in the sameway as formats.
Formats and subjects have a simple parameter expansion capability using the%(<name>) syntax. E.g. %(_ALERT) will expand to the name of the alert.
Default _FORMAT
This is an automatically generatedmail from Geneos Gateway: %(_GATEWAY)
Action "%(_ACTION)" is being fired against Geneos DataItem%(_VARIABLEPATH)
The dataitem value is "%(_VALUE)" and its severity is %(_SEVERITY)
Default _ALERT_FORMAT
This is an automatically generatedmail from Geneos Gateway: %(_GATEWAY)
Alert "%(_ALERT)" is being fired becauseGeneos DataItem%(_VARIABLE) in dataview %(_DATAVIEW) inManaged Entity %(_MANAGED_ENTITY) is at %(_SEVERITY) severity.
The cell value is "%(_VALUE)"
This Alert was created at %(_ALERT_CREATED) and has been fired%(_REPEATCOUNT)times.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 103 of 141
The item's XPath is %(_VARIABLEPATH)
This alert is controlled by throttle: "%(_THROTTLER)".
The default _ALERT_FORMAT also lists the values of all matched alert levels.
Default _CLEAR_FORMAT
This is an automatically generatedmail from Geneos Gateway: %(_GATEWAY).
Alert "%(_ALERT)" is being cancelled becauseGeneos DataItem%(_VARIABLE) in dataview%(_DATAVIEW) inManaged Entity %(_MANAGED_ENTITY) is at %(_SEVERITY) severity.
The cell value is "%(_VALUE)"
This Alert was created at %(_ALERT_CREATED) and has been fired%(_REPEATCOUNT)times.
The item's XPath is %(_VARIABLEPATH)
This alert is controlled by throttle: "%(_THROTTLER)".
The default _CLEAR_FORMAT also lists the values of all matched alert levels.
Default _SUSPEND_FORMAT
This is an automatically generatedmail from Geneos Gateway: %(_GATEWAY).
Alert "%(_ALERT)" is being suspended because of: "%(_SUSPEND_REASON)". No noti-fications will be fired for this alert until it is resumed. If the alert is cancelled before it is resumedno further notifications will be fired.
The cell value is "%(_VALUE)"
This Alert was created at %(_ALERT_CREATED) and has been fired%(_REPEATCOUNT)times.
The item's XPath is %(_VARIABLEPATH)
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 104 of 141
This alert is controlled by throttle: "%(_THROTTLER)".
The default _SUSPEND_FORMAT also lists the values of all matched alert levels.
Default _RESUME_FORMAT
This is an automatically generatedmail from Geneos Gateway: %(_GATEWAY).
Alert "%(_ALERT)" is being resumed because of: "%(_RESUME_REASON)". GeneosDataItem%(_VARIABLE) in dataview %(_DATAVIEW) inManaged Entity %(_MANAGED_ENTITY) is %(_SEVERITY) severity.
The cell value is "%(_VALUE)"
This Alert was created at %(_ALERT_CREATED) and has been fired%(_REPEATCOUNT)times.
The item's XPath is %(_VARIABLEPATH)
This alert is controlled by throttle: "%(_THROTTLER)".
The default _RESUME_FORMAT also lists the values of all matched alert levels.
Default _SUMMARY_FORMAT
This is an automatically generatedmail from Geneos Gateway: %(_GATEWAY)
Summary for alert throttle "%(_THROTTLER)"%(_VALUE) Alerts have been throttled in the last %(_SUMMARY_PERIOD), including:%(_DROPPED_ALERTS) Alert(s)%(_DROPPED_CLEARS) Clear(s)%(_DROPPED_SUSPENDS) Suspend(s%(_DROPPED_RESUMES) Resume(s)
The default _SUMMARY_FORMAT also lists all current alerts controlled by the throttle.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 105 of 141
Alerting
OverviewThe Alerting feature of gateway automatically notifies users when a cell severity goes toWarning orCritical. It is completely removed from the rule logic that sets the cell severity and can instead issue alertsbased on arbitrary criteria such as system or server location.
Alerts are configured in hierarchies trees based on the properties of the item being alerted on. A hierarchyhas a defined set of levels specifying what property to match on. Properties can be part of the geneosdirectory structure (e.g. plug-in or sampler) or a user definedmanaged entity attribute (e.g. COUNTRY orCITY). Alerts can be defined at any level of a hierarchy.
When the severity on a cell changes toWarning or Critical the Alert Manager walks down the hierarchymatching the cell properties at each level. If a matching alert is found it is fired.
Alerts can vary in complexity. A 'Show Alerts' command, run by right clicking on any cell, will show theAlerts that would fire were a severity change to occur.
HierarchiesA hierarchy tree has a set depth, with each level defined as matching to a particular data-item parameter.The following parameter types are available:
Parameter Meaning
Managed Entity Parameter A user defined managed entity parameter (e.g.COUNTRY).
Managed Entity Name The name of the managed entity.
Row Name The table row name of the cell.
Column Name The table column name of the cell.
Headline Name The name of the headline.
Dataview Name The name of the dataview.
Sampler Name The name of the sampler.
Sampler Type The type of the sampler.
Sampler Group The group of the sampler.
Plug-In Name The name of the plug-in.
The tree can be formed of any number of branches, not descending below the defined levels. Every branch(or alert level) has a name value which is matched to its corresponding level match parameter, i.e. if thefirst level has amatch parameter of pluginName then all level one branches will have namescorresponding to different plugins. Matching is exact (wildcards are not supported) and case sensitive.There is no need to provide alert levels for every possible value.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 106 of 141
Each alert level can define both warning and critical notifications. When a dataview cell's severity ischanged to warning or critical, the cell is compared against the hierarchy, the Alert Manager walks downthematching alert levels and themost specific (bottommost) notification found is fired. Less specificnotifications further up the tree can also optionally be fired.
Any number of hierarchies can be created. Default behaviour is to fire a single notification from everymatching hierarchy, but hierarchies have priorities and it is possible to configure only the highest prioritymatching alert to fire.
NotificationsAt each alert level, notifications can be defined for warning and critical severity. Notifications are specifiedin an escalation ladder, if the alert is still valid after the escalation interval the next escalation level is fired.Each notification can fire multiple effects to separate distribution lists, each with its own repeat interval.
Distribution ListsEach notification effect has three distribution lists: To, CC (Carbon Copy), and BCC (Blind Carbon Copy).When adding a user or user-group to a distribution list the information type to add can be specified, thiscorresponds to the generic user information defined in the Authentication Technical Reference. Bedefault this will be "Email" but any information can be specified and passed to the effect, and because aneffect can be a user defined script any information can be interpreted.
EffectsWhen a notification fires it calls an effect (as defined in the effects section), passing it information aboutthe alert, the distribution lists, and about the data-item the alert has been created for.
Variables Passed To EffectThe following variables are passed to the called effect. The exact form in which they are passed willdepend on the type of effect.
Alert information_ALERT
The name of the alert, this is formed of the hierarchy name, the name of each alert level, the severity, andthe level down the escalation chain: e.g. for a hierarchy matching on plugin name and row name:myHeirarcy/FKM/myFile.txt/WARNING/0
_ALERT_CREATED
The time the alert was created.
_ALERT_TYPE
The type of alert being fired, this can be one of five values: Alert, Clear, Suspend, Resume, orThrottleSummary. See below for more details on Suspend and Resume alerts.
_CLEAR
Whether or not this alert is a clear.
_SUSPEND_REASON
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 107 of 141
Only present for Suspend alerts. The reason why the alert is being suspended.
_RESUME_REASON
Only present for Resume alerts. The reason why the alert is being resumed.
_HIERARCHY
The name of the hierarchy
_HIERARCHY_LEVEL
The hierarchy level on which the alert was fired (depth down the tree). Zero biased.
_LEVEL_<level>
Thematching parameter of the hierarchy level (e.g._ROWNAME). Level is zero biased.
_MATCHED_<level>
Thematching parameter of the hierarchy level in a human readable form (e.g. rowName)
_THROTTLER
Name of the throttle controlling this alert, blank if not throttled.
Data item information_SEVERITY
The data-item severity. One of UNDEFINED, OK,WARNING, CRITICAL orUSER.
_VALUE
Value of data-item
_VARIABLEPATH
The full gateway path to the data-item.
_GATEWAY
The name of the gateway firing the action.
_PROBE
The name of the probe the data-item belongs to
_NETPROBE_HOST
The hostname of the probe the data-item belongs to. This value is provided for backwards compatibilitywith old action scripts.
_MANAGED_ENTITY
The name of themanaged entity the data-item belongs to.
_SAMPLER
The name of the sampler the data-item belongs to.
_SAMPLER_TYPE
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 108 of 141
The type of the sampler the data-item belongs to.
_SAMPLER_GROUP
The group of the sampler the data-item belongs to.
_DATAVIEW
The name of the dataview the data-item belongs to.
_PLUGINNAME
The name of the plugin that created the dataview.
_ROWNAME
The name of the row the data-item belongs to (if any).
_COLUMN
The name of the column the data-item belongs to (if any).
_HEADLINE
The name of the headline (if the data-item is a headline).
_VARIABLE
Short name of the data-item if it is amanaged variable, in the form <!>name for headlines or row.col for tablecells. This value is provided for backwards compatibility with older action scripts.
_REPEATCOUNT
The number of times this notification has been repeated for the triggering data-item.
_FIRSTCOLUMN
The name of the first column of the dataview the data-item belongs to (if any).
_<column name>
The values of cells in the same row as the data-item. Environment variables are namedwith the columnname (prefixed with an underscore), and the values are the values of the cell in that column.
<attribute name>
The values of any managed entity attributes which have been specified. Environment variables are namedwith themanaged entity attribute names, and the values contain the attribute values.
_KBA_URLS
A list of application knowledge base article URLs, separated by newlines.
Distribution Lists_TO
Comma delimited list of message recipients, populated from the values in the user information in theauthentication section (e.g. [email protected], 12345678)
_TO_INFO_TYPE
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 109 of 141
Corresponding comma delimited list of information types. The effect can use this to treat each element inthe _TO list differently if necessary. (e.g. Email, Pager).
_TO_NAME
Corresponding comma delimited list of users full names, as specified in the authentication section. (e.g.Alan User, Alan User)
_CC
As with the _TO list, a comma delimited list of Carbon Copy recipients.
_CC_INFO_TYPE
As with the _TO_INFO_TYPE list, a comma delimited list of Carbon Copy recipient information types.
_CC_NAME
As with the _TO_NAME list, a comma delimited list of Blind Carbon Copy recipient names.
_BCC
As with the _TO list, a comma delimited list of Carbon Copy recipients.
_BCC_INFO_TYPE
As with the _TO_INFO_TYPE list, a comma delimited list of Blind Carbon Copy recipient informationtypes.
_BCC_NAME
As with the _TO_NAME list, a comma delimited list of Blind Carbon Copy recipient names.
libemailThe gateway ships with pre-built shared library called libemail.so designed to interpret alert or actionparameters and send e-mails using an SMTP server. See the appendix for more details.
Repeating NotificationsA repeating notification is a notification which repeats (i.e. is sent again) after a configured time period,provided the alert remains valid for that time. When a notification fires for the first time the _REPEATCOUNT environment variable (or equivalent for non-script type alert) has an initial value of 0.This value is incremented for each subsequent repetition.
Repeating notifications could be used for example to inform users at regular intervals that a problem stillexists. It is possible to set repeating notifications to cancel after the notification has escalated.
There are a number of situations where notifications will be suppressed by default, such as the Gatewaystarting up (see fireOnComponentStartup and fireOnConfigurationChange). In these cases, the initialaction will not fire but any repeats or escalations will be scheduled and fire later if the alert continues to bevalid.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 110 of 141
EscalationNotifications are configured in an escalation chain where each step on the chain has a separate escalationinterval (specified in seconds). If the alert is still valid (i.e. the problem has not been fixed) after theescalation interval has passed the next notification is fired.
ClearsA notification with clear set will be fired one final time when the triggering data-item's severity drops belowthe alert severity to inform the recipients that the alert has been cancelled. A clear notification is passedexactly the same variables as a normal notification except that _CLEAR will be set to TRUE and _ALERT_TYPE will be set toClear.
A data-item of severity Warning changing to Critical will not produce a clear for theWarning alert. The Alertis instead put on hold and when the data-item's severity eventually drops back below warning a clear willbe issued.
Severity Transition Example 1
l OK -> Warning
l WARNING alert fires. Repeats and escalations scheduled.
l Warning -> Critical
l WARNING alert repeats and escalations cancelled.
l CRITICAL alert fires. Repeats and escalations scheduled.
l Critical -> Warning
l CRITICAL alert repeats and escalations cancelled.
l CRITICAL clear fired.
l WARNING alert fires (at first escalation level and with a repeat count of 0).Repeats and escalations scheduled.
l Warning -> OK
l WARNING alert repeats and escalations cancelled.
l WARNING clear fired.
Severity Transition Example 2
l OK -> Warning
l WARNING alert fires. Repeats and escalations scheduled.
l Warning -> Critical
l WARNING alert repeats and escalations cancelled.
l CRITICAL alert fires. Repeats and escalations scheduled.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 111 of 141
l Critical -> OK
l CRITICAL alert repeats and escalations cancelled.
l CRITICAL clear fired.
l WARNING clear fired.
Suspended AlertsAlerts are suspended when either the alert hierarchy goes out of active time, the target cell becomesinactive (due to a rule activeTime), or the target cell is snoozed. When an alert is suspended it is put intospecial state where no notifications will be sent. If the Clear flag is set a single Suspend (_ALERT_TYPE=Suspend) notification is sent to inform the users that the Alert has been suspended and why (_SUSPEND_REASON).
If the alert is still valid (i.e. the target cell is still red/orange) once all three suspension criteria are no longermet, then the alert is resumed. A resumed alert has its escalation chain and repeat count reset. The veryfirst notification(s) sent will have _ALERT_TYPE set toResume and include an explanation of why the alerthas been resumed (_RESUME_REASON).
There are six possible reason why an alert can be suspended or resumed:
Reason Description
Hierarchy Active Time The hierarchy has gone in or out of active time.
Cell Active State The target cell has gone active or inactive.
Cell Snooze State The target cell has been snoozed or unsnoozed.
Ancestor Active State An ancestor of the target cell has gone active orinactive.
Ancestor Snooze State An ancestor of the target cell has been snoozed orunsnoozed.
Configuration Change The configuration specifying the activeTime orsnoozing/active state restrictions for this alert hasbeen altered.
The following examples illustrate the precise suspend and resume behaviour. They use the hierarchyactivetime but are equally valid for the snoozed and active state of the target cell.
Example 1: RepeatingRed triangles mark notifications that are fired, empty triangles mark point where notifications would havebeen fired but are not. Repeats stop while hierarchy is inactive and start again with a repeat count of zerowhen hierarchy goes active.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 112 of 141
Example 2: EscalationsAlert queued until active. Escalation chain begins only once active. Empty triangle does not fire an alertbut time stamp of when the cell severity changed is recorded and included in notification.
Example 3: Resetting EscalationsEscalation fires. First notification fires again once hierarchy goes active and escalation chain is restartedand escalation will fire again.
Example 4: ClearsClear (empty triangle) is not fired. Instead a Suspend notification is fired (yellow triangle).
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 113 of 141
Example 5: Cells Changing State While Alert Is SuspendedNo notifications are ever fired while the alert is suspended. When alert is resumed cell state is re-evaluated and notifications are restarted. Clear is later fired when cell state finally goes green.
Example 6: Intervals That Span Entire Suspended PeriodScheduled repeats and escalations are all cancelled when an alert is suspended. Even if the alert isresumed before they would have fired.
Active TimesAlert hierarchies can optionally reference an active time by name using the activeTime setting, allowingtime-based control of alerts. Setting an active time will suspend all alerts from that hierarchy, preventingthem from being fired while the time is inactive. Once the active time period resumes, and if the alert is stillvalid, it will fire and repeat / escalate as normal.
See the section on active times for details on this gateway feature.
For example, an active time could be configured on a hierarchy which emails users. Outside of office hoursthere will be nobody to respond to the notification, and so the alert can be disabled at these times.
Restricted AlertsAlert hierarchies can be configured with restrictions which will suspend them, depending upon thecondition of the data-item that the alert is fired on. Currently conditions which can be checked include thesnooze and active state of the data-item or parent items. For alerts configured with multiple restrictions,the alert will fire only if none of the restrictions apply.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 114 of 141
Specifying a restriction on items can help prevent unwanted alerts from firing. Snoozing is typically used toignore an error while it is being investigated, whereas active state changes based on an active time.Depending upon the alert, it may be helpful to ignore a condition if either of these conditions is true. Sincethis is a common activity, these are the default restrictions for alerts.
For example, an alert which sends emails could be restricted to firing only if an item is not snoozed, sinceif the item is snoozed someone is investigating the problem.
Alert ThrottlingIn a number of scenarios it is necessary to throttle alert notifications so that some of them are not sent. Todo this a throttle needs to be defined and referenced from the throttling section of an Alert or Hierarchy.
Gateway2 allows you to configure rolling throttles to restrict the number of notifications. With a rollingthrottle it is possible to say only allow one notification to be fired within twenty four hours or fivenotifications within a fiveminute period.
SummariesA throttle can fire a summary effect at configurable periods. This effect could be used to send an email ortext message summarising the number of alerts throttled since the first alert was fired or the first alert wasblocked, then subsequently since the last summary was sent. Naturally if no alerts were throttled duringthis period no summary is sent.
As alerts are throttled their distribution lists are collected and the summary effect is fired to the combineddistribution list of every user whomissed an alert controlled by that throttle.
Summary EffectThe summary effect has the following information set in the environment.
Alert information_ALERT
"UNDEFINED"
_ALERT_CREATED
Time and date at which summary is fired
_ALERT_TYPE
"ThrottleSummary"
_CLEAR
"FALSE"
_HIERARCHY
"UNDEFINED"
_HIERARCHY_LEVEL
"UNDEFINED"
_CURRENT_ALERTS
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 115 of 141
Number of currently valid alerts controlled by this throttle.
_CURRENT_ALERT_<index>
The name of the current alert. One for every currently valid alert controlled by this throttle.
_CURRENT_ALERT_HOLD_<index>
Whether or not the current alert is on hold (an alert of a higher severity has been raised against theDataItem). One for every currently valid alert controlled by this throttle.
_CURRENT_ALERT_SUSPEND_<index>
Whether or not the current alert is suspended. One for every currently valid alert controlled by this throttle.
_CURRENT_ITEM_<index>
XPath of the alert DataItem. One for every currently valid alert controlled by this throttle.
_THROTTLER
The name of the throttle
DataItem Information_GATEWAY
Name of gateway
_SEVERITY
"UNDEFINED"
_MANAGED_ENTITY
"UNDEFINED"
_NETPROBE_HOST
"UNDEFINED"
_VARIABLE
"THROTTLER"
Throttling Information_VALUE
The total number of throttled notifications.
_DROPPED_ALERTS
The number of throttled Alert notifications.
_DROPPED_CLEARS
The number of throttled Clear notifications.
_DROPPED_SUSPENDS
The number of throttled Suspend notifications.
_DROPPED_RESUMES
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 116 of 141
The number of throttled Resume notifications.
_SUMMARY_PERIOD
String describing the summary period.
_SUMMARY_STRATEGY
String describing the summary strategy.
Distribution Lists_TO
Comma delimited list of message all _TO recipients who had a notification throttled by this throttle.
_TO_INFO_TYPE
Corresponding comma delimited list of information types. The effect can use this to treat each element inthe _TO list differently if necessary. (e.g. Email, Pager)
_TO_NAME
Corresponding comma delimited list of users full names, as specified in the authentication section. (e.g.Alan User, Alan User)
_CC
Comma delimited list of message all _CC recipients who had a notification throttled by this throttle.
_CC_INFO_TYPE
As with the _TO_INFO_TYPE list, a comma delimited list of Carbon Copy recipient information types.
_CC_NAME
As with the _TO_NAME list, a comma delimited list of Blind Carbon Copy recipient names.
_BCC
Comma delimited list of message all _BCC recipients who had a notification throttled by this throttle.
_BCC_INFO_TYPE
As with the _TO_INFO_TYPE list, a comma delimited list of Blind Carbon Copy recipient informationtypes.
_BCC_NAME
As with the _TO_NAME list, a comma delimited list of Blind Carbon Copy recipient names.
GroupingGroupings allow a throttle to keep different counters for different logical groups. Each group is defined by acollection of XPaths which are evaluated when the action is fired. See XPaths - User Guide for moreinformation on XPaths. There is also a default group to throttle items that do not match the groupingcriteria.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 117 of 141
The result of evaluating each of these XPaths are gathered together to uniquely identify the throttlinggroup. To be part of a group all of the grouping criteria must bemet and if the grouping criteria are not allmet the default group will be used.
ExamplesThrottling per dataview.
ancestor::dataview
This will evaluate to the dataview of the data-item that triggered the alert. Effectively defining separatethrottling for each dataview as the throttle is applied.
If you have FKM and cpu dataviews triggering alerts they would each fire alerts up to the configured limitedwithin the configured time period.
Throttling separately for one specific plugin.
ancestor::dataview[@name="cpu"]
This will throttle actions triggered by dataviews named "cpu" separately to all other actions to which thethrottle is applied. There is an implicit default throttle for data-items that do not belong to a configuredgroup.
Throttling by row for one specific plugin.
ancestor::sampler[(param("PluginName")="FKM")]/dataview@rowname
This will throttle alerts triggered by each row of an FKM dataview separately.
Note: There are two XPaths. Both have to be satisfied. This effectively defines a group for each row ofthe FKM dataview. When the alert is fired the questions asked are "Is this part of the FKM dataview?"and "which row does it belong to?"
Throttle each data item separately
.
(dot) The current data-item; Throttle every data-item separately.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 118 of 141
Throttling by set of plugin types.
ancestor::dataview[@name="disk"]ancestor::dataview[@name="cpu"]ancestor::dataview[@name="network"]ancestor::dataview[@name="hardware"]
This will throttle "system" alerts together in one group.
Throttling by fkm dataviews per filename.
ancestor::sampler[(param("PluginName")="FKM")]/dataview../cell[(@column="filename")]/@value
This will throttle alerts triggered by each fkm file from each fkm dataview seperately. Alerts fired from cellsassociated with the same filenamewill be throttled into the same group.
Valid Grouping PathsYoumay receive a warning about parts of a configured grouping path not uniquely identifying a gatewayitem. Going in an upward direction (i.e. ancestor or "...") this is ok and will not generate a warning. Theproblem occurs when going "downwards", let's say your XPath is defined as:
ancestor::probe[@name="Holly"]//sampler
The intention being to throttle actions for all samplers on that probe. This will work for a while, untilsamplers are added or taken away from the probe. When the next action is fired the set of active samplerswill be different to the previous set. This will lead to the action being throttled by a different group. Thisprobably isn't the intended behaviour and is why the gateway issues a warning.
If the configured XPath were simply:
ancestor::probe[@name="Holly"]
This would throttle every action originating from that probe.
In a number of scenarios it is necessary to throttle alert notifications so that some of them are not sent. Todo this a throttle needs to be defined and referenced from the throttling section of an Alert or Hierarchy.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 119 of 141
Gateway2 allows you to configure rolling throttles to restrict the number of notifications. With a rollingthrottle it is possible to say only allow one notification to be fired within twenty four hours or fivenotifications within a fiveminute period.
When a notification fires it calls an effect (as defined in the effects section), passing it information aboutthe alert, the distribution lists, and about the data-item the alert has been created for.
Alert Commands
Show AlertsThis command shows all the alerts that are applicable to a selected data-item. Each applicable alert'sconfiguration (as configured in the Gateway Setup Editor) is presented in a formatted output to the ActiveConsole Output pane. This command applies only to data view data cells.
Evaluate AlertsThis command shows all the data-items in the system that currently matches the alert criteria in that partof the hierarchy tree. It can be executed by right clicking on an Alert in the Alerting hierarchy in theGateway Setup Editor. Thematching criterion is as specified in the hierarchy tree. Example, if youconfigure an Alerting hierarchy by managed entity name, and configure an Alert underneath this Alertinghierarchy with amanaged entity name to report all Warning and Critical alerts, only this managed entity (orits descendant data-items) that currently have warning or critical severity will be displayed.
For each data-item, it presents the following information:
Value Effect
Name The name of data-item
Display Name The display name of data-item
Type The data-item type, e.g. ManagedVariable
User Readable Path The XPath of data-item
Severity The severity of data-item (0 - Undefined, 1 - Ok, 2 -Warning, 3 - Critical)
Snoozed Whether data-item is snoozed (true, false)
Knowledge Base Whether has knowledge base (true, false)
Active Whether data-item is active (true, false)
DirectKnowledgeBase Whether has direct knowledge base (true, false)
Snoozed Parents The number of snoozed parents
User Assigned Whether assigned to any user
ManagedVariable Legacy Name The legacy name of the managed variable
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 120 of 141
Value Effect
ManagedVariable Value The value of managed variable
ManagedVariable Cell Column Name The managed variable column name
ManagedVariable Cell Row Name The managed variable row name
This command is useful in cases where the first severity change caused the Alert to be raised and notifiedto users but subsequent severity changes might go un-notified because they only keep the Alert valid atthat point in time. One can find all the severity changes in all managed variables that currently match theAlert criteria.
Configuration
alerting > hierarchyA hierarchy specifies the criteria on which basis an alert is fired and defines the alerts to be fired along withtheir distribution lists. Any number of hierarchies can be specified.
Mandatory: No
alerting > hierarchyGroupHierarchy groups are used to group sets of hierarchies, to improve ease of setupmanagement.
Mandatory: No
alerting > hierarchyGroup > nameSpecifies the name of the hierarchy group. Although the name is not used internally by gateway, it isrecommended to give the group a descriptive name so that users editing the setup file can easilydetermine the purpose of the group.
Mandatory: Yes
alerting > hierarchy > nameUnique name that identifies the hierarchy.
Mandatory: Yes
alerting > hierarchy > prioritySpecifies the priority of the hierarchy. When stopWhenMatched is set hierarchies are processed inpriority order. If two hierarchies are specified with the same priority the gateway will determine the order inwhich they are processed.
Mandatory: Yes
alerting > hierarchy > levelsSpecifies thematching criteria for every level of the hierarchy tree.
Mandatory: No
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 121 of 141
alerting > hierarchy > levels > level > matchThe parameter of the data-item that must match the alert name in order to match this level of the hierarchytree.
Mandatory: Yes
alerting > hierarchy > levels > level > match > man-agedEntityAttributeSpecifies themanaged entity attribute tomatch on.
alerting > hierarchy > levels > level > match > managedEntityNameSpecifies that the alert level shouldmatch on the cells managed entity name.
alerting > hierarchy > levels > level > match > rowNameSpecifies that the alert level shouldmatch on the cells row name.
alerting > hierarchy > levels > level > match > columnNameSpecifies that the alert level shouldmatch on the cells column name.
alerting > hierarchy > levels > level > match > headlineNameSpecifies that the alert level shouldmatch on the headline name.
alerting > hierarchy > levels > level > match > dataviewNameSpecifies that the alert level shouldmatch on the cells dataview name.
alerting > hierarchy > levels > level > match > samplerNameSpecifies that the alert level shouldmatch on the cells sampler name.
alerting > hierarchy > levels > level > match > samplerTypeSpecifies that the alert level shouldmatch on the cells sampler type.
alerting > hierarchy > levels > level > match > samplerGroupSpecifies that the alert level shouldmatch on the cells sampler group.
alerting > hierarchy > levels > level > match > pluginNameSpecifies that the alert level shouldmatch on the cells plugin name.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 122 of 141
alerting > hierarchy > alertAn alert describes a single branch of a hierarchy tree. It is evaluated if its namematches the appropriatelevelmatch-parameter of the target data-item where the appropriate level is the depth down the tree.
Hierarchies can contain any number of alert branches, and alert branches can contain any number of childalert branches. The depth of the alert tree cannot descend below the number of defined levels.
Mandatory: No
alerting > hierarchy > alert > nameUsed tomatch against the appropriate levelmatch-parameter of the target data-item. Matching is casesensitive and does not allow wild-cards. The appropriate level is the level for the depth this alert in thehierarchy tree.
For example, if the corresponding level in the hierarchy treematches onmanaged entity name, then thename specified heremust exactly match the name of amanaged entity.
Mandatory: Yes
alerting > hierarchy > alert > alertSpecifies a child alert.
Mandatory: No
alerting > hierarchyProcessingSpecifies how to process the hierarchy. Can take two values: processAll or stopWhenMatched.
Mandatory: NoDefault: processAll
alerting > hierarchyProcessing > processAllProcess all hierarchies, firing all alerts that match.
Mandatory: Yes (must be one of processAll or stopWhenMatched)
alerting > hierarchyProcessing > stopWhenMatchedProcess hierarchies in priority order and stop after the first notification is fired.
Mandatory: Yes (must be one of processAll or stopWhenMatched)
alerting > hierarchy > activeTimeSpecifies an optional activeTime, outside of which the hierarchy will not fire any notifications. See activetimes section for more details.
Mandatory: No
alerting > hierarchy > restrictions > snoozingThe snoozing restriction can be used to prevent an alert notification firing depending upon the snooze stateof the data-item which triggered the alert. Allowable values are listed below:
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 123 of 141
Value Effect
alwaysFire The alert is always fired, regardless of snooze state.
fireIfItemNotSnoozed The alert is fired if the triggering data-item is notsnoozed.
fireIfItemAndAncestorsNotSnoozed The alert is fired if the triggering data-item and all ofits ancestor data-items are not snoozed.
Mandatory: NoDefault: fireIfItemAndAncestorsNotSnoozed
alerting > hierarchy > restrictions > inactivityThe inactivity restriction can be used to prevent an alert notification firing depending upon the active stateof the data-item which triggered the alert. Allowable values are listed below:
Value Effect
alwaysFire The alert is always fired, regardless of active state.
fireIfItemActive The alert is fired if the triggering data-item is active.
fireIfItemAndAncestorsActive The alert is fired if the triggering data-item and all ofits ancestor data-items are active.
Mandatory: NoDefault: fireIfItemAndAncestorsActive
alerting > fireOnComponentStartupAlerts may be fired when a gateway or netprobe is first started.
Mandatory: NoDefault: false
alerting > fireOnConfigurationChangeAlerts may be fired following a change of the gateway configuration file.
Mandatory: NoDefault: false
alerting > hierarchy > throttleSpecify a default throttle for all alerts in this hierarchy. This must be the name of a throttle defined in theAlerting section of the gateway setup.
Mandatory: No
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 124 of 141
alerting > hierarchy > alert > warningDefines the warning notification for this alert branch. This alert is fired when amatching cell's severity isset to warning by a rule, and remains valid until the cell's severity drops below warning, rises to critical, orthe cell is deleted.
Any number of notifications can be defined in an escalation chain. Initially only the first will be fired, thiswill escalate to the second after the escalation interval has passed, that will then escalate to the third, ifdefined, and so on until either all notifications have been fired or the alert is no longer valid.
Mandatory: No
alerting > hierarchy > alert > warning > levelDefines a single notification.
Mandatory: No
alerting > hierarchy > alert > warning > level > escalationIntervalPeriod in seconds after which the alert, if still valid, will escalate to the next notification in the escalationchain, if it has been defined. This defaults to 300 (5minutes).
Mandatory: NoDefault: 300
alerting > hierarchy > alert > warning > level > notificationDefines a single notification in the escalation chain of notifications. A notification can contain any numberof effects, each with a separate distribution list and repeat interval.
Mandatory: No
alerting > hierarchy > alert > warning > level > notification > clearWhether or not to fire a clear notification when the alert is cancelled. Clears are fired using the same effectand distribution lists as the alert but with the variable _CLEAR set to true.
Mandatory: NoDefault: false
alerting > hierarchy > alert > warning > level > notification > repeatRepeat settings for the notification.
Mandatory: No
alerting > hierarchy > alert > warning > level > notification > repeat >intervalThe repeat interval for the notification in seconds. The effect will be fired each interval while the alert isvalid and the restrictions aremet.
Mandatory: Yes
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 125 of 141
alerting > hierarchy > alert > warning > level > notification > repeat >behaviourRepeat behaviour for the alert, can currently have two settings: continueAfterEscalation andcancelAfterEscalation. If set to continue after escalation, repeats will continue to fire even after the alerthas escalated; if set to cancel after escalation, repeats will cease to fire after the alert has escalated.
Mandatory: NoDefault: continueAfterEscalation
alerting > hierarchy > alert > warning > alwaysNotifySpecifies that the alert should fire even if other, more specific, matching alerts were fired further down thisbranch of the hierarchy tree. Default behaviour is for only themost specific matching alert to fire.
Mandatory: NoDefault: false
alerting > hierarchy > alert > criticalDefines the critical notification for this alert branch. This alert is fired if a matching cell goes to criticalseverity and remains valid until the cell drops below critical severity or is deleted.
Any number of notifications can be defined in an escalation chain. Initially only the first will be fired, thiswill escalate to the second after the escalation interval has passed, that will then escalate to the third, ifdefined, and so on until either all notifications have been fired or the alert is no longer valid.
Mandatory: No
alerting > hierarchy > alert > critical > levelDefines a single notification.
Mandatory: No
alerting > hierarchy > alert > critical > level > escalationIntervalPeriod in seconds after which the alert, if still valid, will escalate to the next notification in the escalationchain, if it has been defined. This defaults to 300 (5minutes).
Mandatory: NoDefault: 300
alerting > hierarchy > alert > critical > level > notificationDefines a single notification in the escalation chain of notifications. A notification can contain any numberof effects, each with a separate distribution list and repeat interval.
Mandatory: No
alerting > hierarchy > alert > critical > level > notification > clearWhether or not to fire a clear notification when the alert is cancelled. Clears are fired using the same effectand distribution lists as the alert but with the variable _CLEAR set to true.
Mandatory: No
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 126 of 141
Default: false
alerting > hierarchy > alert > critical > level > notification > repeatRepeat settings for the notification.
Mandatory: No
alerting > hierarchy > alert > critical > level > notification > repeat >intervalThe repeat interval for the notification in seconds. The effect will be fired each interval while the alert isvalid and the restrictions aremet.
Mandatory: Yes
alerting > hierarchy > alert > critical > level > notification > repeat >behaviourRepeat behaviour for the alert, can currently have two settings: continueAfterEscalation andcancelAfterEscalation. If set to continue after escalation, repeats will continue to fire even after the alerthas escalated; if set to cancel after escalation, repeats will cease to fire after the alert has escalated.
Mandatory: NoDefault: continueAfterEscalation
alerting > hierarchy > alert > critical > alwaysNotifySpecifies that the alert should fire even if other, more specific, matching alerts were fired further down thisbranch of the hierarchy tree. Default behaviour is for only themost specific matching alert to fire.
Mandatory: NoDefault: false
alerting > hierarchy > alert > warning > level > notification > effectThe effect that is to be fired for this notification.
Mandatory: Yes
alerting > hierarchy > alert > critical > level > notification > effectThe effect that is to be fired for this notification.
Mandatory: Yes
alerting > hierarchy > alert > warning > level > notification > userDefines the user information that will be passed to the effect. Any number of users can be passed to aneffect in one of three distribution lists, To, CC, and BCC.
Mandatory: No
alerting > hierarchy > alert > warning > level > notification > user >userThe name of the User, as defined in the Authentication section.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 127 of 141
Mandatory: Yes
alerting > hierarchy > alert > warning > level > notification > user >infoTypeThe user information to include on the distribution list, as defined in the authentication section, userinformation. Will default to "Email" if not set.
Mandatory: NoDefault: Email
alerting > hierarchy > alert > warning > level > notification > user >listThe distribution list to include the user on. Each notification has three distribution lists: To, CC, and BCC.Will default to "To" if not set.
Mandatory: NoDefault: To
alerting > hierarchy > alert > warning > level > notification > groupDefines group information that will be passed to the effect.
Groups have now been deprecated in favour of roles, as authentication user groups have also beendeprecated for roles.
Please see the documentation for roles if you still want to configure groups.
Role, infoType, list, include.
Mandatory: NoDeprecated: See Roles settings.
alerting > hierarchy > alert > warning > level > notification > roleDefines the Role information that will be passed to the effect. Any number of roles can be passed to aneffect in one of three distribution lists, To, CC, and BCC.
Mandatory: No
alerting > hierarchy > alert > warning > level > notification > role >roleThe name of the Role, as defined in the Authentication section.
Mandatory: Yes
alerting > hierarchy > alert > warning > level > notification > role >infoTypeThe Role information to include on the distribution list, as defined in the Authentication TechnicalReference . Will default to "Email" if not set.
Mandatory: NoDefault: Email
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 128 of 141
alerting > hierarchy > alert > warning > level > notification > role >listThe distribution list to include the role on. Each notification has three distribution lists: To, CC, and BCC.Will default to "To" if not set.
Mandatory: NoDefault: To
alerting > hierarchy > alert > warning > level > notification > role >includeWhat information from the role to include in the list. Can be one of three values:
Value Effect
ROLE Include only the information from the actual rolesection.
MEMBERS Include the information from all the role's individualmember user sections.
ROLE+MEMBERS Include information from both the group section andall the group's individual member user sections.
Mandatory: NoDefault: ROLE
alerting > hierarchy > alert > critical > level > notification > userDefines the user information that will be passed to the effect. Any number of users can be passed to aneffect in one of three distribution lists, To, CC, and BCC.
Mandatory: No
alerting > hierarchy > alert > critical > level > notification > user >userThe name of the User, as defined in the Authentication Technical Reference.
Mandatory: Yes
alerting > hierarchy > alert > critical > level > notification > user >infoTypeThe user information to include on the distribution list, as defined in the authentication section, userinformation. Will default to "Email" if not set.
Mandatory: NoDefault: Email
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 129 of 141
alerting > hierarchy > alert > critical > level > notification > user > listThe distribution list to include the user on. Each notification has three distribution lists: To, CC, and BCC.Will default to "To" if not set.
Mandatory: NoDefault: To
alerting > hierarchy > alert > critical > level > notification > groupDefines group information that will be passed to the effect.
Groups have now been deprecated in favour of roles, as authentication user groups have also beendeprecated for roles.
Please see the documentation for roles if you still want to configure groups.
Role, infoType, list, include.
Mandatory: NoDeprecated: See Roles settings.
alerting > hierarchy > alert > critical > level > notification > roleDefines the Role information that will be passed to the effect. Any number of roles can be passed to aneffect in one of three distribution lists, To, CC, and BCC.
Mandatory: No
alerting > hierarchy > alert > critical > level > notification > role > roleThe name of the Role, as defined in the Authentication section.
Mandatory: Yes
alerting > hierarchy > alert > critical > level > notification > role >infoTypeThe Role information to include on the distribution list, as defined in the authentication section. Willdefault to "Email" if not set.
Mandatory: NoDefault: Email
alerting > hierarchy > alert > critical > level > notification > role > listThe distribution list to include the role on. Each notification has three distribution lists: To, CC, and BCC.Will default to "To" if not set.
Mandatory: NoDefault: To
alerting > hierarchy > alert > critical > level > notification > role >includeWhat information from the group to include in the list. Can be one of three values:
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 130 of 141
Value Effect
ROLE Include only the information from the actual rolesection.
MEMBERS Include the information from all the group's individualmember user sections.
ROLE+MEMBERS Include information from both the group section andall the role's individual member user sections.
Mandatory: NoDefault: ROLE
alerting > hierarchy > alert > throttleSpecify a throttle to apply to all notifications at this alert level, and all alert levels below this level unlessoverridden.
Mandatory: No
alerting > throttleSpecifies an AlertThrottle for throttling alerts.
Mandatory: No
alerting > throttle > nameThis is a name to uniquely identify the throttle.
Mandatory: Yes
alerting > throttle > noOfAlertsThis is the number of alerts allowed within the time interval.
Mandatory: Yes
alerting > throttle > perThis is the number of time units used to define throttling duration. For example if you were setting a throttleof one action per tenminute interval. It would be "10".
Mandatory: Yes
alerting > throttle > intervalThis is the time interval in use seconds, minutes or hours, allowing the throttle to be defined in number ofalerts per interval.
Mandatory: Yes
alerting > throttle > groupingGroupings allow a throttle to keep different counters for different logical groups.
Mandatory: No
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 131 of 141
alerting > throttle > grouping > pathsGroupings allow a throttle to keep different counters for different logical groups. Each group is defined by acollection of XPaths which are evaluated when the action is fired. See the XPath User Guide for moreinformation on XPaths.
Mandatory: No
alerting > throttle > grouping > paths > pathGroupings allow a throttle to keep different counters for different logical groups. Each group is defined by acollection of XPaths which are evaluated when the alert is fired. There is also a default group to throttleitems that do not match the grouping criteria.
The result of evaluating each of these XPaths are gathered together to uniquely identify the throttlinggroup.
See theGrouping section for more information.
Mandatory: No
alerting > throttle > summaryDefines when summary effects should be fired.
Mandatory: No
alerting > throttle > summary > sendThis is the number of time units after which the summary effect should be fired.
Mandatory: Yes
alerting > throttle > summary > intervalThis is the time interval in use seconds, minutes or hours.
Mandatory: Yes
alerting > throttle > summary > strategyWhich strategy should be used? Fire the effect a configured time after the first allowed alert or a configuredtime after the first blocked alert.
Mandatory: Yes
alerting > throttle > summary > effectThe effect to fire for an Alert summary.
Mandatory: Yes
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 132 of 141
Effects
IntroductionEffects are defined routines that can be performed by the gateway. They cannot be called directly but arecalled as part of an action or alert. An effect can be thought of as a cut down action.
Effects allow the gateway to interface with other external systems, so that monitoring data can triggerother events in addition to being displayed in ActiveConsole. For instance, effects can be created to sendemails or pager messages.
OperationEffects are called by Actions and Alerts but is always run in the context of the specific data-item whichcaused the event, such as aManaged Variable that triggered a rule.
The value and other attributes of this item are thenmade available to the effect, which allows for an effectto have a customised operation depending upon these values. Depending upon the type of effect beingfired, the values will be passed to the action in different ways. Please refer to the appropriate effectconfiguration section for further details. The information passed to an effect will also differ slightlydepending on whether it is called by an action or alert.
Values passed to actions include the following:
l Data identifying the data-item and action or alert being fired.
l If the data-item is from a dataview table, then additional values from the dataview row.
l Any managed entity attributes which have been configured.
l In the case of effect called from actions, additional user data as configured in an environment.
l A list of knowledge-base articles which apply to the data-item.
Effect Configuration
Basic ConfigurationEffects are configured within the Effects top-level section of the gateway setup. Configuration consists ofa list of effect definitions, which specifies what will be done when the effect is fired. As effect arereferenced by name in other parts of the gateway setup, each effect must have a unique name among allother effects to prevent ambiguity.
Script effectsA script effect can run a shell-script or executable file. Theminimum required configuration for this type ofeffect is the executable to run, the command-line (whichmay be empty, but must still be specified) and thelocation to run this effect.
Depending upon the configured runLocation, this effect will run either on the Gateway or Netprobe hosts.Netprobe effects will run on the Netprobe containing the data-item that triggered the effect, unless anotherNetprobe has been explicitly specified with the probe setting.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 133 of 141
An effect run on Netprobe requires that a probe encoded password is specified in the probeconfiguration. If not specified, the Netprobe will return the error: "Remote Command not executed - invalidpassword". If there is no password to configure, run the Netprobe with -nopassword flag to avoid thisproblem.
For an effect which executes on theGateway, the value of the exeFile setting is checked to ensure thatthe executable is accessible by the Gateway. If this is not the case, the Gateway will be unable to executethe action and a setup validation error is produced.
Note: This validation cannot be performed by actions which run on Netprobe.
When executing a script effect, the script / executable being run is passed the values and attributes of thedata-item which triggered the alert or action that called the effect. These are passed as environmentvariables, which the script can then read and respond as required. The environment variables which arepassed are listed in the actions and alert sections.
Shared libraryShared library effects execute functions from within a shared library. Library effects aremore versatilethan script effects since they can store state between different executions of an effect, however they alsorequire more effort on behalf of the user to create.
Library effects currently only execute on the gateway, and require aminimum of the library file and functionname to be configured. Like script effects, these settings name are checked by gateway during setupvalidation to ensure the function can be found, so that an invalid configuration is detected immediatelyrather than when the effect is run.
Shared library functions must have the following prototype (similar to themain function of a basic Cprogram).
extern "C" int functionName(int argc, char** argv);
When a library effect is executed, the values and attributes of the data-item which triggered the action oralert are passed to it. These are passed as an array of strings of the form NAME=VALUE in the argvparameter. The number of values passed is given in the argc parameter. These variables are listed in theactions and alert sections.
See the Shared library section for an example of a shared library action.
Command effectsCommand-type effects can run any command supported by gateway. These commands are referenced byname (as commands are uniquely named) and the configurationmust supply all arguments expected bythe command in order to be valid. The number and type of arguments expected will vary according to thecommand being referenced.
Arguments can be specified with a static value, text value or a parameter value. A static value will havethe same value every time the effect is executed. A text value will have variable value depending upon the
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 134 of 141
values of the Geneos variables (evaluated to the command target data-item environment). The parametervalue configuration allows users to select a variable value, which will be populated from the data-itemwhich triggered the alert or action, similar to environment variables passed in by the actions and alert.
An example is shown below using the /SNOOZE:time command.
This command snoozes a data-item for a specified time period, and takes arguments as specified in thetable below:
Index Description Argument Type (Default) Value
1 User comment User input: MultiLineString
2 Item severity XPath state/@severity
3 Snooze type Static time
4 Snooze duration User input: Float 24
5 Snooze units User input: Options Hours (3600 - default),minutes (60), days(86400).
Of the arguments listed, three are user-input arguments - those at indexes 1, 4 and 5. To execute thecommand, these arguments must have values specified. For this command arguments 2 and 3 havedefaults specified, and so will take these values if they are not overridden.
Configuration SettingsEffects are configured in the Effects top-level section of the gateway setup. Configuration consists of a listof effect definitions, each of which contains theminimum required configuration for their type. Each effectis identified by a user-supplied name, whichmust be unique among all other effect to prevent ambiguity, aseffects are referenced by name.
Mandatory: Yes
Common effect settingsThe settings below are common to all types of effect.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 135 of 141
effects > effectAn effect definition contains the configuration required for a single effect. Theminimum configurationrequired will vary depending upon the type of effect being configured.
effects > effect > nameEffects are referenced by other parts of the gateway setup by name. In order to avoid ambiguity, effectsare required to have a unique name among all other effects.
Mandatory: Yes
Script effect settingsThe settings below define a script type effect.
effects > effect > scriptScript type effects allow the gateway to run a shell-script or executable file in response to gateway events.See the script effects section above for more details.
Mandatory: Yes (one of script, sharedLibrary or command must be specified for an effect)
effects > effect > script > exeFileSpecifies the shell script or executable file which will be run when the effect is called. For script effectswhich run on gateway (configured using the runLocation setting) this parameter is checked at setupvalidation time to ensure that the file exists.
Mandatory: Yes
effects > effect > script > argumentsThis setting specifies the command-line arguments which will be passed to the script or executable whenthe effect is called.
Mandatory: Yes
effects > effect > script > runLocationThe run location specifies where the script should be run. Valid values are detailed below.
Value Effect
gateway The script is run on the gateway.
netprobe The script is run on the netprobe from which thetriggering data-item came, unless this is overriddenusing the probe setting. An effect run on Netproberequires that probe encoded password is specified inthe probe configuration.
Mandatory: Yes
effects > effect > script > probeThis setting allows users to configure a specific netprobe to run the script on, when the script has beenconfigured to run on netprobes using the runLocation setting.
Mandatory: No
Shared library effect settingsThe settings below define a shared library type effect.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 136 of 141
effects > effect > sharedLibraryShared library type allow the gateway to run a function from a shared library in response to gatewayevents. See the shared library section above for more details.
Mandatory: Yes (one of script, sharedLibrary or command must be specified for an effect)
effects > effect > sharedLibrary > libraryFileSpecifies the location of the shared library to use for this effect. This setting is checked during setupvalidation to ensure that gateway can access this library.
Mandatory: Yes
effects > effect > sharedLibrary > functionNameSpecifies the name of the shared library function to run, inside the library specified by the libraryFilesetting. This setting is checked during setup validation to ensure that this function exists within the sharedlibrary.
Mandatory: Yes
effects > effect > sharedLibrary > runThreadedOptional Boolean setting specifying whether to run the shared library function within a thread or not.Running an effect in a thread is slightly less efficient but is recommended for library effects which takesome time to complete, to ensure that execution does not interfere with normal gateway operation.
Note: Shared library functions using this setting whichmaintain state should be written to bethread-safe to avoid potential problems.
Mandatory: NoDefault: false
effects > effect > sharedLibrary > staticParametersDefines static parameters which are always passed to the shared library function along with any valuespassed in by the action or alert.
Mandatory: No
effects > effect > sharedLibrary > staticParameters > staticParameter > nameName of static parameter. This must be unique, if a parameter of the same name is passed in by thecalling action or alert then this setting will be overridden.
Mandatory: Yes
effects > effect > sharedLibrary > staticParameters > staticParameter > valueValue of static parameter.
Mandatory: Yes
Command effect settingsThe settings below define a command type effect.
effects > effect > commandCommand type actions allow the gateway to run an internal or user-defined command in response togateway events. See the command section above for more details.
Mandatory: Yes (one of script, sharedLibrary or command must be specified for an effect)
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 137 of 141
effects > effect > command > refThis setting specifies which commandwill be executed when this command type effect is fired.Commands are referenced using the unique command name.
Mandatory: Yes
effects > effect > command > argsThis section allows the action to supply arguments to the command. If a command has any argumentswithout default values, then thesemust be specified so that the command can be run. This condition ischecked during setup validation.
Mandatory: No (unless the command has arguments without default values)
effects > effect > command > args > argEach arg definition specifies a single argument to pass to the command.
effects > effect > command > args > arg > targetThe target setting specifies which argument in the command this definition applies to. Commandarguments are numbered from one. E.g. A target value of four means that the contents of this definition willbe supplied as the fourth argument to the specified command.
Mandatory: Yes>
effects > effect > command > args > arg > staticSpecifies a static value for the command argument. This value will be the same for all executions of thiseffect.
Mandatory: Yes (mutually exclusive with text or parameter below)
effects > effect > command > args > arg > textA variable argument value for the command. This can include static text or Geneos variables which will beevaluated to their respective values depending upon the target data-item the command is being executedon. Example: if a Geneos variable "OS" is defined with different values at 2 different Managed Entities, andthe command is run on both theseManaged Entities data-items, then both command instances will getdifferent value of "OS" depending upon theManaged Entity data-item it is being run on. The argument typeis singleLineStringVar and can consist of static data and/or any number of Geneos variables interleavedtogether with/without static data. E.g. "Host:$(OS)-$(VERSION)" where "OS" and "VERSION" are 2 pre-definedGeneos variables. Currently only the following variables values can be properly converted tostring:
Variable Type Value
boolean "true" is checked, "false" otherwise
double The actual double value specified
integer The actual integer value specified
externalConfigFile The name of an external configuratin file.
macro The value of the macro selected - gateway name orgateway port or managed entity name or probe hostor probe name or probe port or sampler name.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 138 of 141
Mandatory: Yes (mutually exclusive with static or parameter below)
effects > effect > command > args > arg > parameterSpecifies a parameterised value for the command argument. This value is obtained from the data-itemwhich triggered the action or alert that called the effect, and so can change on every execution. Possiblevalues are listed below.
Value Effect
action The name of the action being triggered.
severity The data-item severity. One of UNDEFINED, OK,WARNING, CRITICAL or USER.
variablePath The full gateway path to the data-item.
gateway The name of the gateway firing the action.
probe The name of the probe the data-item belongs to (ifany).
probeHost The hostname of the probe the data-item belongs to(if any). This value is provided for backwardscompatibility.
managedEntity The name of the managed entity the data-itembelongs to (if any).
sampler The name of the sampler the data-item belongs to (ifany).
dataview The name of the dataview the data-item belongs to (ifany).
variable Short name of the data-item if it is a managedvariable, in the form <!>name for headlines or row.colfor table cells. This value is provided for backwardscompatibility.
repeatCount The number of times this action has been repeatedfor the triggering item.
Mandatory: Yes (mutually exclusive with static or text above)
AnnotationsAnnotations solve the following problems.
Conditional text in email templateslibemail like any Geneos shared lib takes a number of parameters.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 139 of 141
Anywhere you can use a standard parameter you can use an annotation.
The parameters are setup with the action or effect defition. Additionally you could add user data from a rulethat causes it to fire.
However if you want parameters available only on particular dataitems or to contain different text ondifferent dataitems while keeping your configuration simple annotations are the answer.
With annotations you can define key/value pairs and target them to dataitems for use in your emailtemplates for alerting and actions.
Optional environment settings for executable actionsSimilarly you can reduce complexity in action configuration. The annotations defined in this section willbecome environment variables to an executable script triggered through actions or effects.
Note: Annotations are added before user data and rule specific variables. This could lead to annotationsbeing overwritten or on some platforms duplicates. For this reason it is advised that the keys are uniquefrom environment variables or parameters for shared libraries.
annotations > annotation > nameA unique name for the annotation within the configuration.
annotations > annotation > keyThis is the name the annotation will be known as when substited for an environment variable or a staticcommand argument. This does not have to be unique and if more than one annotation applies with thesame key name then the values are combined.
The values are separated by new lines and the order is undefined. If ordering is important then separateannotations should be used to enforce order.
annotations > annotation > valueThe text to be substituted for the given key.
annotations > annotation > targetsA collection of xpaths used to identify applicable targets for the annotation.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 140 of 141
annotations > annotation > targets > targetsAn xpath identifying targets for the annotation.
GeneosRelease v4.6.0. GeneosRules, Actions, and Alerts v1.0.0 - TechnicalReference Published Date 16/03/2018
Page 141 of 141