Metrics access

Two types of metrics are provided by the IBM® Streams instance, namely system and custom metrics. System metrics are predefined and are maintained by the IBM Streams instance. Custom metrics are created and maintained by the operators.

System metrics

System metrics come in two varieties: operator-level metrics and processing element-level metrics. Operator-level metrics are accessed through the getMetrics() member function of the OperatorContext class, which returns an object of type OperatorMetrics. The operator context object is accessible through the getContext() member function of the operator.

Individual operator-level metrics are available through the getInputPortMetric(port, metric) and getOutputPortMetric(port, metric) methods of the OperatorMetrics class, where port is the port index and metric is the name of the metric (of OperatorMetrics::InputPortMetricName and OperatorMetrics::OutputPortMetricName type). The available metrics include:

Processing element-level metrics are accessed through the getMetrics() member function of the ProcessingElement class, which returns an object of type PEMetrics. The processing element object is accessible through the getPE() member function of the operator.

Individual processing element-level metrics are available through the getInputPortMetric(port, metric) and getOutputPortMetric(port, metric) methods of the PEMetrics class, where port is the port index and metric is the name of the metric (of PEMetrics::InputPortMetricName and PEMetrics::OutputPortMetricName type).

The Metric class is used to represent a metric. Each metric has a short name, a description, and a value of type int64. System metrics can be read, but cannot be written.

The available metrics include:

In addition to the processing element-level metrics described in Table 2, processing element-level connection metrics are provided by the system. The available metrics include:

Each processing element output port can be connected to zero or more input ports on other processing elements. The connection information can be accessed by using ProcessingElement::getOutputPortConnections(), which returns a list of information about each connection, including the congestion factor for this connection and the nTuplesFilteredOut metric for the connection. From SPL, the information can be returned by using the native function spl.utility::getPEOutputPortConnections().

If a processing element restarts, all system metrics are reset to their initial values.

Custom metrics

Custom metrics that are listed in the operator model are automatically instantiated by the IBM Streams instance.

The names of all the custom metrics can be found by calling the getCustomMetricNames() member function of the OperatorMetric class. The custom metrics can be accessed at run time by the getCustomMetricByName(name) member function of the OperatorMetric class. More metrics can be created explicitly at run time, by using the createCustomMetric(name, description, kind) member function. For both functions, the returned metric objects of type Metric are owned by the IBM Streams instance, but the operator can update their value freely. The value of the metric can be updated by the use of setValue(newValue) and incrementValue(incValue) functions.

If a processing element restarts, custom metrics are reset to their initial value unless they are explicitly reset by the operator from a previous checkpoint.

// member variable in operator
Metric * numInterestingEvents_;
...
// create the metric
OperatorMetrics  & opm = getContext().getMetrics();
numInterestingEvents_ = & opm.createCustomMetric("nInterestingEvents",
    "Number of very interesting events seen so far", Metric::Counter);
...
// update the metric
numInterestingEvents_->setValue(numEvents);
// increment the value
numInterestingEvents_->incrementValue(10);