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.ResourceSample  
    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.ResourceSample resource​(MeterRegistry registry, java.lang.String name)  
    static Timer.Sample start()
    Start a timing sample using the System clock.
    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 Details

    • start

      static Timer.Sample start()
      Start a timing sample using the System clock.
      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 whose clock is 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)

    • resource

      @Incubating(since="1.6.0") static Timer.ResourceSample resource​(MeterRegistry registry, java.lang.String name)
      Parameters:
      registry - A meter registry against which the timer will be registered.
      name - The name of the timer.
      Returns:
      A timing builder that automatically records a timing on close.
      Since:
      1.6.0

    • 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