Package io.micrometer.core.instrument

Interface Timer

All Superinterfaces:

HistogramSupport, Meter

All Known Implementing Classes:

AbstractTimer, CumulativeTimer, DropwizardTimer, NoopTimer, StepTimer

public interface Timer
extends Meter, HistogramSupport

Timer intended to track of a large number of short running events. Example would be something like an HTTP request. Though "short running" is a bit subjective the assumption is that it should be under a minute.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Timer.Builder	Fluent builder for timers.
static class	Timer.Sample	Maintains state on the clock's start position for a latency sample.

Nested classes/interfaces inherited from interface io.micrometer.core.instrument.Meter

Meter.Id, Meter.Type

Method Summary

Modifier and Type	Method	Description
java.util.concurrent.TimeUnit	baseTimeUnit()
static Timer.Builder	builder(Timed timed, java.lang.String defaultName)	Create a timer builder from a Timed annotation.
static Timer.Builder	builder(java.lang.String name)
long	count()
default double	histogramCountAtValue(long valueNanos)	Deprecated. Use HistogramSupport.takeSnapshot() to retrieve bucket counts.
double	max(java.util.concurrent.TimeUnit unit)
default double	mean(java.util.concurrent.TimeUnit unit)
default java.lang.Iterable<Measurement>	measure()	Get a set of measurements.
default double	percentile(double percentile, java.util.concurrent.TimeUnit unit)	Deprecated. Use HistogramSupport.takeSnapshot() to retrieve bucket counts.
void	record(long amount, java.util.concurrent.TimeUnit unit)	Updates the statistics kept by the timer with the specified amount.
void	record(java.lang.Runnable f)	Executes the runnable f and records the time taken.
default void	record(java.time.Duration duration)	Updates the statistics kept by the timer with the specified amount.
<T> T	record(java.util.function.Supplier<T> f)	Executes the Supplier f and records the time taken.
<T> T	recordCallable(java.util.concurrent.Callable<T> f)	Executes the callable f and records the time taken.
static Timer.Sample	start()	Start a timing sample.
static Timer.Sample	start(Clock clock)	Start a timing sample.
static Timer.Sample	start(MeterRegistry registry)	Start a timing sample.
double	totalTime(java.util.concurrent.TimeUnit unit)
default java.lang.Runnable	wrap(java.lang.Runnable f)	Wrap a Runnable so that it is timed when invoked.
default <T> java.util.concurrent.Callable<T>	wrap(java.util.concurrent.Callable<T> f)	Wrap a Callable so that it is timed when invoked.
default <T> java.util.function.Supplier<T>	wrap(java.util.function.Supplier<T> f)	Wrap a Supplier so that it is timed when invoked.

Methods inherited from interface io.micrometer.core.instrument.distribution.HistogramSupport

takeSnapshot, takeSnapshot

Methods inherited from interface io.micrometer.core.instrument.Meter

close, getId, match, use

Method Detail

start

static Timer.Sample start()

Start a timing sample.

Returns:

A timing sample with start time recorded.

Since:

1.1.0

start

static Timer.Sample start(MeterRegistry registry)

Start a timing sample.

Parameters:

registry - a meter registry to be used

Returns:

A timing sample with start time recorded.

start

static Timer.Sample start(Clock clock)

Start a timing sample.

Parameters:

clock - a clock to be used

Returns:

A timing sample with start time recorded.

builder

static Timer.Builder builder(java.lang.String name)

builder

static Timer.Builder builder(Timed timed,
                             java.lang.String defaultName)

Create a timer builder from a Timed annotation.

Parameters:

timed - The annotation instance to base a new timer on.

defaultName - A default name to use in the event that the value attribute is empty.

Returns:

This builder.

record

void record(long amount,
            java.util.concurrent.TimeUnit unit)

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

Parameters:

amount - Duration of a single event being measured by this timer. If the amount is less than 0 the value will be dropped.

unit - Time unit for the amount being recorded.

record

default void record(java.time.Duration duration)

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

Parameters:

duration - Duration of a single event being measured by this timer.

record

<T> T record(java.util.function.Supplier<T> f)

Executes the Supplier f and records the time taken.

Type Parameters:

T - The return type of the Supplier.

Parameters:

f - Function to execute and measure the execution time.

Returns:

The return value of f.

recordCallable

<T> T recordCallable(java.util.concurrent.Callable<T> f)
              throws java.lang.Exception

Executes the callable f and records the time taken.

Type Parameters:

T - The return type of the Callable.

Parameters:

f - Function to execute and measure the execution time.

Returns:

The return value of f.

Throws:

java.lang.Exception - Any exception bubbling up from the callable.

record

void record(java.lang.Runnable f)

Executes the runnable f and records the time taken.

Parameters:

f - Function to execute and measure the execution time.

wrap

default java.lang.Runnable wrap(java.lang.Runnable f)

Wrap a Runnable so that it is timed when invoked.

Parameters:

f - The Runnable to time when it is invoked.

Returns:

The wrapped Runnable.

wrap

default <T> java.util.concurrent.Callable<T> wrap(java.util.concurrent.Callable<T> f)

Wrap a Callable so that it is timed when invoked.

Type Parameters:

T - The return type of the callable.

Parameters:

f - The Callable to time when it is invoked.

Returns:

The wrapped callable.

wrap

default <T> java.util.function.Supplier<T> wrap(java.util.function.Supplier<T> f)

Wrap a Supplier so that it is timed when invoked.

Type Parameters:

T - The return type of the Supplier result.

Parameters:

f - The Supplier to time when it is invoked.

Returns:

The wrapped supplier.

Since:

1.2.0

count

long count()

Returns:

The number of times that stop has been called on this timer.

totalTime

double totalTime(java.util.concurrent.TimeUnit unit)

Parameters:

unit - The base unit of time to scale the total to.

Returns:

The total time of recorded events.

mean

default double mean(java.util.concurrent.TimeUnit unit)

Parameters:

unit - The base unit of time to scale the mean to.

Returns:

The distribution average for all recorded events.

max

double max(java.util.concurrent.TimeUnit unit)

Parameters:

unit - The base unit of time to scale the max to.

Returns:

The maximum time of a single event.

measure

default java.lang.Iterable<Measurement> measure()

Description copied from interface: Meter

Get a set of measurements. Should always return the same number of measurements and in the same order, regardless of the level of activity or the lack thereof.

Specified by:

measure in interface Meter

Returns:

The set of measurements that represents the instantaneous value of this meter.

histogramCountAtValue

@Deprecated
default double histogramCountAtValue(long valueNanos)

Deprecated.

Use HistogramSupport.takeSnapshot() to retrieve bucket counts.

Provides cumulative histogram counts.

Parameters:

valueNanos - The histogram bucket to retrieve a count for.

Returns:

The count of all events less than or equal to the bucket. If valueNanos does not match a preconfigured bucket boundary, returns NaN.

percentile

@Deprecated
default double percentile(double percentile,
                          java.util.concurrent.TimeUnit unit)

Deprecated.

Use HistogramSupport.takeSnapshot() to retrieve bucket counts.

Parameters:

percentile - A percentile in the domain [0, 1]. For example, 0.5 represents the 50th percentile of the distribution.

unit - The base unit of time to scale the percentile value to.

Returns:

The latency at a specific percentile. This value is non-aggregable across dimensions. Returns NaN if percentile is not a preconfigured percentile that Micrometer is tracking.

baseTimeUnit

java.util.concurrent.TimeUnit baseTimeUnit()

Returns:

The base time unit of the timer to which all published metrics will be scaled