The JPPF statistics API

1 API description

The statistics in JPPF are handled with objects of type JPPFStatistics, which are a grouping of JPPFSnapshot objects, each snapshot representing a value that is constantly monitored, for instanc the number of nodes connected to a server, or the number of jobs in the server queue, etc.

JPPFSnapshot exposes the following API:

public interface JPPFSnapshot extends Serializable {
  // Get the total cumulated sum of the values
  double getTotal();

  // Get the latest observed value
  double getLatest();

  // Get the smallest observed value
  double getMin();

  // Get the peak observed value
  double getMax();

  // Get the average value
  double getAvg();

  // Get the label for this snapshot
  String getLabel();

  // Get the count of values added to this snapshot
  long getValueCount();
}

The label of a snapshot is expected to be unique and enables identifiying it within a JPPFStatistics object.

JPPF implements three different types of snapshots, each with a different semantics for the getLatest() method:

• CumulativeSnapshot: in this implementation, getLatest() is computed as the cumulated sum of all values added to the snapshot. If values are only added, and not removed, then it will always return the same value as getTotal().
• NonCumulativeSnapshot: here, getLatest() is computed as the average of the latest set of values that were added, or the latest value if only one was added.
• SingleValueSnapshot: in this implementation, only getTotal() is actually computed, all other methods return 0.

A JPPFStatistics object allows exploring the snapshots it contains, by exposing the following methods:

public class JPPFStatistics implements Serializable, Iterable<JPPFSnapshot> {
  // Get a snapshot specified by its label
  public JPPFSnapshot getSnapshot(String label)

  // Get all the snapshots in this object
  public Collection<JPPFSnapshot> getSnapshots()

  // Get the snapshots in this object using the specified filter
  public Collection<JPPFSnapshot> getSnapshots(Filter filter)

  @Override
  public Iterator<JPPFSnapshot> iterator()

  // A filter interface for snapshots
  public interface Filter {
    // Determines whether the specified snapshot is accepted by this filter
    boolean accept(JPPFSnapshot snapshot)
  }
}

Note that, since it implements Iterable<JPPFSnapshot>, a JPPFStatistics object can be used directly in a for loop:

JPPFStatistics stats = ...;
for (JPPFSnapshot snapshot: stats) {
  System.out.println("got '" + snapshot.getLabel() + "' snapshot");
}

Currently, only the JPPF driver holds and maintains a JPPFStatistics instance. It can be obtained directly with:

JPPFStatistics stats = JPPFDriver.getInstance().getStatistics();

It can also be obtained remotely via the manegement APIs, as described in the section Management and monitoring > Server management > Server statistics of this documentation.

Additionally, the class JPPFStatisticsHelper holds a set of constants definitions for the labels all all the snapshots currently used in JPPF, along with a number of utility methods to ease the use of statistics:

public class JPPFStatisticsHelper {
  // Count of tasks dispatched to nodes
  public static String TASK_DISPATCH = "task.dispatch";

  // ... other constant definitions ...

  // Determine wether the specified snapshot is a single value snapshot
  public static boolean isSingleValue(JPPFSnapshot snapshot)

  // Determine wether the specified snapshot is a cumulative snapshot
  public static boolean isCumulative(JPPFSnapshot snapshot)

  // Determine wether the specified snapshot is a non-cumulative snapshot
  public static boolean isNonCumulative(JPPFSnapshot snapshot)

  // Get the translation of the label of a snapshot in the current locale
  public static String getLocalizedLabel(JPPFSnapshot snapshot)

  // Get the translation of the label of a snapshot in the specified locale
  public static String getLocalizedLabel(JPPFSnapshot snapshot, Locale locale)
}

The getLocalizedLabel() methods provide a short, localized description of what the snapshot is.

Note: at this time, only English translations are available.

2 Statistics snapshots reference by type

The table below provides a list of the existing server statistics snapshots grouped by type. The snapshot names correspond to the names of the constants defined in JPPFStatisticsHelper.

To obtain the corresponding JPPFSnapshot from a JPPFStatistics object, you can write code similar to the following:

JPPFStatistics stats = ...;
JPPFSnapshot snapshot = stats.getSnapshot(JPPFStatisticsHelper.NODE_EXECUTION);