SNMP Alerts

Overview

The GigaSpaces data grid Alert interface exposes the data grid environment and the application's health state. It allows users to register listeners on one or more alert types and receive notifications once an alert has been raised or has been resolved. You may use this framework to build a custom integration with a third party monitoring products to leverage the data grid alerting system. A recommended approach for this type of integration is to construct a listener that writes the selected alert types into the logger mechanism. Examples of this are the log4j and commons-logging frameworks.

The main advantage to this approach is the ability to use an extensive set of out-of-the-box log appenders that translate log messages into different protocols and APIs to be consumed by third-party products.

AlertsLoggerBridge.jpg

AlertsLoggingGatway Example

The AlertLoggingGateway example provided with the GigaSpaces distribution uses an existing Log4J Appender (SnmpTrapAppender) to convert log messages into SNMP traps, resulting in the alerts being propagated to a third-party network management solution.

SNMP_Appender.jpg

Components

SnmpTrapTransmitter

The SnmpTrapTransmitter is a Processing Unit that is responsible for the generic Alert-to-Log bridging, and listens to all alerts in its alert filter file. Any incoming alerts are written to the commons log. The SnmpTrapTransmitter is generic and can therefore be reused in similar projects without any changes. The SnmpTrapTransmitter exposes the following configuration parameters:

  • AlertFileFilter - the name of Alert filter xml file used to filter Alerts to be logged.
    loggerName - the name of the logger to be created.
    group - the data grid group for which the Alert listener will be configured.
  <bean id="SnmpTrapTransmitter" class="org.openspaces.example.alert.logging.snmp.SnmpTrapTransmitter" >
    <property name="alertFileFilter" value="notify-alerts.xml" />
    <property name="loggerName" value="org.openspaces.example.alert.logging.AlertLoggingGateway" />
    <property name="group" value="group-name-here" />
  </bean>

If you implement your own variant for this class, then for other types of alert interceptions you also have to do the following:

  • Override the construct() method to register for alerts
  • Override the destroy() method to clean up the registration
  • Create your own class implementing the AlertTriggeredEventListener interface in which you will issue the logging calls.

See the following example:

public class SnmpTrapTransmitter {

    private Log logger;

    @PostConstruct
    public void construct() throws Exception {
        registerAlertTrapper();
    }

    @PreDestroy
    public void destroy() throws Exception {
            alertManager.getAlertTriggered().remove(atListener);
    }

    private void registerAlertTrapper() {
        atListener = new AlertTriggeredEventListener() {
            public void alertTriggered(Alert alert) {
                String loggRecord;
                loggRecord = alert.toString();
                logger.info(loggRecord);
            }
        };

        XmlAlertConfigurationParser cparse = new XmlAlertConfigurationParser(alertFileFilter);
        alertManager.configure(cparse.parse());
        alertManager.getAlertTriggered().add(atListener);
    }
}

SnmpTrapSender

The SnmpTrapSender is a utility class that implements the SnmpTrapAppender's SnmpTrapSenderFacade interface with an implementation that queues and asynchronously transmits Alerts as SNMP traps. The SNMP transmission method - sendTrap() - uses the snmp4j library as its underlying implementation.

public class SnmpTrapSender implements SnmpTrapSenderFacade {

    public void addTrapMessageVariable(String trapOID, String trapValue) {
        trapQueue.add(trapValue);
    }


    public void initialize(SNMPTrapAppender arg0) {
        trapQueue.clear();
        loadRunParams();
    }

    public void sendTrap() {
        String trapVal = trapQueue.removeFirst();
                PDUv1 trapPdu = (PDUv1)DefaultPDUFactory.createPDU(SnmpConstants.version1);
                trapPdu.setType(PDU.V1TRAP);
                // pack trapVal into trapPdu
        snmp.send(trapPdu, target);
    }

Logging

The Commons-logging.properties file is a commons logging configuration file that redirects its calls to a log4j logger. In our example, this file contains a redirection of commons-logging to log4j because the SNMP trapper used is on top of log4j. log4j.properties is a log4j configuration file that delegates log writes to the SNMPTrapAppender, resulting in SNMP traps.

log4j.rootCategory=INFO,TRAP_LOG
log4j.appender.TRAP_LOG=org.apache.log4j.ext.SNMPTrapAppender
log4j.appender.TRAP_LOG.ImplementationClassName=org.openspaces.example.alert.logging.snmp.SnmpTrapSender
log4j.appender.TRAP_LOG.ManagementHost=127.0.0.1
log4j.appender.TRAP_LOG.ManagementHostTrapListenPort=162
log4j.appender.TRAP_LOG.CommunityString=public
log4j.appender.TRAP_LOG.Threshold=INFO
log4j.appender.TRAP_LOG.layout=org.apache.log4j.PatternLayout
log4j.appender.TRAP_LOG.layout.ConversionPattern=%d,%p,%t,%c,%m%n

Using the AlertsLoggingGatway Example

External Dependencies

  • Minimum log4j version is 1.2.14

  • Minimum snmpTrapAppender version is 1.2.9

  • Minimum snmp4j version is 1.11.2

  • To build the example, you must have Apache Maven installed. You may find it already part of the GigaSpaces folders under \gigaspaces-xap\tools\maven.

Running the Example

The AlertsLoggingGatway example is located under <product>/tools/alert-integration.

To run the example:

  1. Set the group value in the pu.xml file to your own data grid group. (Optionally, you can edit the function registerAlertTrapper() in SnmpTrapTransmitter.java to create your own Admin object in any way you see fit.)

  2. (Optional) Edit the notify-alerts.xml file to set your own alerts and alert conditions that will be listened to by this example.

  3. (Optional) Edit log4j.properties to set the IP address and port used by your SNMP server software (if any).

  4. If you don't have SNMP server software, download one in order to run and test this example. For example, the iReasoning MIB browser (mibbrowser) provides good basic SNMP trap viewing capabilities with a free personal edition. Make sure to configure log4j.properties to use the same IPaddress and port used by the server.

  5. Install XAP's Maven dependencies to the local Maven repository by running the <XAP_root>/tools/maven/installmavenrep.sh(bat) script.

  6. Build and pack the sample project into a JAR file. This can be done by executing the command mvn from the project's root directory, or by performing an equivalent action within your UI. A successful build should result in the creation of the example JAR file in target/AlertLoggingGateway.jar.

  7. If needed, start the data grid with at least one running LUS, GSM and GSC belonging to the data grid group declared in step 1.

  8. Deploy the sample JAR to the GSC.

  9. If needed, perform data grid actions that will trigger one or more of the defined alerts. Creating a new GSC is usually a good way to creating a multitude of different alerts.

  10. Start up your SNMP server to intercept and view incoming traps. If you're using a MIB browser, enter the Trap Receiver (Ctrl-I) and make sure it is configured to listen on the correct IP address and port.