rfm@gnu.org
)Copyright: (C) 2012 Free Software Foundation, Inc.
- Declared in:
- EcAlerter.h
This class handles delivery and logging of error and
alert messages to the people who should be monitoring
the system. It is used by the Control server (to which
all these messages are delivered) and implements a
simple rule based mechanism for managing final
delivery of the messages.
The Control
server also feeds alarm events (see
EcAlarm
) into the system as alerts.
The configured rules are compared against each
message and any actions associated with a
matching rule are performed.
The matching
fields in each rule are -
YES
or NO
) saying whether rule matching should stop if this rule is matched. If this is NO
(the default) then after any action associated with this rule is performed, matching continues at the next rule. YES
or NO
) saying whether stored messages due to be sent out later should be sent out immediately after processing this rule. This is useful in the event that some time critical message must be sent, but should not normally be used. There are two additional fields Extra1 and Extra2 which are matched against the message. These patterns do not effect whether the action of the rule is executed or not, but the text matched is made available for substitution into replacement messages.
When a match is found the full message
is normally sent to all the destinations
listed in the Email and
Sms arrays in the rule, and
logged to all the destinations in
the Log array.
Before
the message is sent, the
Rewrite field may be used to
change the message in the event
(rewriting it for the current
rule and for all subsequent rules).
Once any rewriting has been
done the actual message sent out will
be the most recently rewritten value (or
a value determined by any
Replacement field in the
current rule).
The
Replacement field comes in
three variants which may be used
instead of the general field,
depending on the kind of alert
actually being sent out. These
variants are:
EmailReplacement,
LogReplacement and
SmsReplacement.
Rewrite and a Replacement fields
are handled by using the text value of
the fields as templates with string
values enclosed in curly brackets
being substituted as follows -
The Log array specifies a list
of log destinations which are normally
treated as filenames (stored in the
standard log directory). However,
a value beginning 'database:' * is logged
to a database (the default database
configured for SQLClient).
After the colon you may place
a table name, but if you don't then the
message will be logged to the
'Alert' table.
The values
logged in separate fields are the
Timestamp, Type, Server, Host,
Extra1, Extra2, and full log text
(as produced by the Replacement config)
is written into the Message field of the
table after having been truncated to
200 chars. Because of the truncation
limit, it is recommended that if you
are trying to include the original
alert {Message} (rather than
rewriting it) the Replacement
does not include Timestamp, Type,
Server, Host, Extra1, Extra2 which
are already saved in separate fields,
and would take up a lot of the 200
chars, which would be better used to
log the actual message.
The Sms array lists phone numbers to which Sms alerts are to be sent (if the alerter has been subclassed to implement SMS delivery).
The Email array lists email
addresses to which email alerts
are to be sent.
An address with
the prefix '{ResponsibleEmail}' may be
used as a special case. It means that
if an alarm has a ResponsibleEmail value
set in its userInfo dictionary, that
value is used as the address,
otherwise the text after
'{ResponsibleEmail}'
is used as a fallback.
An
optional Subject field
may be present in the rule... this is
used to specify that the email is to
be tagged with the given subject line.
This defeats batching of
messages in that only messages
with the same subject may be batched
in the same email.
NB. The value
of the Subject field is used as
a template in the same way as the
Replacement fields.
The Threaded is just like the Email array except that it is only used for alarm messages, and the messages sent to the addresses in this array form a chain of linke messages referring back to each other rather than all being versions of the same message. This may give a better effect for people using mail clients which don't support the message-ID header well.
Configuration of the alerter is done by the 'Alerter' key in the user defaults system. The value for this key must be a dictionary configuring the Email setup and the rules as follows:
YES
, all outgoing
Email messages are logged.
When an ExAlerter instance is used by
a Control server process, The 'Alerter'
configuration dictionary may
contain some extra configuration
used to define the way the Control
server uses the alerter.
The
Control server integrates the alarm
system (EcAlarm etc) with the
alerting system (used by alert and
error level logging from EcProcess)
by generating alerter events when alarms
of a severity above a certain threshold
are raised, and sending alerter 'clear'
messages when those alarms are
cleared.
The Control server
may also be configured to generate
reminder alerts when alarms have
not been dealt with (cleared) in a
timely manner.
Rules
an array of
dictionaries, each of which provides a rule
for delivering some form of alert.
This method handles an error/alert event (an 'error'
is one which may be buffered, while an 'alert' must be
sent immediately).
If the
identifier field is non-nil then the
event is an alert which is identified by the value
of the field.
An 'alert' may be due to an
alarm (persistent problem), in which
case the alarm argument must contain the
original alarm details including its
perceived severity. However, the value returned
by
[EcAlarm -extra]
may be used to specify that an event is a clear (the
end of the alarm), (the value of the field
bust be 'Clear').
The reminder
field counts the number of copies of an
alarm previously sent to the alerting
system, and should be set to -1 if the alert is
not an alarm, reminder ofr an
alarm, or clear of an alarm.
The use of an empty string as an
identifier is permitted for events which
should not be buffered, but which will never be
matched by a clear.
Each event must consist of text associated with a host name, server name (usually the process on the host) and timestamp.
Each message is matched against each rule in the
Rules configuration in turn, and the first
match found is used. The message is sent to the
people listed in the Email
and
Sms
entries in the rule (which may be
either single names or arrays of names).
This method handles error/alert messages. It is able to handle multiple (newline separated messages.
Each message must be a line of the format -
serverName(hostName): YYYY-MM-DD
hh:mm:ss.mmm szzzz type - text
Each message is parsed an then the components are passed to the -handleEvent:withHost:andServer:timestamp:identifier:alarm:reminder: method.
nil
identifier.
nil
identifier.
nil
identifier.