com.bigdata.ganglia

Class GangliaService

java.lang.Object

com.bigdata.ganglia.GangliaService

All Implemented Interfaces:

IGangliaMetricsReporter, Runnable

Direct Known Subclasses:

BigdataGangliaService

public class GangliaService
extends Object
implements Runnable, IGangliaMetricsReporter

A full ganglia-aware service suitable for embedding with a Java application. The service listens for metrics declarations (ganglia metadata records), metric data, and metric requests. Metric requests are honored as is the restart protocol necessary to avoid multicast storms. In addition to its role as a listener, the service multicasts metric declarations and metrics obtained either from the underlying platform (OS/host) or from the application into which this service is embedded.

Applications can embed this service by adding their own IGangliaMetadataFactory instances (to get nice metric declarations) and can register an IGangliaMetricsCollector to periodically report performance metrics out to the ganglia network. You can also use setMetric(String, Object) to directly update a metric.

The ganglia protocol replicates soft state into all gmond and gmetad instances. The GangliaService is a full participant in the protocol and will also develop a snapshot of the soft state of the cluster. This protocol has a lot of benefits, but the metadata declarations can stick around and be discovered long after you have shutdown the GangliaService.

When developing with the embedded GangliaService it is a Good Idea to use a private gmond / gmetad configuration (non-default address and/or port). Then, if you wind up making some mistakes when declaring your application counters and those mistakes replicated into the soft state of the ganglia services you can just shutdown your private service instances.

Another trick is to use the [mock] mode (it is a constructor argument) while you are developing so the GangliaService does not actually send out any packets.

Finally, there is also a utility class (in the test suite) which can be used to monitor the ganglia network for packets which can not be round-tripped. This can be used to identify bugs if you are doing development on embedded GangliaService code base.

Author:

thompsonbry@users.sourceforge.net TODO Only allows one join group and port for listening and only listens by joining a multicast group.

Unicast support should not be that different. The list of metricsServers is fine for sending data whether using unicast or multicast. I need to experiment with a (list of) addresses for receiving data. Note that ganglia supports more than one address and port for unicast or multicast. It should not be difficult to do the same thing under java. FIXME Setup a JXM bridge for counters. Anything which make it into ganglia or perhaps anything which is declared in our counters hierarchy. TODO Turn off heartbeat automatically if we detect a heartbeat with a different timestamp while this GangliaService is running. That will help us avoid stomping on gmond. TODO Setup a listener for TCP connections on the same port that we listen on for UDP. If there is a connection, then respond by streaming the XML data for the current counters. The XML DTD (and sample data) can be obtained using telenet localhost 8649. This is the hook used for the ganglia web UI, some nagios integrations, etc. FIXME Provide a sample collector for the JVM and use it in main(). TODO Port the more sophisticated collectors into this module?

See Also:

The ganglia monitoring system, diagnose multicast applications

Field Summary

Fields

Modifier and Type	Field and Description
static String	HOSTNAME The name of an environment variable whose value will be used as the canoncial host name for the host running this JVM.

Constructor Summary

Constructors

