Follow

How To Send Heartbeat Events From Applications

Pre-Requisites

  • The application must be able to connect to the XML-RPC port 8081 on the Zenoss master.

Applies To

  • Zenoss 4.0.x
  • Zenoss 3.1.x
  • Zenoss 3.0.x

Summary

It is desirable in some circumstances to have applications generate heartbeat events as a non-intrusive way of determining basic functionality of the application stack.  Naturally, an end-to-end transaction that exercises all portions of the application stack are a much more meaningful check (this is also known as a "synthetic transaction"), but this is sometimes not possible or desirable (for example due to specific security controls or audit concerns).

Procedure

Example: Sending a Heartbeat through a zensendevent

The updated zensendevent command can be used to send the extra required timeout field needed for heartbeats. Here is an example usage:

zensendevent -c /Heartbeat -p application_name -d mydevice -s Critical -o timeout=300 "Testing"

Notes:

  • The event class MUST be /Heartbeat -- not even a subclass of /Heartbeat, just /Heartbeat.
  • The timeout field determines, in seconds, the amount of time for which a heartbeat event must be received, or else the zenactions daemon will generate a heartbeat event. If the timeout field is not specified, a traceback will occur.

Example: Sending a Heartbeat through a Perl Script

The following script is a Perl example of sending through XML-RPC:

#!/usr/bin/perl -sw

use Frontier::Client;

$creds = "admin:zenoss";
$host = "localhost:8081";
$url = "http://$creds\@$host";

%evt = (
   "component" => "myApplication",
   "summary" => "Heartbeat",
   "eventClass" => "/Heartbeat",

   "device" => "mydevice",

   "timeout" => 30,
   "severity" => 5,
 #  "monitor" => "localhost",
);

$serv = Frontier::Client->new(url => $url, debug => 10);
$resp = $serv->call("sendEvent", \%evt);

This will generate something like the following output:

---- request ----

sendEvent

eventClass/Heartbeat
summaryHeartbeat
componentmyApplication
timeout30
severity5

---- response ----

none

To disable the information about packets being shipped back and forth, remove the debug variable from the new() call.

Example: Sending an Event through Java

The following is the code that we will put into a file called JavaRPCExample.java:

import java.net.URL;
import java.util.HashMap;

import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;

public class JavaRPCExample {

  public static void main(String[] args) throws Exception {
      XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
      config.setServerURL(new URL( "http://localhost:8081"));
      config.setBasicUserName("admin");
      config.setBasicPassword("zenoss");
      XmlRpcClient client = new XmlRpcClient();
      client.setConfig(config);
      HashMap params = new HashMap();
      params.put("device", "mydevice");
      params.put("component", "myApplication");
      params.put("summary", "Heartbeat");
      params.put("timeout", 30);
      params.put("severity", 4);
      params.put("eventClass", "/Heartbeat");
      client.execute("sendEvent", new Object[]{params});
  }
}
 

Here's the rough outline of how to run this example:

# Get the JDK (**not** the JRE -- doh!) for your platform
# .... install JDK ....
#  Get Java XML-RPC libraries
wget 'http://apache.sunsite.ualberta.ca/ws/xmlrpc/apache-xmlrpc-current-bin.tar.gz'
tar xzf apache-xmlrpc-current-bin.tar.gz
cd apache-xmlrpc-3.1.2/lib
# Copy the JavaRPCExample.java file into place
cp /tmp/JavaRPCExample.java .
# Compile....
javac -d . -cp 'ws-commons-util-1.0.2.jar:xmlrpc-client-3.1.2.jar:xmlrpc-common-3.1.2.jar' JavaRPCExample.java
# Run...
java  -cp 'ws-commons-util-1.0.2.jar:xmlrpc-client-3.1.2.jar:xmlrpc-common-3.1.2.jar:.' JavaRPCExample

Generating an Alert from the Heartbeat Timeout Event

Assuming that the zenactions daemon is running, and the zensendevent (or equivalent event sending action) is successful, there will not be a heartbeat event in the console or anything associated with a device, but there will be an entry in the MySQL table events.heartbeat. If no additional heartbeat messages are sent, then sometime after the timeout in the heartbeat message, a new event should be generated that will be visible in the console stating that the component (such as a daemon) is missing heartbeats.  The specific fields from the event that will be used in the heartbeat failure event are subject to change, but currently a heartbeat failure event will be populated with the following fields:

device
component
eventClass /Status/Heartbeat

summary "%s %s heartbeat failure" % (device, component)

severity Error

Any transforms or event mappings should be applied to the /Status/Heartbeats event class.  Note that changing the device name will cause the event to be cleared and then re-added as a new event, causing a large number of alert flappings.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk