Package io.micrometer.core.instrument

Class Timer.Builder

java.lang.Object

io.micrometer.core.instrument.AbstractTimerBuilder<Timer.Builder>

io.micrometer.core.instrument.Timer.Builder

Enclosing interface:

Timer

public static class Timer.Builder
extends AbstractTimerBuilder<Timer.Builder>

Fluent builder for timers.

Field Summary

Fields inherited from class io.micrometer.core.instrument.AbstractTimerBuilder

description, distributionConfigBuilder, name, pauseDetector, tags

Method Summary

Modifier and Type	Method	Description
Timer.Builder	description(@Nullable String description)
Timer.Builder	distributionStatisticBufferLength(@Nullable Integer bufferLength)	Statistics emanating from a timer 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).
Timer.Builder	distributionStatisticExpiry(@Nullable Duration expiry)	Statistics emanating from a timer 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).
Timer.Builder	maximumExpectedValue(@Nullable Duration max)	Sets the maximum value that this timer is expected to observe.
Timer.Builder	minimumExpectedValue(@Nullable Duration min)	Sets the minimum value that this timer is expected to observe.
Timer.Builder	pauseDetector(@Nullable PauseDetector pauseDetector)	Sets the pause detector implementation to use for this timer.
Timer.Builder	percentilePrecision(@Nullable Integer digitsOfPrecision)	Determines the number of digits of precision to maintain on the dynamic range histogram used to compute percentile approximations.
Timer.Builder	publishPercentileHistogram()	Adds histogram buckets used to generate aggregable percentile approximations in monitoring systems that have query facilities to do so (e.g.
Timer.Builder	publishPercentileHistogram(@Nullable Boolean enabled)	Adds histogram buckets used to generate aggregable percentile approximations in monitoring systems that have query facilities to do so (e.g.
Timer.Builder	publishPercentiles(double @Nullable ... percentiles)	Produces an additional time series for each requested percentile.
Timer	register(MeterRegistry registry)	Add the timer to a single registry, or return an existing timer in that registry.
Timer.Builder	serviceLevelObjectives(Duration @Nullable ... slos)	Publish at a minimum a histogram containing your defined service level objective (SLO) boundaries.
Timer.Builder	sla(Duration @Nullable ... sla)	Publish at a minimum a histogram containing your defined service level objective (SLO) boundaries.
Timer.Builder	tag(String key, String value)
Timer.Builder	tags(Iterable<Tag> tags)
Timer.Builder	tags(String... tags)
Meter.MeterProvider<Timer>	withRegistry(MeterRegistry registry)	Convenience method to create meters from the builder that only differ in tags.

Methods inherited from class java.lang.Object

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

Method Details

tags

public Timer.Builder tags(String... tags)

Overrides:

tags in class AbstractTimerBuilder<Timer.Builder>

Parameters:

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

Returns:

This builder.

tags

public Timer.Builder tags(Iterable<Tag> tags)

Overrides:

tags in class AbstractTimerBuilder<Timer.Builder>

Parameters:

tags - Tags to add to the eventual timer.

Returns:

The timer builder with added tags.

tag

public Timer.Builder tag(String key,
 String value)

Overrides:

tag in class AbstractTimerBuilder<Timer.Builder>

Parameters:

key - The tag key.

value - The tag value.

Returns:

The timer builder with a single added tag.

publishPercentiles

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

Description copied from class: AbstractTimerBuilder

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 AbstractTimerBuilder.publishPercentileHistogram() to publish a histogram that can be used to generate aggregable percentile approximations.

Overrides:

publishPercentiles in class AbstractTimerBuilder<Timer.Builder>

Parameters:

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

Returns:

This builder.

percentilePrecision

public Timer.Builder percentilePrecision(@Nullable Integer digitsOfPrecision)

Description copied from class: AbstractTimerBuilder

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.

Overrides:

percentilePrecision in class AbstractTimerBuilder<Timer.Builder>

Parameters:

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

Returns:

This builder.

publishPercentileHistogram

public Timer.Builder publishPercentileHistogram()

Description copied from class: AbstractTimerBuilder

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).

Overrides:

publishPercentileHistogram in class AbstractTimerBuilder<Timer.Builder>

Returns:

This builder.

publishPercentileHistogram

public Timer.Builder publishPercentileHistogram(@Nullable Boolean enabled)

Description copied from class: AbstractTimerBuilder

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).