Constructor and Description
GangliaService(String serviceName) Simple constructor uses the defaults for everything except the heartbeart.
GangliaService(String hostName, String serviceName, InetSocketAddress[] metricsServers, InetAddress listenGroup, int listenPort, boolean listen, boolean report, boolean mock, int quietPeriod, int initialDelay, int heartbeatInterval, int monitoringInterval, int globalDMax, IGangliaMetadataFactory metadataFactory) Core constructor for an embedded GangliaService - see run() to actually run the service.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	addMetricCollector(IGangliaMetricsCollector c) Register a metrics collector.
protected void	gatherMetrics() Runs each IGangliaMetricsCollector in turn.
static String	getCanonicalHostName() The name for this host.
String[]	getDefaultHostReportOn() Return a copy of the default metrics used to generate IHostReport s.
IGangliaState	getGangliaState() The soft-state as maintained using the ganglia protocol and including any metrics collected by this host regardless of whether they are being reported to other hosts.
String	getHostName() The name of the host on which this GangliaService is running as it will be reported through IGangliaMessages to other ganglia services.
IHostReport[]	getHostReport() Return a host report based on the current state (similar to gstat -a).
IHostReport[]	getHostReport(String[] reportOn, Comparator<IHostReport> comparator) Return a host report based on the current state (similar to gstat -a).
IHostReport[]	getHostReport(String[] hosts, String[] reportOn, Comparator<IHostReport> comparator) Return a host report based on the current state (similar to gstat -a).
IGangliaMetadataFactory	getMetadataFactory() Return the factory for metric declarations.
protected boolean	isListening() Return true if the GangliaService is currently listening.
protected boolean	isQuietPeriod() Return true iff this service is in its quite period.
static void	main(String[] args) Runs a GangliaService as a standalone application.
boolean	removeMetricCollector(IGangliaMetricsCollector c) Remove a metrics collector.
void	run() Run the ganglia service.
protected void	sendMessage(IGangliaMessage msg) Queue an IGangliaMessage to be sent to the network.
void	setMetric(String metricName, Object value) Set the value of a metric.
protected long	uptime() Return the time in seconds since the last service start.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HOSTNAME

public static final String HOSTNAME

The name of an environment variable whose value will be used as the canoncial host name for the host running this JVM. This information is used by the GangliaService, which is responsible for obtaining and reporting the canonical hostname for host metrics reporting.

See Also:

Provide workaround for bad reverse DNS setups, Constant Field Values

Constructor Detail

GangliaService

public GangliaService(String serviceName)
               throws UnknownHostException

Simple constructor uses the defaults for everything except the heartbeart.

Note: The heartbeat is set to ZERO (0) under the assumption that gmond will be running on the same host. The GangliaService MUST NOT send out a heartbeat if gmond is also running on the host since the two heartbeats will be different (they are the start time of gmond) and gmond and gmetad will both get confused.

Parameters:

serviceName - The name of the service in which you are embedding ganglia support.

Throws:

UnknownHostException

GangliaService

public GangliaService(String hostName,
              String serviceName,
              InetSocketAddress[] metricsServers,
              InetAddress listenGroup,
              int listenPort,
              boolean listen,
              boolean report,
              boolean mock,
              int quietPeriod,
              int initialDelay,
              int heartbeatInterval,
              int monitoringInterval,
              int globalDMax,
              IGangliaMetadataFactory metadataFactory)

Core constructor for an embedded GangliaService - see run() to actually run the service.

Parameters:

hostName - The name of this host.

serviceName - The name of the service which is embedding ganglia support.

metricsServers - The unicast or multicast addresses for sending out packets.

listenGroup - The multicast join group on which to listen for packets.

listenPort - The port for the multicast join group.

listen - true iff the service should listen for packets.

report - true iff the service should report metrics.

mock - true iff the service should do everything EXCEPT sending out the packets (they are logged instead). This is a debugging option.

quietPeriod - The ganglia quiet period.

initialDelay - The initial delay before metrics are reported.

heartbeatInterval - The ganglia heartbeat interval. Use ZERO (0) if you are running gmond on the same host. That will prevent the GangliaService from transmitting a different heartbeat, which would confuse gmond and gmetad.

monitoringInterval - The delay between sweeps to collect performance counters from the application.

globalDMax - The global value of DMax.

metadataFactory - An application hook for providing nice metric declarations.

See Also:

IGangliaDefaults

Method Detail

getDefaultHostReportOn

public String[] getDefaultHostReportOn()

Return a copy of the default metrics used to generate IHostReport s.

See Also:

getHostReport()

uptime

protected long uptime()

Return the time in seconds since the last service start.

Throws:

IllegalStateException - if the service is not running.

