org.apache.kafka.common.metrics.stats

Class Frequencies

java.lang.Object

org.apache.kafka.common.metrics.stats.SampledStat

org.apache.kafka.common.metrics.stats.Frequencies

All Implemented Interfaces:

CompoundStat, Measurable, MeasurableStat, MetricValueProvider<Double>, Stat

public class Frequencies
extends SampledStat
implements CompoundStat

A CompoundStat that represents a normalized distribution with a Frequency metric for each bucketed value. The values of the Frequency metrics specify the frequency of the center value appearing relative to the total number of values recorded.

For example, consider a component that records failure or success of an operation using boolean values, with one metric to capture the percentage of operations that failed another to capture the percentage of operations that succeeded.

This can be accomplish by created a Sensor to record the values, with 0.0 for false and 1.0 for true. Then, create a single Frequencies object that has two Frequency metrics: one centered around 0.0 and another centered around 1.0. The Frequencies object is a CompoundStat, and so it can be added directly to a Sensor so the metrics are created automatically.

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.kafka.common.metrics.stats.SampledStat

SampledStat.Sample

Nested classes/interfaces inherited from interface org.apache.kafka.common.metrics.CompoundStat

CompoundStat.NamedMeasurable

Field Summary

Fields inherited from class org.apache.kafka.common.metrics.stats.SampledStat

samples

Constructor Summary

Constructors

Constructor and Description
Frequencies(int buckets, double min, double max, Frequency... frequencies) Create a Frequencies that captures the values in the specified range into the given number of buckets, where the buckets are centered around the minimum, maximum, and intermediate values.

Method Summary

Modifier and Type	Method and Description
double	combine(List<SampledStat.Sample> samples, MetricConfig config, long now)
static Frequencies	forBooleanValues(MetricName falseMetricName, MetricName trueMetricName) Create a Frequencies instance with metrics for the frequency of a boolean sensor that records 0.0 for false and 1.0 for true.
double	frequency(MetricConfig config, long now, double centerValue) Return the computed frequency describing the number of occurrences of the values in the bucket for the given center point, relative to the total number of occurrences in the samples.
protected org.apache.kafka.common.metrics.stats.Frequencies.HistogramSample	newSample(long timeMs)
List<CompoundStat.NamedMeasurable>	stats()
protected void	update(SampledStat.Sample sample, MetricConfig config, double value, long timeMs)

Methods inherited from class org.apache.kafka.common.metrics.stats.SampledStat

current, measure, oldest, purgeObsoleteSamples, record, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.kafka.common.metrics.Stat

record

Constructor Detail

Frequencies

public Frequencies(int buckets,
                   double min,
                   double max,
                   Frequency... frequencies)

Create a Frequencies that captures the values in the specified range into the given number of buckets, where the buckets are centered around the minimum, maximum, and intermediate values.

Parameters:

buckets - the number of buckets; must be at least 1

min - the minimum value to be captured

max - the maximum value to be captured

frequencies - the list of Frequency metrics, which at most should be one per bucket centered on the bucket's value, though not every bucket need to correspond to a metric if the value is not needed

Throws:

IllegalArgumentException - if any of the Frequency objects do not have a center value within the specified range

Method Detail

forBooleanValues

public static Frequencies forBooleanValues(MetricName falseMetricName,
                                           MetricName trueMetricName)

Create a Frequencies instance with metrics for the frequency of a boolean sensor that records 0.0 for false and 1.0 for true.

Parameters:

falseMetricName - the name of the metric capturing the frequency of failures; may be null if not needed

trueMetricName - the name of the metric capturing the frequency of successes; may be null if not needed

Returns:

the Frequencies instance; never null

Throws:

IllegalArgumentException - if both falseMetricName and trueMetricName are null

stats

public List<CompoundStat.NamedMeasurable> stats()

Specified by:

stats in interface CompoundStat

frequency

public double frequency(MetricConfig config,
                        long now,
                        double centerValue)

Return the computed frequency describing the number of occurrences of the values in the bucket for the given center point, relative to the total number of occurrences in the samples.

Parameters:

config - the metric configuration

now - the current time in milliseconds

centerValue - the value corresponding to the center point of the bucket

Returns:

the frequency of the values in the bucket relative to the total number of samples

combine

public double combine(List<SampledStat.Sample> samples,
                      MetricConfig config,
                      long now)

Specified by:

combine in class SampledStat

newSample

protected org.apache.kafka.common.metrics.stats.Frequencies.HistogramSample newSample(long timeMs)

Overrides:

newSample in class SampledStat

update

protected void update(SampledStat.Sample sample,
                      MetricConfig config,
                      double value,
                      long timeMs)

Specified by:

update in class SampledStat