10 June 2024

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.

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.

Components

SnmpTrapTransmitter

The SnmpTrapTransmitter is a Processing Unit This is the unit of packaging and deployment in the GigaSpaces Data Grid, and is essentially the main GigaSpaces service. The Processing Unit (PU) itself is typically deployed onto the Service Grid. When a Processing Unit is deployed, a Processing Unit instance is the actual runtime entity. 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.

Running the Example

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

To run the example:

Set the group value in the pu This is the unit of packaging and deployment in the GigaSpaces Data Grid, and is essentially the main GigaSpaces service. The Processing Unit (PU) itself is typically deployed onto the Service Grid. When a Processing Unit is deployed, a Processing Unit instance is the actual runtime entity..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.)
(Optional) Edit the notify-alerts.xml file to set your own alerts and alert conditions that will be listened to by this example.
(Optional) Edit log4j.properties to set the IP address and port used by your SNMP server software (if any).
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.
Install GigaSpaces's Maven dependencies to the local Maven repository by running the <product>/bin/gs maven install script.
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.
If needed, start the data grid with at least one running LUS Lookup Service. This service provides a mechanism for services to discover each other. Each service can query the lookup service for other services, and register itself in the lookup service so other services may find it., GSM Grid Service Manager. This is is a service grid component that manages a set of Grid Service Containers (GSCs). A GSM has an API for deploying/undeploying Processing Units. When a GSM is instructed to deploy a Processing Unit, it finds an appropriate, available GSC and tells that GSC to run an instance of that Processing Unit. It then continuously monitors that Processing Unit instance to verify that it is alive, and that the SLA is not breached. and GSC Grid Service Container. This provides an isolated runtime for one (or more) processing unit (PU) instance and exposes its state to the GSM. belonging to the data grid group declared in step 1.
Deploy the sample JAR to the GSC.
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.
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.