Authors
- Richard Frith-Macdonald (
rfm@gnu.org
)
-
Copyright: (C) 2012 Free Software Foundation, Inc.
- Declared in:
- EcAlarm.h
- Conforms to:
- NSCoding
- NSCopying
The EcAlarm class encapsulates an alarm to be sent out
to a monitoring system. It's designed to work cleanly
with industry standard SNMP alarm monitoring systems.
For more information on how the SNMP operation works,
see the
EcAlarmSinkSNMP
class documentation.
Instances are created and sent to a central
coordination point where checks are
performed to see if there is an existing alarm
for the same issue. If the incoming alarm does not
change the severity of an existing alarm, it is
ignored, otherwise it may be passed on to an
external monitoring system. The central
coordination system is responsible for
ensuring that alarms for the same issue are
updated to contain the first event date,
notification ID and a trend indicator.
Instance Variables
Method summary
+ (
EcAlarm*)
alarmForManagedObject: (NSString*)managedObject
at: (NSDate*)eventDate
withEventType: (
EcAlarmEventType)eventType
probableCause: (
EcAlarmProbableCause)probableCause
specificProblem: (NSString*)specificProblem
perceivedSeverity: (
EcAlarmSeverity)perceivedSeverity
proposedRepairAction: (NSString*)proposedRepairAction
additionalText: (NSString*)additionalText;
Creates and returns an autoreleased instance by
calling the designated initialiser with all the
supplied arguments.
+ (
EcAlarmEventType)
eventTypeFromProbableCause: (
EcAlarmProbableCause)value;
This method provides a mapping from the probable cause
of an event to the event type.
The method is
called during initialisation of an alarm instance
(except where the probable cause is
EcAlarmProbableCauseUnknown)
to check that the supplied arguments are consistent. If
a subclass extends the possible probable cause values, it
must also override this method to handle those new
values by returning a known event type.
+ (NSString*)
stringFromEventType: (
EcAlarmEventType)value;
Provides a human readable string representation of
an event type.
This method is called during
initialisation of an alarm instance to check
that the supplied event type is legal.
Returns
nil
if the value is unknown.
+ (NSString*)
stringFromProbableCause: (
EcAlarmProbableCause)value;
Provides a human readable string representation of
a probable cause.
Returns nil
if the
value is unknown.
+ (NSString*)
stringFromSeverity: (
EcAlarmSeverity)value;
Provides a human readable string representation of
a severity.
Returns nil
if the
value is unknown.
+ (NSString*)
stringFromTrend: (
EcAlarmTrend)value;
Provides a human readable string representation of
a trend.
Returns nil
if the
value is unknown.
- (NSString*)
additionalText;
This is the supplementary text (optional) which may be
provided with and alarm an an aid to the human
operator for the monitoring system.
- (
EcAlarm*)
clear;
Returns an autoreleased copy of the receiver with
the same notificationID but with a perceivedSeverity
set to be EcAlarmSeverityCleared... this may be used to
clear the alarm represented by the receiver.
- (NSComparisonResult)
compare: (
EcAlarm*)other;
Compares the other object with the
receiver for sorting/ordering.
If both
objects have a notificationID set then the result
of the numeric comparison of those IDs is used.
Otherwise the result of the comparison orders the
objects by managedObject, eventType, probableCause,
and specificProblem.
- (id)
copyWithZone: (NSZone*)aZone;
EcAlarm objects may be copied. This method is
provided to implement the NSCopying protocol.
A copy of an object does
not copy
any value provided by the
-setExtra:
method.
A copy of an object is not frozen.
- (void)
dealloc;
Deallocates the receiver.
- (void)
encodeWithCoder: (NSCoder*)aCoder;
EcAlarm objects may be passed over the distributed
objects system or archived. This method is provided
to implement the NSCoding protocol.
An encoded
copy of an object does
not copy any value
provided by the
-setExtra:
method.
- (NSDate*)
eventDate;
Returns the timestamp of the event which generated
the alarm.
- (
EcAlarmEventType)
eventType;
This method returns the type for event which generated
the alarm.
- (void*)
extra;
Returns any extra information stored by the
-setExtra:
method.
- (NSDate*)
firstEventDate;
If this alarm is known to be represent an event updating
the status of an existing alarm, this method returns
the date of the initial event. otherwise it returns
nil
.
- (void)
freeze;
Freeze the state of the receiver; no more calls to
setters are permitted.
Then a frozen alarm
is copied, the new copy is not frozen.
- (NSUInteger)
hash;
Returns the hash of the receiver... which is also
the hash of its managedObject.
- (id)
initForManagedObject: (NSString*)managedObject
at: (NSDate*)eventDate
withEventType: (
EcAlarmEventType)eventType
probableCause: (
EcAlarmProbableCause)probableCause
specificProblem: (NSString*)specificProblem
perceivedSeverity: (
EcAlarmSeverity)perceivedSeverity
proposedRepairAction: (NSString*)proposedRepairAction
additionalText: (NSString*)additionalText;
This is a designated initialiser for the class.
Initialises the receiver as an alarm for a
particular event.
The
managedObject argument may be
nil
if the alarm should use the default
managed object value for the current process.
The eventDate argument may be
nil
if the alarm should use the current
timestamp.
The managedObject,
eventType, probableCause, and
specificProblem arguments uniquely
identify the issue for which an alarm is being
produced.
The perceivedSeverity
indicates the importance of the problem, with a
value of EcAlarmSeverityCleared indicating that the
problem is over.
A
proposedRepairAction is mandatory (unless
the severity is cleared) to provide the human operator
with some sort of hint about how they should resolve
the issue.
- (id)
initWithCoder: (NSCoder*)aCoder;
EcAlarm objects may be passed over the distributed
objects system or archived. This method is provided
to implement the NSCoding protocol.
- (BOOL)
isEqual: (id)other;
Returns a flag indicating whether the receiver is
equal to the other object. To be
considered equal either:
The two objects
must have equal managedObject values and equal
(non-zero) notificationID values or
the
two objects must have equal managedObject values, equal
eventType values, equal probableCause values, and
equal specificProblem values.
NB. you must not
set two alarm instances to have the same notificationID
values if they are not considered equal using the
other criteria.
- (NSString*)
managedObject;
Returns the managedObject value set when the
receiver was initialised.
- (NSString*)
moComponent;
Returns the component of the managed object (if
any).
- (NSString*)
moHost;
Returns the host of the managed object.
- (NSString*)
moInstance;
Returns the instance of the managed object (if
any).
- (NSString*)
moProcess;
Returns the process name of the managed object.
- (
EcAlarmSeverity)
perceivedSeverity;
Returns the perceivedSeverity set when the receiver
was initialised.
- (
EcAlarmProbableCause)
probableCause;
Returns the probableCause set when the receiver was
initialised.
- (NSString*)
proposedRepairAction;
Returns the proposedRepairAction set when the
receiver was initialised.
- (void)
setExtra: (void*)extra;
Sets extra data for the current instance.
Extra data is not copied, archived, or
transferred over DO, it is available only in
the exact instance of the class in which it was set.
- (void)
setFirstEventDate: (NSDate*)firstEventDate;
Sets the first event date for the receiver.
You
should not normally call this as it is reserved for
use by code which has matched the receiver to an
existing alarm.
- (void)
setNotificationID: (int)notificationID;
Sets the notification ID for the receiver.
You
should not normally call this as it is reserved for
use by code which has matched the receiver to an
existing alarm.
In particular, two
instances should not be set to have the same
non-zero notificationID unless they are
equal according to other criteria of equality (ie
have the same managedObject, eventType, probableCause,
and specificProblem values).
- (void)
setTrendIndicator: (
EcAlarmTrend)trendIndicator;
Sets the trend indicator for the receiver.
You
should not normally call this as it is reserved for
use by code which has matched the receiver to an
existing alarm.
- (void)
setUserInfo: (NSDictionary*)userInfo;
Sets the user information associated with this alarm
(a dictionary).
This user information is
additional data associated with the alarm which
is copied when the alarm is copied. This data is not
used by the CCITT X.733... it's optional additional
data.
Conventional keys are:
- ResponsibleEmail
-
The Email address of the person/entity with primary
responsibility for dealing with an alarm
... this is intended for use by the alerting system
(EcAlerter) when deciding where to send
email alerts.
- (NSString*)
specificProblem;
Returns the specificProblem set when the receiver
was initialised.
- (
EcAlarmTrend)
trendIndicator;
Returns the value most recently set by the
-setTrendIndicator:
method (or EcAlarmTrendNone if that method has not
been called).
This tells you whether the
receiver represents an increase in severity of an
issue, or a decrease in severity (or no change).
- (NSDictionary*)
userInfo;
Returns any previously set information (see
-setUserInfo:) or nil
if none
has been set.
Instance Variables for EcAlarm Class
@protected NSString* _additionalText;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected NSDate* _eventDate;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected EcAlarmEventType _eventType;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected void* _extra;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected NSDate* _firstEventDate;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected BOOL _frozen;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected NSString* _managedObject;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected int _notificationID;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected EcAlarmSeverity _perceivedSeverity;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected EcAlarmProbableCause _probableCause;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected NSString* _proposedRepairAction;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected NSString* _specificProblem;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected EcAlarmTrend _trendIndicator;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected NSDictionary* _userInfo;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
- Declared in:
- EcAlarm.h
Description forthcoming.
Method summary
+ (
EcAlarm*)
clear: (NSString*)componentName
cause: (
EcAlarmProbableCause)probableCause
problem: (NSString*)specificProblem;
Generates an alarm to clears an alarm previously
generated.
The componentName
may be nil
for a process-wide alarm.
The probableCause must NOT be
unknown... it is used to infer the event type.
The specificProblem must be
identical to the value supplied in the original
alarm that this is intended to clear.
+ (
EcAlarm*)
raise: (NSString*)componentName
cause: (
EcAlarmProbableCause)probableCause
problem: (NSString*)specificProblem
severity: (
EcAlarmSeverity)perceivedSeverity
action: (NSString*)proposedRepairAction
,...;
Generates a new alarm event with minimal
parameters.
The componentName
may be nil
for a process-wide alarm.
The probableCause must NOT be
unknown... it is used to infer the event type.
The specificProblem is used to
identify the event for which the alarm is raised.
The perceivedSeverity must be one
of EcAlarmSeverityWarning, EcAlarmSeverityMinor,
EcAlarmSeverityMajor or
EcAlarmSeverityCritical.
The proposedRepairAction must contain
information sufficient for any person receiving
notification of the alarm to be able to deal
with it. The action is a format string, optionally
followed by any number of arguments to be
incorporated into the repair action. NB. The
resulting proposed repair action must be no more
than 255 bytes in length when converted to UTF-8 data.
typedef enum ... EcAlarmEventType;
The EcAlarmEventType enumeration defines the different
types of alarm we support.
The enumerated values
MUST be matched by those in your SNMP MIB if you wish to
have your software interact with SNMP tools.
NB.
EcAlarmEventTypeUnknown must
NOT be used in an alarm... it is employed
solely as a marker for the case where a lookup of type
from probable cause can not determine a specific event
type.
- EcAlarmEventTypeUnknown
-
Not used
- EcAlarmEventTypeCommunications
-
A communications/networking/protocol issue
- EcAlarmEventTypeEnvironmental
-
An external environmental issue (eg building on fire)
- EcAlarmEventTypeEquipment
-
A hardware problem (eg disk failure)
- EcAlarmEventTypeProcessingError
-
A software problem (a bug or misconfiguration)
- EcAlarmEventTypeQualityOfService
-
A system not running as well as expected... eg.
overloaded
typedef enum ... EcAlarmProbableCause;
The EcAlarmProbableCause enumeration defines the probable
causes of alarms produced by the system.
These
are taken from the CCITT X.733 specification with the
numeric values from the CCITT X.721 specification.
Enumeration values include a comment to specify
which EcAlarmEventType they apply to.
- EcAlarmProbableCauseUnknown
-
Category: Any
- EcAlarmAdapterError
-
Category: Equipment
- EcAlarmApplicationSubsystemFailure
-
Category: Processing
- EcAlarmBandwidthReduced
-
Category: QoS
- EcAlarmCallEstablishmentError
-
Category: Communications
- EcAlarmCommunicationsProtocolError
-
Category: Communications
- EcAlarmCommunicationsSubsystemFailure
-
Category: Communications
-
EcAlarmConfigurationOrCustomizationError
-
Category: Processing
- EcAlarmCongestion
-
Category: QoS
- EcAlarmCorruptData
-
Category: Processing
- EcAlarmCpuCyclesLimitExceeded
-
Category: Processing
- EcAlarmDataSetOrModemError
-
Category: Equipment
- EcAlarmDegradedSignal
-
Category: Communications
- EcAlarmDTE_DCEInterfaceError
-
Category: Communications
- EcAlarmEnclosureDoorOpen
-
Category: Environmental
- EcAlarmEquipmentMalfunction
-
Category: Equipment
- EcAlarmExcessiveVibration
-
Category: Environmental
- EcAlarmFileError
-
Category: Processing
- EcAlarmFireDetected
-
Category: Environmental
- EcAlarmFloodDetected
-
Category: Environmental
- EcAlarmFramingError
-
Category: Communications
-
EcAlarmHeatingOrVentilationOrCoolingSystemProblem
-
Category: Environmental
- EcAlarmHumidityUnacceptable
-
Category: Environmental
- EcAlarmInputOutputDeviceError
-
Category: Equipment
- EcAlarmInputDeviceError
-
Category: Equipment
- EcAlarmLANError
-
Category: Communications
- EcAlarmLeakDetected
-
Category: Environmental
- EcAlarmLocalNodeTransmissionError
-
Category: Communications
- EcAlarmLossOfFrame
-
Category: Communications
- EcAlarmLossOfSignal
-
Category: Communications
- EcAlarmMaterialSupplyExhausted
-
Category: Environmental
- EcAlarmMultiplexerProblem
-
Category: Equipment
- EcAlarmOutOfMemory
-
Category: Processing
- EcAlarmOuputDeviceError
-
Category: Equipment
- EcAlarmPerformanceDegraded
-
Category: QoS
- EcAlarmPowerProblem
-
Category: Equipment
- EcAlarmPressureUnacceptable
-
Category: Environmental
- EcAlarmProcessorProblem
-
Category: Equipment
- EcAlarmPumpFailure
-
Category: Environmental
- EcAlarmQueueSizeExceeded
-
Category: QoS
- EcAlarmReceiveFailure
-
Category: Equipment
- EcAlarmReceiverFailure
-
Category: Equipment
- EcAlarmRemoteNodeTransmissionError
-
Category: Communications
- EcAlarmResourceAtOrNearingCapacity
-
Category: QoS
- EcAlarmResponseTimeExcessive
-
Category: QoS
- EcAlarmRetransmissionRateExcessive
-
Category: QoS
-
EcAlarmSoftwareProgramAbnormallyTerminated
-
Category: Processing
- EcAlarmSoftwareProgramError
-
Category: Processing
- EcAlarmStorageCapacityProblem
-
Category: Processing
- EcAlarmTemperatureUnacceptable
-
Category: Environmental
- EcAlarmThresholdCrossed
-
Category: QoS
- EcAlarmTimingProblem
-
Category: Equipment
- EcAlarmToxicLeakDetected
-
Category: Environmental
- EcAlarmTransmitFailure
-
Category: Equipment
- EcAlarmTransmitterFailure
-
Category: Equipment
- EcAlarmUnderlyingResourceUnavailable
-
Category: Processing
- EcAlarmVersionMismatch
-
Category: Processing
typedef enum ... EcAlarmSeverity;
The EcAlarmSeverity enumeration defines the 'perceived
severities' of alarms produced by the system.
The enumerated values MUST be matched by those
in your SNMP MIB if you wish to have your software
interact with SNMP tools.
NB. The use of
EcAlarmSeverityIndeterminate
should be avoided.
- EcAlarmSeverityIndeterminate
-
Do not use
- EcAlarmSeverityCritical
-
Immediate intervention required to restore
service
- EcAlarmSeverityMajor
-
Severe but partial system failure or a problem
which might recover without intervention
- EcAlarmSeverityMinor
-
A failure, but one which is likely to recover or which
is probably not urgent
- EcAlarmSeverityWarning
-
An unusual event which may not indicate any problem,
but which ought to be looked into
- EcAlarmSeverityCleared
-
This indicates the resolution of an earlier issue
typedef enum ... EcAlarmTrend;
The EcAlarmTrend enumeration defines the severity trend
of alarms produced by the system.
The enumerated
values MUST be matched by those in your SNMP MIB if
you wish to have your software interact with SNMP tools.
- EcAlarmTrendNone
-
This is not a change in severity of an earlier alarm
- EcAlarmTrendUp
-
This is a more severe version of an earlier alarm
- EcAlarmTrendDown
-
This is a less severe version of an earlier alarm
NSString* EcMakeManagedObject(NSString* host, NSString* process, NSString* component);
This function builds a managed object name from
host, process, and
component.
The host part
may be nil
... for the current
host.
The process part may
be nil
... for the current process.
The component may well be
nil
if the alert applies to the
process as a whole rather than to a
particular component. This field is
typically used to identify a particular network
connection etc within a process.
This parses the process and separates out any
instance ID (trailing hyphen and string of digits).
It then builds the managed object from four parts (
host, process, instance,
component) separated by underscores. Any
underscores in the arguments are replaced by
hyphens.
NB. The total length must not exceed
127 ASCII characters.