/** Enterprise Control Configuration and Logging Copyright (C) 2012 Free Software Foundation, Inc. Written by: Richard Frith-Macdonald Date: Febrary 2010 Originally developed from 1996 to 2020 by Brainstorm, and donated to the FSF. This file is part of the GNUstep project. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111 USA. */ #ifndef _ECALARM_H #define _ECALARM_H #import @class NSCoder; @class NSDate; @class NSDictionary; @class NSString; /** * 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 { EcAlarmEventTypeUnknown = 0, EcAlarmEventTypeCommunications = 2, EcAlarmEventTypeEnvironmental = 3, EcAlarmEventTypeEquipment = 4, EcAlarmEventTypeProcessingError = 10, EcAlarmEventTypeQualityOfService = 11, } EcAlarmEventType; /** 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 * EcAlarmOutputDeviceError * 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 { EcAlarmProbableCauseUnknown = 0, // Any EcAlarmAdapterError = 1, // Equipment EcAlarmApplicationSubsystemFailure = 2, // Processing EcAlarmBandwidthReduced = 3, // QoS EcAlarmCallEstablishmentError = 4, // Communications EcAlarmCommunicationsProtocolError = 5, // Communications EcAlarmCommunicationsSubsystemFailure = 6, // Communications EcAlarmConfigurationOrCustomizationError = 7, // Processing EcAlarmCongestion = 8, // QoS EcAlarmCorruptData = 9, // Processing EcAlarmCpuCyclesLimitExceeded = 10, // Processing EcAlarmDataSetOrModemError = 11, // Equipment EcAlarmDegradedSignal = 12, // Communications EcAlarmDTE_DCEInterfaceError = 13, // Communications EcAlarmEnclosureDoorOpen = 14, // Environmental EcAlarmEquipmentMalfunction = 15, // Equipment EcAlarmExcessiveVibration = 16, // Environmental EcAlarmFileError = 17, // Processing EcAlarmFireDetected = 18, // Environmental EcAlarmFloodDetected = 19, // Environmental EcAlarmFramingError = 20, // Communications EcAlarmHeatingOrVentilationOrCoolingSystemProblem = 21, // Environmental EcAlarmHumidityUnacceptable = 22, // Environmental EcAlarmInputOutputDeviceError = 23, // Equipment EcAlarmInputDeviceError = 24, // Equipment EcAlarmLANError = 25, // Communications EcAlarmLeakDetected = 26, // Environmental EcAlarmLocalNodeTransmissionError = 27, // Communications EcAlarmLossOfFrame = 28, // Communications EcAlarmLossOfSignal = 29, // Communications EcAlarmMaterialSupplyExhausted = 30, // Environmental EcAlarmMultiplexerProblem = 31, // Equipment EcAlarmOutOfMemory = 32, // Processing EcAlarmOutputDeviceError = 33, // Equipment EcAlarmPerformanceDegraded = 34, // QoS EcAlarmPowerProblem = 35, // Equipment EcAlarmPressureUnacceptable = 36, // Environmental EcAlarmProcessorProblem = 37, // Equipment EcAlarmPumpFailure = 38, // Environmental EcAlarmQueueSizeExceeded = 39, // QoS EcAlarmReceiveFailure = 40, // Equipment EcAlarmReceiverFailure = 41, // Equipment EcAlarmRemoteNodeTransmissionError = 42, // Communications EcAlarmResourceAtOrNearingCapacity = 43, // QoS EcAlarmResponseTimeExcessive = 44, // QoS EcAlarmRetransmissionRateExcessive = 45, // QoS EcAlarmSoftwareProgramAbnormallyTerminated = 47, // Processing EcAlarmSoftwareProgramError = 48, // Processing EcAlarmStorageCapacityProblem = 49, // Processing EcAlarmTemperatureUnacceptable = 50, // Environmental EcAlarmThresholdCrossed = 51, // QoS EcAlarmTimingProblem = 52, // Equipment EcAlarmToxicLeakDetected = 53, // Environmental EcAlarmTransmitFailure = 54, // Equipment EcAlarmTransmitterFailure = 55, // Equipment EcAlarmUnderlyingResourceUnavailable = 56, // Processing EcAlarmVersionMismatch = 57, // Processing } EcAlarmProbableCause; /** 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. * * EcAlarmSeverityIndeterminateDo 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 { EcAlarmSeverityIndeterminate = 0, EcAlarmSeverityCritical = 1, EcAlarmSeverityMajor = 2, EcAlarmSeverityMinor = 3, EcAlarmSeverityWarning = 4, EcAlarmSeverityCleared = 5 } EcAlarmSeverity; /** 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 * */ typedef enum { EcAlarmTrendNone = 0, EcAlarmTrendUp = '+', EcAlarmTrendDown = '-', } EcAlarmTrend; /** 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. */ NSString * EcMakeManagedObject(NSString *host, NSString *process, NSString *component); /**

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

*

Alarms which have been raised (by passing them to an alarm destination) * remain raised until they are cleared (by passign a matching alarm with * a cleared severity status) to the destination. Alarm clears sent with * no earlier matching raise are generally ignored, but a clear may be * flagged as a special audit alarm: one which is passed on and logged * for audit porposes. This is a rare situation where the alarm does not * actually represent a problem (or even the suspicion of a problem). *

