Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

How to add a new alarm

Introduction

  • All processes (C++, java, and scripts) can raise alarms, which are logged in a single file (/var/log/sipxpbx/sipXalarms.log)
  • Internally, alarms are raised by specifying a unique string id and a list of any desired string parameters. There are no restrictions on the alarm code: examples could be "ALARM_FILE_REP_FAILED" or "ALARM_12345" or "ANY_OLD_ALARM_CONDITION" (this string is not viewable by users).
  • A set of XML alarm definition files contains details on each alarm, identified by its unique id (above). This includes an external unique alarm code, severity, component, description, resolution, and actions.
  • High-level alarm configuration data is stored in /etc/sipxpbx/alarm-config.xml. This includes the external email address(es) to which alarms should be sent.
    Non-localized per-alarm configuration data is stored in /etc/sipxpbx/alarms/.xml. This includes the unique internal id and external code for each alarm, and the actions which should be taken when this alarm occurs. Alarm definitions can be split among several files as desired by the application.
    Description and resolution strings are stored in separate, localizable, files in /share/sipxecs/alarms/-strings.xml These files are not backed up.
  • Actions currently include log and email. These are configurable for each alarm, as well as global enable/disable flags for each notification method. Max_report and thresholds are also provided on a per-alarm basis (e.g. only report this alarm x times; or only report this alarm after it occurs x times).

Adding new alarms

To add a new alarm, add a new section into the appropriate xml file in sipXsupervisor/etc/, with a new alarm id. Add the description and resolution strings in the appropriate-strings.xml file in sipXsupervisor/meta/alarms/. Normally there is no need to create new files; however if adding an optional package it might be desirable to capture the alarms in separate files.

  • The alarm id is a required field, and can be any unique string. This string is only used internally.
  • The alarm code is specified in the config file (e.g. sipXsupervisor/etc/sipXalarms-config.xml). New alarms should be added at the end of the appropriate file, and the code should follow the naming pattern for that file (e.g. SIPXnnnnn, incremented for each new alarm).

Generating alarms

  • Interfaces are provided for Java and C++ code to call to generate alarms. There are only two parameters: the unique internal ID and the parameter string (or list of strings).
  • For C++, there is a static function raiseAlarm(alarmId, alarmParams). See sipXsupervisor/src/SipxProcess.cpp for an example.
  • For sipXconfig (Java), the object should inject an AlarmContext, then call AlarmContext.raiseAlarm(alarmId, alarmParams...). See sipXconfig/neoconf/src/org/sipfoundry/sipxconfig/login/LoginContextImpl.java for an example. Other Java processes should send xmlrpc to the Alarm Server on the localhost.
  • Many alarm conditions are detected by the various scripts used by sipx. A script sipx-alarm exists to use the xml-rpc interface to report alarms. Note however that the script can only be used once sipxsupervisor is up and running. See sipXtools/src/sipx-mrtg-threshok.in for an example.
  • No labels