isQuietPeriod

protected boolean isQuietPeriod()

Return true iff this service is in its quite period.

Ganglia has a quiet period for 10m after a service start. During that quiet period a metadata request will not cause the timestamp of the metrics to be reset.

isListening

protected boolean isListening()

Return true if the GangliaService is currently listening.

run

public void run()

Run the ganglia service.

Specified by:

run in interface Runnable

sendMessage

protected void sendMessage(IGangliaMessage msg)

Queue an IGangliaMessage to be sent to the network.

Parameters:

msg - The message.

gatherMetrics

protected void gatherMetrics()

Runs each IGangliaMetricsCollector in turn.

addMetricCollector

public boolean addMetricCollector(IGangliaMetricsCollector c)

Register a metrics collector.

Parameters:

c - The collector.

Returns:

true iff it was not already registered.

removeMetricCollector

public boolean removeMetricCollector(IGangliaMetricsCollector c)

Remove a metrics collector.

Parameters:

c - The collector.

Returns:

true iff it is no longer registered.

setMetric

public void setMetric(String metricName,
             Object value)

Set the value of a metric. This routine is typically invoked by IGangliaMetricsCollectors. However, you can also simply invoke it directly.

Note: In order to get a nice metadata declaration for the record, the application should also register an IGangliaMetadataFactory.

Specified by:

setMetric in interface IGangliaMetricsReporter

Parameters:

metricName - The name of the metric.

value - The metric value.

See Also:

getMetadataFactory()

getHostName

public String getHostName()

The name of the host on which this GangliaService is running as it will be reported through IGangliaMessages to other ganglia services.

getGangliaState

public IGangliaState getGangliaState()

The soft-state as maintained using the ganglia protocol and including any metrics collected by this host regardless of whether they are being reported to other hosts.

getMetadataFactory

public IGangliaMetadataFactory getMetadataFactory()

Return the factory for metric declarations. If you supply a GangliaMetadataFactory instance to the constructor (which is the default behavior for the reduced constructor) then you can extend the default behavior in order to get nice metadata declarations for your application metrics.

getHostReport

public IHostReport[] getHostReport()

Return a host report based on the current state (similar to gstat -a).

Note: The report will not be accurate immediately as the GangliaService needs to build up a model of the current state of the monitored hosts.

getHostReport

public IHostReport[] getHostReport(String[] reportOn,
                          Comparator<IHostReport> comparator)

Return a host report based on the current state (similar to gstat -a).

Note: The report will not be accurate immediately as the GangliaService needs to build up a model of the current state of the monitored hosts.

Parameters:

reportOn - The metrics to be reported for each host. The IHostReport.getMetrics() is an ordered map and will reflect the metrics in the order in which they are requested here.

comparator - The comparator used to order the IHostReports.

Returns:

The IHostReports for each known host ordered by the given Comparator.

getHostReport

public IHostReport[] getHostReport(String[] hosts,
                          String[] reportOn,
                          Comparator<IHostReport> comparator)

Return a host report based on the current state (similar to gstat -a).

Note: The report will not be accurate immediately as the GangliaService needs to build up a model of the current state of the monitored hosts.

Parameters:

hosts - The hosts for which host reports will be returned.

reportOn - The metrics to be reported for each host. The IHostReport.getMetrics() is an ordered map and will reflect the metrics in the order in which they are requested here.

comparator - The comparator used to order the IHostReports (optional).

Returns:

The IHostReports for each specified host ordered by the given Comparator.

getCanonicalHostName

public static final String getCanonicalHostName()

The name for this host.

See Also:

HOSTNAME, Provide workaround for bad reverse DNS setups

main

public static void main(String[] args)
                 throws Exception

Runs a GangliaService as a standalone application.

Note: This routine is mainly for test as the primary purpose of the GangliaService is to embed it within another application.

Parameters:

args - ignored.

Throws:

Exception