com.netflix.spectator.api.histogram

Class PercentileDistributionSummary

java.lang.Object

com.netflix.spectator.api.histogram.PercentileDistributionSummary

All Implemented Interfaces:

DistributionSummary, Meter

public final class PercentileDistributionSummary
extends Object
implements DistributionSummary

Distribution summary that buckets the counts to allow for estimating percentiles. This distribution summary type will track the data distribution for the summary by maintaining a set of counters. The distribution can then be used on the server side to estimate percentiles while still allowing for arbitrary slicing and dicing based on dimensions.

Percentile distribution summaries are expensive compared to basic distribution summaries from the registry. In particular they have a higher storage cost, worst case ~300x, to maintain the data distribution. Be diligent about any additional dimensions added to percentile distribution summaries and ensure they have a small bounded cardinality. In addition it is highly recommended to set a threshold (see PercentileDistributionSummary.Builder.withRange(long, long)) whenever possible to greatly restrict the worst case overhead.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PercentileDistributionSummary.Builder Helper for getting instances of a PercentileDistributionSummary.

Nested classes/interfaces inherited from interface com.netflix.spectator.api.DistributionSummary

DistributionSummary.BatchUpdater

Method Summary

Modifier and Type	Method and Description
static IdBuilder<PercentileDistributionSummary.Builder>	builder(Registry registry) Return a builder for configuring and retrieving and instance of a percentile distribution summary.
long	count() The number of times that record has been called since this timer was last reset.
static PercentileDistributionSummary	get(Registry registry, Id id) Creates a distribution summary object that can be used for estimating percentiles.
boolean	hasExpired() Indicates whether the meter is expired.
Id	id() Identifier used to lookup this meter in the registry.
Iterable<Measurement>	measure() Get the set of measurements for this meter.
double	percentile(double p) Computes the specified percentile for this distribution summary.
void	record(long amount) Updates the statistics kept by the summary with the specified amount.
void	record(long[] amounts, int n) Updates the statistics kept by the summary with the specified amounts as a batch.
long	totalAmount() The total amount of all recorded events since this summary was last reset.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.netflix.spectator.api.DistributionSummary

batchUpdater

Method Detail

get

public static PercentileDistributionSummary get(Registry registry,
                                                Id id)

Creates a distribution summary object that can be used for estimating percentiles. Percentile distribution summaries are expensive compared to basic distribution summaries from the registry. Be diligent with ensuring that any additional dimensions have a small bounded cardinality. It is also highly recommended to explicitly set the threshold (see PercentileDistributionSummary.Builder.withRange(long, long)) whenever possible.

Parameters:

registry - Registry to use.

id - Identifier for the metric being registered.

Returns:

Distribution summary that keeps track of counts by buckets that can be used to estimate the percentiles for the distribution.

builder

public static IdBuilder<PercentileDistributionSummary.Builder> builder(Registry registry)

Return a builder for configuring and retrieving and instance of a percentile distribution summary. If the distribution summary has dynamic dimensions, then the builder can be used with the new dimensions. If the id is the same as an existing distribution summary, then it will update the same underlying distribution summaries in the registry.

id

public Id id()

Description copied from interface: Meter

Identifier used to lookup this meter in the registry.

Specified by:

id in interface Meter

measure

public Iterable<Measurement> measure()

Description copied from interface: Meter

Get the set of measurements for this meter.

Specified by:

measure in interface Meter

hasExpired

public boolean hasExpired()

Description copied from interface: Meter

Indicates whether the meter is expired. For example, a counter might expire if there is no activity within a given time frame.

Specified by:

hasExpired in interface Meter

record

public void record(long amount)

Description copied from interface: DistributionSummary

Updates the statistics kept by the summary with the specified amount.

Specified by:

record in interface DistributionSummary

Parameters:

amount - Amount for an event being measured. For example, if the size in bytes of responses from a server. If the amount is less than 0 the value will be dropped.

record

public void record(long[] amounts,
                   int n)

Description copied from interface: DistributionSummary

Updates the statistics kept by the summary with the specified amounts as a batch. Behaves as if `record()` was called in a loop, but may be faster in some cases.

Specified by:

record in interface DistributionSummary

Parameters:

amounts - Amounts for an event being measured. For example, if the size in bytes of responses from a server. If the amount is less than 0 the value will be dropped.

n - The number of elements to write from the amounts array (starting from 0). If n is <= 0 no entries will be recorded. If n is greater than amounts.length, all amounts will be recorded.

See Also:

DistributionSummary.record(long)

percentile

public double percentile(double p)

Computes the specified percentile for this distribution summary.

Parameters:

p - Percentile to compute, value must be 0.0 <= p <= 100.0.

Returns:

An approximation of the p`th percentile in seconds.

count

public long count()

Description copied from interface: DistributionSummary

The number of times that record has been called since this timer was last reset. How often a timer is reset depends on the underlying registry implementation.

Specified by:

count in interface DistributionSummary

totalAmount

public long totalAmount()

Description copied from interface: DistributionSummary

The total amount of all recorded events since this summary was last reset. How often a timer is reset depends on the underlying registry implementation.

Specified by:

totalAmount in interface DistributionSummary