SMILA/Project Concepts/Performance counters API

Overview

System components can report their state as numeric/timestamp data using Performance Counters API. Those value can be accessed via JMX interface remotely to analyze system workload. The API implementation is similar to the one in the .NET in naming and approach.

Major API classes

• PerformanceCounter - the actual counter which value is sampled for system components monitoring.
• PerformanceSample - counter sample containing sample base value (number of operations preceding the time of sample), raw value (the actual counter value) and the sampling timestamp
• CounterFormula - formula used to calculate the value of the counter using the last two samples.
• CounterCategory - counter catagory used to group counters.
• CounterRegistry - the counters registry where they can be accessed/registered by name & category name.

CounterRegistry has four static fields representing predefined counter formulas:

Formula	Description
CounterRegistry.SIMPLE_COUNT_FORMULA	Simple items count formula returning the counter raw value
CounterRegistry.AVERAGE_FORMULA	Average count formula calculates how many items are processed, on average, during an operation. The formula is (Xn - X0)/(Bn - B0) where Xi is a counter sample and the Bi is the corresponding base value (number of counter changes).
CounterRegistry.RATE_FORMULA	Rate formula calculates (Xn - X0)/(Tn - T0), where Xi is a counter sample and Ti is the time that the corresponding sample was taken. The result is the average usage per second.
CounterRegistry.AVERAGE_TIMER_FORMULA	Average timer formulla calculates the time (in seconds) it takes, on average, to complete a process or operation. The formula is (Tn - T0)/(Bn - B0) where Bi is base value and the Ti is corresponding timestamp.

API Usage

Creating a new counter

CounterRegistry is a singleton which can be accessed only with static CounterRegistry.INSTANCE reference. Create a new PerformanceCounter instance, specify counter name, category name & formula. If a category given doesn't exist, create it using createCategory() method. Bind the counter to the registry.

CounterRegistry.INSTANCE.createCategory(CATEGORY_NAME);
 
final PerformanceCounter counter = new PerformanceCounter(COUNTER_NAME, CATEGORY_NAME, CounterRegistry.AVERAGE_FORMULA);
CounterRegistry.INSTANCE.bindCounter(counter);

Obtaining a counter reference and value reading/writing

Existing counter can be obtained from the registry using getCounter method. PerformanceCounter provides the following methods for value changing:

interface PerformanceCounter
{
    increment()
    incrementBy()
    decrement()
    decrementBy()
}

Also the raw value can be set directly with setRawValue() method.

To get the calculated counter value call the getNextValue() method. Note that counter must be sampled before acquiring the formula calculated value.

JMX counters

Performance counters value can be accessible via JMX interface using the RemoteCountersRegistry. To use that feature start JVM with the following arguments:

-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.ssl=false
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.port=9004

OSGi Bundle usage

To use Performance counters API into some OSGi bundle,

org.eccenca.performancecounters

package must be imported into that bundle. Use Import-Package directive in your bundle's MANIFEST.MF:

Import-Package: org.eccenca.performancecounters

Here is the sample MANIFEST.MF file:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Example Plug-in
Bundle-SymbolicName: JMXCounters.example
Bundle-Version: 1.0.0
Bundle-Activator: jmxcounters.example.Activator
Import-Package: org.eccenca.performancecounters,
 org.osgi.framework;version="1.3.0"
Eclipse-LazyStart: true