Chapter 55. Ganglia

Ganglia Component

Available as of Camel 2.15.0
The Ganglia component provides a mechanism to send a value (the message body) as a metric to the Ganglia monitoring system, using the gmetric4j library. It can be used in conjunction with standard Ganglia and JMXetric to monitor metrics from the operating system, JVM, and business processes through a single platform.
You should have a Ganglia gmond agent running on the same machine as your JVM. The agent sends a heartbeat to the Ganglia infrastructure, which camel-ganglia is currently unable to do.
On most Linux systems (RHEL and CentOS with EPEL, Fedora, Debian, and Ubuntu), you can install just the Ganglia agent package. It will run automatically in multicast mode, but you can configure it to run in regular UDP unicast mode.
Maven users will need to add the following dependency to their pom.xml for this component:
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-ganglia</artifactId>
    <version>2.17.0.redhat-630187</version>
    <!-- use the same version as your Camel core version -->
</dependency>

URI format

ganglia:address:port[?options]
You can append query options to the URI using this format: ?option=value&option=value&...

Ganglia Endpoint Options

Name Default Description Override w/ header
mode MULTICAST Specifies the addressing mode to use to send the UDP metric packets. Valid values are: MULTICAST or UNICAST.
ttl 5 When using MULTICAST, specifies packets' time-to-live.
wireFormat31x true Specifies the wire format to use. true sets the wire format to Ganglia v3.1.0 and later. false sets the wire format to Ganglia v3.0.x or earlier.
groupName Java Specifies the group to which the metric belongs.
prefix [Optional] Specifies the string prefix to add to metricName. An underscore is automatically added to the prefix.
metricName metric
Specifies the name to use for the metric.
GangliaConstants.METRIC_NAME
type STRING Specifies the metric's type. (STRING, INT8|16|32, UINT8|16|32, FLOAT, DOUBLE) GangliaConstants.METRIC_TYPE
slope BOTH
Specifies the slope of the metric's lifetime, which determines how the metric data are stored. Valid values are:
  • ZERO—the value never changes
  • POSITIVE—the value either increases or stays the same
  • NEGATIVE—the value either decreases or stays the same
  • BOTH—the value can increase or decrease
GangliaConstants.METRIC_SLOPE
units
[Optional] Specifies the unit of measurement that qualifies the metric's value (such as bytes, seconds, Celsius, liters, and so on.
Do not use prefixes (k [kilo], m [milli], and so on) to scale the units, as other tools may do so later. The value should also be unscaled.
GangliaConstants.METRIC_UNITS
tmax 60
Specifies the maximum time in seconds between gmetric calls. After tmax, Ganglia considers the current value expired.
GangliaConstants.METRIC_TMAX
dmax 0
Specifies the lifetime in seconds of the specified metric.
GangliaConstants.METRIC_DMAX

Message Body

Any value, such as a string or numeric type, in the message body is sent to the Ganglia monitoring system.

Return Value/Response

Ganglia sends metrics using unidirectional UDP or multicast. There is no response or change to the message body.

Sending a String Metric

The message body is converted to a String and sent as a metric value. Unlike numeric metrics, String values cannot be charted, but Ganglia makes them available for reporting. The os_version string at the top of every Ganglia host page is an example of a String metric.
from("direct:string.for.ganglia")
    .setHeader(GangliaConstants.METRIC_NAME, simple("my_string_metric"))
    .setHeader(GangliaConstants.METRIC_TYPE, GMetricType.STRING)
    .to("direct:ganglia.tx");
     
from("direct:ganglia.tx")
    .to("ganglia:239.2.11.71:8649?mode=MULTICAST&prefix=test");

Sending a Numeric Metric

from("direct:value.for.ganglia")
    .setHeader(GangliaConstants.METRIC_NAME, simple("widgets_in_stock"))
    .setHeader(GangliaConstants.METRIC_TYPE, GMetricType.UINT32)
    .setHeader(GangliaConstants.METRIC_UNITS, simple("widgets"))
    .to("direct:ganglia.tx");
     
from("direct:ganglia.tx")
    .to("ganglia:239.2.11.71:8649?mode=MULTICAST&prefix=test");