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

    • 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