io.micrometer.core.instrument

Class DistributionSummary.Builder

java.lang.Object

io.micrometer.core.instrument.DistributionSummary.Builder

Enclosing interface:

DistributionSummary

public static class DistributionSummary.Builder
extends java.lang.Object

Fluent builder for distribution summaries.

Method Summary

Modifier and Type	Method and Description
DistributionSummary.Builder	baseUnit(java.lang.String unit)
DistributionSummary.Builder	description(java.lang.String description)
DistributionSummary.Builder	distributionStatisticBufferLength(java.lang.Integer bufferLength) Statistics emanating from a distribution summary like max, percentiles, and histogram counts decay over time to give greater weight to recent samples (exception: histogram counts are cumulative for those systems that expect cumulative histogram buckets).
DistributionSummary.Builder	distributionStatisticExpiry(java.time.Duration expiry) Statistics emanating from a distribution summary like max, percentiles, and histogram counts decay over time to give greater weight to recent samples (exception: histogram counts are cumulative for those systems that expect cumulative histogram buckets).
DistributionSummary.Builder	maximumExpectedValue(java.lang.Long max) Sets the maximum value that this distribution summary is expected to observe.
DistributionSummary.Builder	minimumExpectedValue(java.lang.Long min) Sets the minimum value that this distribution summary is expected to observe.
DistributionSummary.Builder	percentilePrecision(java.lang.Integer digitsOfPrecision) Determines the number of digits of precision to maintain on the dynamic range histogram used to compute percentile approximations.
DistributionSummary.Builder	publishPercentileHistogram() Adds histogram buckets used to generate aggregable percentile approximations in monitoring systems that have query facilities to do so (e.g.
DistributionSummary.Builder	publishPercentileHistogram(java.lang.Boolean enabled) Adds histogram buckets used to generate aggregable percentile approximations in monitoring systems that have query facilities to do so (e.g.
DistributionSummary.Builder	publishPercentiles(double... percentiles) Produces an additional time series for each requested percentile.
DistributionSummary	register(MeterRegistry registry) Add the distribution summary to a single registry, or return an existing distribution summary in that registry.
DistributionSummary.Builder	scale(double scale) Multiply values recorded to the distribution summary by a scaling factor.
DistributionSummary.Builder	sla(long... sla) Publish at a minimum a histogram containing your defined SLA boundaries.
DistributionSummary.Builder	tag(java.lang.String key, java.lang.String value)
DistributionSummary.Builder	tags(java.lang.Iterable<Tag> tags)
DistributionSummary.Builder	tags(java.lang.String... tags)

Methods inherited from class java.lang.Object

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

Method Detail

tags

public DistributionSummary.Builder tags(java.lang.String... tags)

Parameters:

tags - Must be an even number of arguments representing key/value pairs of tags.

Returns:

The distribution summmary builder with added tags.

tags

public DistributionSummary.Builder tags(java.lang.Iterable<Tag> tags)

Parameters:

tags - Tags to add to the eventual distribution summary.

Returns:

The distribution summary builder with added tags.

tag

public DistributionSummary.Builder tag(java.lang.String key,
                                       java.lang.String value)

Parameters:

key - The tag key.

value - The tag value.

Returns:

The distribution summary builder with a single added tag.

description

public DistributionSummary.Builder description(@Nullable
                                               java.lang.String description)

Parameters:

description - Description text of the eventual distribution summary.

Returns:

The distribution summary builder with added description.

baseUnit

public DistributionSummary.Builder baseUnit(@Nullable
                                            java.lang.String unit)

Parameters:

unit - Base unit of the eventual distribution summary.

Returns:

The distribution summary builder with added base unit.

publishPercentiles

public DistributionSummary.Builder publishPercentiles(@Nullable
                                                      double... percentiles)

Produces an additional time series for each requested percentile. This percentile is computed locally, and so can't be aggregated with percentiles computed across other dimensions (e.g. in a different instance). Use publishPercentileHistogram() to publish a histogram that can be used to generate aggregable percentile approximations.

Parameters:

percentiles - Percentiles to compute and publish. The 95th percentile should be expressed as 0.95.

Returns:

This builder.

percentilePrecision

public DistributionSummary.Builder percentilePrecision(@Nullable
                                                       java.lang.Integer digitsOfPrecision)

Determines the number of digits of precision to maintain on the dynamic range histogram used to compute percentile approximations. The higher the degrees of precision, the more accurate the approximation is at the cost of more memory.

Parameters:

digitsOfPrecision - The digits of precision to maintain for percentile approximations.

Returns:

This builder.

publishPercentileHistogram

public DistributionSummary.Builder publishPercentileHistogram()

Adds histogram buckets used to generate aggregable percentile approximations in monitoring systems that have query facilities to do so (e.g. Prometheus' histogram_quantile, Atlas' :percentiles).

Returns:

This builder.

publishPercentileHistogram

public DistributionSummary.Builder publishPercentileHistogram(@Nullable
                                                              java.lang.Boolean enabled)

Adds histogram buckets used to generate aggregable percentile approximations in monitoring systems that have query facilities to do so (e.g. Prometheus' histogram_quantile, Atlas' :percentiles).

Parameters:

enabled - Determines whether percentile histograms should be published.

Returns:

This builder.

sla

public DistributionSummary.Builder sla(@Nullable
                                       long... sla)

Publish at a minimum a histogram containing your defined SLA boundaries. When used in conjunction with publishPercentileHistogram(), the boundaries defined here are included alongside other buckets used to generate aggregable percentile approximations.

Parameters:

sla - Publish SLA boundaries in the set of histogram buckets shipped to the monitoring system.

Returns:

This builder.

minimumExpectedValue

public DistributionSummary.Builder minimumExpectedValue(@Nullable
                                                        java.lang.Long min)

Sets the minimum value that this distribution summary is expected to observe. Sets a lower bound on histogram buckets that are shipped to monitoring systems that support aggregable percentile approximations.

Parameters:

min - The minimum value that this distribution summary is expected to observe.

Returns:

This builder.

maximumExpectedValue

public DistributionSummary.Builder maximumExpectedValue(@Nullable
                                                        java.lang.Long max)

Sets the maximum value that this distribution summary is expected to observe. Sets an upper bound on histogram buckets that are shipped to monitoring systems that support aggregable percentile approximations.

Parameters:

max - The maximum value that this distribution summary is expected to observe.

Returns:

This builder.

distributionStatisticExpiry

public DistributionSummary.Builder distributionStatisticExpiry(@Nullable
                                                               java.time.Duration expiry)

Statistics emanating from a distribution summary like max, percentiles, and histogram counts decay over time to give greater weight to recent samples (exception: histogram counts are cumulative for those systems that expect cumulative histogram buckets). Samples are accumulated to such statistics in ring buffers which rotate after this expiry, with a buffer length of distributionStatisticBufferLength(Integer).

Parameters:

expiry - The amount of time samples are accumulated to a histogram before it is reset and rotated.

Returns:

This builder.

distributionStatisticBufferLength

public DistributionSummary.Builder distributionStatisticBufferLength(@Nullable
                                                                     java.lang.Integer bufferLength)

Statistics emanating from a distribution summary like max, percentiles, and histogram counts decay over time to give greater weight to recent samples (exception: histogram counts are cumulative for those systems that expect cumulative histogram buckets). Samples are accumulated to such statistics in ring buffers which rotate after distributionStatisticExpiry(Duration), with this buffer length.

Parameters:

bufferLength - The number of histograms to keep in the ring buffer.

Returns:

This builder.

scale

public DistributionSummary.Builder scale(double scale)

Multiply values recorded to the distribution summary by a scaling factor.

Parameters:

scale - Factor to scale each recorded value by.

Returns:

This builder.

register

public DistributionSummary register(MeterRegistry registry)

Add the distribution summary to a single registry, or return an existing distribution summary in that registry. The returned distribution summary will be unique for each registry, but each registry is guaranteed to only create one distribution summary for the same combination of name and tags.

Parameters:

registry - A registry to add the distribution summary to, if it doesn't already exist.

Returns:

A new or existing distribution summary.