This article explains how to use Stream-JMX programmatically to schedule and manage the collection of JMX metrics. It covers samplers, filters, multiple MBean servers, and the SamplingAgent helper class.
Coding
// obtain SamplerFactory instance
SamplerFactory factory = DefaultSamplerFactory.getInstance();
// create an instance of the sampler that will sample MBeans
Sampler sampler = factory.newInstance();
// schedule collection (ping) for given MBean filter and 30000 ms sampling period
Map<String, Object> samplerCfg = new HashMap<>(3);
samplerCfg.put(SampleHandler.CFG_INCLUDE_FILTER, Sampler.JMX_FILTER_ALL);
samplerCfg.put(Sampler.CFG_SAMPLING_PERIOD, 30000);
sampler.setSchedule(samplerCfg).run();
The setSchedule(..).run() sequence
must be called to run the schedule. setSchedule(..) just
sets the scheduling parameters, run() executes the schedule.
To schedule metric collection for a specific MBean server:
// obtain SamplerFactory instance
SamplerFactory factory = DefaultSamplerFactory.getInstance();
// create an instance of the sampler that will sample MBeans
Sampler sampler = factory.newInstance(ManagementFactory.getPlatformMBeanServer());
// schedule collection (ping) for given MBean filter and 30000 ms sampling period
Map<String, Object> samplerCfg = new HashMap<>(3);
samplerCfg.put(SampleHandler.CFG_INCLUDE_FILTER, Sampler.JMX_FILTER_ALL);
samplerCfg.put(Sampler.CFG_SAMPLING_PERIOD, 30000);
sampler.setSchedule(samplerCfg).run();Stream-JMX supports both inclusion and exclusion filters. To schedule metric collection for a specific MBean server while excluding certain MBeans, use the following example.
(Note: Exclusion filters are applied after inclusion filters)
// obtain SamplerFactory instance
SamplerFactory factory = DefaultSamplerFactory.getInstance();
// create an instance of the sampler that will sample MBeans
Sampler sampler = factory.newInstance(ManagementFactory.getPlatformMBeanServer());
// schedule collection (ping) for given MBean filter and 30000 ms sampling period
Map<String, Object> samplerCfg = new HashMap<>(3);
samplerCfg.put(SampleHandler.CFG_INCLUDE_FILTER, Sampler.JMX_FILTER_ALL);
samplerCfg.put(SampleHandler.CFG_EXCLUDE_FILTER, "mydomain:*");
samplerCfg.put(Sampler.CFG_SAMPLING_PERIOD, 30000);
sampler.setSchedule(samplerCfg).run();Below is an example of how to sample all registered MBean servers:
// obtain SamplerFactory instance
SamplerFactory factory = DefaultSamplerFactory.getInstance();
// find other registered MBean servers
ArrayList<MBeanServer> mlist = MBeanServerFactory.findMBeanServer(null);
Map<String, Object> samplerCfg = new HashMap<>(3);
samplerCfg.put(SampleHandler.CFG_INCLUDE_FILTER, Sampler.JMX_FILTER_ALL);
samplerCfg.put(Sampler.CFG_SAMPLING_PERIOD, 30000);
for (MBeanServer server: mlist) {
Sampler jmxp = factory.newInstance(server);
jmxp.setSchedule(samplerCfg).run();
}Alternatively, Stream-JMX provides a helper class, SamplingAgent, that allows you to schedule sampling for all registered MBeanServer instances.
SamplingAgent.newSamplingAgent().sample(Sampler.JMX_FILTER_ALL, Sampler.JMX_FILTER_NONE, 60000, TimeUnit.MILLISECONDS);
Sampled MBean attributes and their values are stored in a collection of Snapshot objects within an Activity instance. The current Activity instance can be obtained via the AttributeSample passed when calling listeners such as AttributeCondition, or SampleListener. Snapshots can be accessed using Activity.getSnapshots() method call.
Sampled output is written to underlying tnt4j event sink configured in tnt4j.properties file. Sink destinations could include a file, socket, log4j, user defined event sink implementations.
For more information on TNT4J and tnt4j.properties see TNT4J Wiki.
Command line to run
The example below runs SamplingAgent helper class as a standalone java application with a given MBean filter "*:*", sampling period in milliseconds (10000), and time to run in milliseconds (60000):
java -Dlog4j2.configurationFile=./config/log4j2.xml -classpath "*;lib/*" com.jkoolcloud.tnt4j.stream.jmx.SamplingAgent "*:*" "" 10000 60000