*/ @interface EcAlarm : NSObject { NSString *_managedObject; NSDate *_eventDate; NSDate *_firstEventDate; EcAlarmEventType _eventType; EcAlarmSeverity _perceivedSeverity; EcAlarmProbableCause _probableCause; NSString *_specificProblem; NSString *_proposedRepairAction; NSString *_additionalText; EcAlarmTrend _trendIndicator; int _notificationID; NSDictionary *_userInfo; void *_extra; BOOL _frozen; uint8_t _delay; BOOL _audit; } /** Creates and returns an autoreleased instance by calling the * designated initialiser with all the supplied arguments. */ + (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; /** 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. */ + (EcAlarmEventType) eventTypeFromProbableCause: (EcAlarmProbableCause)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*) stringFromEventType: (EcAlarmEventType)value; /** Provides a human readable string representation of a probable cause.
* Returns nil if the value is unknown. */ + (NSString*) stringFromProbableCause: (EcAlarmProbableCause)value; /** Provides a human readable string representation of a severity.
* Returns nil if the value is unknown. */ + (NSString*) stringFromSeverity: (EcAlarmSeverity)value; /** Provides a human readable string representation of a trend.
* Returns nil if the value is unknown. */ + (NSString*) stringFromTrend: (EcAlarmTrend)value; /** This is the supplementary text (optional) which may be provided with * and alarm an an aid to the human operator for the monitoring system. */ - (NSString*) additionalText; /** Returns YES if this alarm is flagged as an audit object: a clear which * should be recorded/monitored even without a matching raise of the alarm. */ - (BOOL) audit; /** 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. */ - (NSComparisonResult) compare: (EcAlarm*)other; /** 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. */ - (EcAlarm*) clear; /** 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. */ - (id) copyWithZone: (NSZone*)aZone; /** Deallocates the receiver. */ - (void) dealloc; /** Returns the queue delay set for this alarm (or zero if none was set). */ - (uint8_t) delay; /** Returns YES if the receiver should be delayed in the queue past the * supplied timestamp, NO otherwise. */ - (BOOL) delayed: (NSTimeInterval)at; /** 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. */ - (void) encodeWithCoder: (NSCoder*)aCoder; /** Returns the timestamp of the event which generated the alarm. */ - (NSDate*) eventDate; /** This method returns the type for event which generated the alarm. */ - (EcAlarmEventType) eventType; /** Returns any extra information stored by the -setExtra: method.
*/ - (void*) extra; /** 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. */ - (NSDate*) firstEventDate; /** Freeze the state of the receiver; * no more calls to setters are permitted.
* When a frozen alarm is copied, the new copy is not frozen. */ - (void) freeze; /** Returns the hash of the receiver ... which is also the hash of its * managedObject. */ - (NSUInteger) hash; /** * 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) initForManagedObject: (NSString*)managedObject at: (NSDate*)eventDate withEventType: (EcAlarmEventType)eventType probableCause: (EcAlarmProbableCause)probableCause specificProblem: (NSString*)specificProblem perceivedSeverity: (EcAlarmSeverity)perceivedSeverity proposedRepairAction: (NSString*)proposedRepairAction additionalText: (NSString*)additionalText; /** EcAlarm objects may be passed over the distributed objects system or * archived. This method is provided to implement the NSCoding protocol. */ - (id) initWithCoder: (NSCoder*)aCoder; /** 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. */ - (BOOL) isEqual: (id)other; /** Returns the managedObject value set when the receiver was initialised. */ - (NSString*) managedObject; /** Returns the component of the managed object (if any). */ - (NSString*) moComponent; /** Returns the host of the managed object. */ - (NSString*) moHost; /** Returns the instance of the managed object (if any). */ - (NSString*) moInstance; /** Returns the process name of the managed object including the instance * separated from the main name by a hyphen. If the managed object has no * process instance, this method simply returns the process name. */ - (NSString*) moInstancedProcess; /** Returns the process name of the managed object. */ - (NSString*) moProcess; /** Returns zero or the notificationID value most recently set by * the -setNotificationID: method. */ - (int) notificationID; /** Returns the perceivedSeverity set when the receiver was initialised. */ - (EcAlarmSeverity) perceivedSeverity; /** Returns the proposedRepairAction set when the receiver was initialised. */ - (NSString*) proposedRepairAction; /** Returns the probableCause set when the receiver was initialised. */ - (EcAlarmProbableCause) probableCause; /** Specified if this alarm is to be flagged as an audit object: a clear which * should be recorded/monitored even without a matching raise of the alarm. */ - (void) setAudit: (BOOL)flag; /** Sets the number of seconds for which this alarm should be delayed in the * queue to allow coalescing with other matching alarms. This defaults to * zero so that there is no special delay in processing beyond that imposed * by periodic queue flushing. */ - (void) setDelay: (uint8_t)delay; /** 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) setExtra: (void*)extra; /** 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) setFirstEventDate: (NSDate*)firstEventDate; /** 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) setNotificationID: (int)notificationID; /** 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) setTrendIndicator: (EcAlarmTrend)trendIndicator; /** 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. * * */ - (void) setUserInfo: (NSDictionary*)userInfo; /** Returns the specificProblem set when the receiver was initialised. */ - (NSString*) specificProblem; /** 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). */ - (EcAlarmTrend) trendIndicator; /** Returns any previously set information (see -setUserInfo:) or nil * if none has been set. */ - (NSDictionary*) userInfo; @end @interface EcAlarm (Convenience) /** 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*) clear: (NSString*)componentName cause: (EcAlarmProbableCause)probableCause problem: (NSString*)specificProblem; /** 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*) raise: (NSString*)componentName cause: (EcAlarmProbableCause)probableCause problem: (NSString*)specificProblem severity: (EcAlarmSeverity)perceivedSeverity action: (NSString*)proposedRepairAction, ...; @end #endif