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