EcAlarm class documentation

Authors

Richard Frith-Macdonald (rfm@gnu.org)

Copyright: (C) 2012 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the EcAlarm class
  2. Software documentation for the EcAlarm(Convenience) category
  3. EcAlarm types
  4. EcAlarm functions

Software documentation for the EcAlarm class

EcAlarm : NSObject

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

alarmForManagedObject: at: withEventType: probableCause: specificProblem: perceivedSeverity: proposedRepairAction: additionalText: 

+ (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.

eventTypeFromProbableCause: 

+ (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.

stringFromEventType: 

+ (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.

stringFromProbableCause: 

+ (NSString*) stringFromProbableCause: (EcAlarmProbableCause)value;
Provides a human readable string representation of a probable cause.
Returns nil if the value is unknown.

stringFromSeverity: 

+ (NSString*) stringFromSeverity: (EcAlarmSeverity)value;
Provides a human readable string representation of a severity.
Returns nil if the value is unknown.

stringFromTrend: 

+ (NSString*) stringFromTrend: (EcAlarmTrend)value;
Provides a human readable string representation of a trend.
Returns nil if the value is unknown.

additionalText 

- (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.

clear 

- (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.

compare: 

- (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.

copyWithZone: 

- (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.

dealloc 

- (void) dealloc;
Deallocates the receiver.

encodeWithCoder: 

- (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.

eventDate 

- (NSDate*) eventDate;
Returns the timestamp of the event which generated the alarm.

eventType 

- (EcAlarmEventType) eventType;
This method returns the type for event which generated the alarm.

extra 

- (void*) extra;
Returns any extra information stored by the -setExtra: method.

firstEventDate 

- (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.

freeze 

- (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.

hash 

- (NSUInteger) hash;
Returns the hash of the receiver... which is also the hash of its managedObject.

initForManagedObject: at: withEventType: probableCause: specificProblem: perceivedSeverity: proposedRepairAction: additionalText: 

- (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.

initWithCoder: 

- (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.

isEqual: 

- (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.

managedObject 

- (NSString*) managedObject;
Returns the managedObject value set when the receiver was initialised.

moComponent 

- (NSString*) moComponent;
Returns the component of the managed object (if any).

moHost 

- (NSString*) moHost;
Returns the host of the managed object.

moInstance 

- (NSString*) moInstance;
Returns the instance of the managed object (if any).

moProcess 

- (NSString*) moProcess;
Returns the process name of the managed object.

notificationID 

- (int) notificationID;
Returns zero or the notificationID value most recently set by the -setNotificationID: method.

perceivedSeverity 

- (EcAlarmSeverity) perceivedSeverity;
Returns the perceivedSeverity set when the receiver was initialised.

probableCause 

- (EcAlarmProbableCause) probableCause;
Returns the probableCause set when the receiver was initialised.

proposedRepairAction 

- (NSString*) proposedRepairAction;
Returns the proposedRepairAction set when the receiver was initialised.

setExtra: 

- (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.

setFirstEventDate: 

- (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.

setNotificationID: 

- (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).

setTrendIndicator: 

- (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.

setUserInfo: 

- (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.

specificProblem 

- (NSString*) specificProblem;
Returns the specificProblem set when the receiver was initialised.

trendIndicator 

- (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).

userInfo 

- (NSDictionary*) userInfo;
Returns any previously set information (see -setUserInfo:) or nil if none has been set.



Instance Variables for EcAlarm Class

_additionalText

@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.

_eventDate

@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.

_eventType

@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.

_extra

@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.

_firstEventDate

@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.

_frozen

@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.

_managedObject

@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.

_notificationID

@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.

_perceivedSeverity

@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.

_probableCause

@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.

_proposedRepairAction

@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.

_specificProblem

@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.

_trendIndicator

@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.

_userInfo

@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.




Software documentation for the EcAlarm(Convenience) category

EcAlarm(Convenience)

Declared in:
EcAlarm.h
Description forthcoming.
Method summary

clear: cause: problem: 

+ (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.

raise: cause: problem: severity: action: ,...

+ (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.

EcAlarm types

EcAlarmEventType

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

EcAlarmProbableCause

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

EcAlarmSeverity

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

EcAlarmTrend

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

EcAlarm functions

EcMakeManagedObject

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.