Overrides:

publishPercentileHistogram in class AbstractTimerBuilder<Timer.Builder>

Parameters:

enabled - Determines whether percentile histograms should be published.

Returns:

This builder.

sla

public Timer.Builder sla(Duration @Nullable ... sla)

Description copied from class: AbstractTimerBuilder

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

Overrides:

sla in class AbstractTimerBuilder<Timer.Builder>

Parameters:

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

Returns:

This builder.

serviceLevelObjectives

public Timer.Builder serviceLevelObjectives(Duration @Nullable ... slos)

Description copied from class: AbstractTimerBuilder

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

Overrides:

serviceLevelObjectives in class AbstractTimerBuilder<Timer.Builder>

Parameters:

slos - Publish SLO boundaries in the set of histogram buckets shipped to the monitoring system.

Returns:

This builder.

minimumExpectedValue

public Timer.Builder minimumExpectedValue(@Nullable Duration min)

Description copied from class: AbstractTimerBuilder

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

Overrides:

minimumExpectedValue in class AbstractTimerBuilder<Timer.Builder>

Parameters:

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

Returns:

This builder.

maximumExpectedValue

public Timer.Builder maximumExpectedValue(@Nullable Duration max)

Description copied from class: AbstractTimerBuilder

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

Overrides:

maximumExpectedValue in class AbstractTimerBuilder<Timer.Builder>

Parameters:

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

Returns:

This builder.

distributionStatisticExpiry

public Timer.Builder distributionStatisticExpiry(@Nullable Duration expiry)

Description copied from class: AbstractTimerBuilder

Statistics emanating from a timer 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 AbstractTimerBuilder.distributionStatisticBufferLength(Integer), hence complete expiry happens after this expiry * buffer length.

Overrides:

distributionStatisticExpiry in class AbstractTimerBuilder<Timer.Builder>

Parameters:

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

Returns:

This builder.

distributionStatisticBufferLength

public Timer.Builder distributionStatisticBufferLength(@Nullable Integer bufferLength)

Description copied from class: AbstractTimerBuilder

Statistics emanating from a timer 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 AbstractTimerBuilder.distributionStatisticExpiry(Duration), with this buffer length.

Overrides:

distributionStatisticBufferLength in class AbstractTimerBuilder<Timer.Builder>

Parameters:

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

Returns:

This builder.

pauseDetector

public Timer.Builder pauseDetector(@Nullable PauseDetector pauseDetector)

Description copied from class: AbstractTimerBuilder

Sets the pause detector implementation to use for this timer. Can also be configured on a registry-level with MeterRegistry.Config.pauseDetector(PauseDetector).

Overrides:

pauseDetector in class AbstractTimerBuilder<Timer.Builder>

Parameters:

pauseDetector - The pause detector implementation to use.

Returns:

This builder.

See Also:

• NoPauseDetector
• ClockDriftPauseDetector

description

public Timer.Builder description(@Nullable String description)

Overrides:

description in class AbstractTimerBuilder<Timer.Builder>

Parameters:

description - Description text of the eventual timer.

Returns:

This builder.

withRegistry

public Meter.MeterProvider<Timer> withRegistry(MeterRegistry registry)

Convenience method to create meters from the builder that only differ in tags. This method can be used for dynamic tagging by creating the builder once and applying the dynamically changing tags using the returned Meter.MeterProvider.

Parameters:

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

Returns:

A Meter.MeterProvider that returns a meter based on the provided tags.

Since:

1.12.0

register

public Timer register(MeterRegistry registry)

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

Parameters:

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

Returns:

A new or existing timer.