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.
  • 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(String name)
    • resource

      @Incubating(since="1.6.0") static Timer.ResourceSample resource(MeterRegistry registry, 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, 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, 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(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

      @Nullable <T> T record(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.
    • record

      default boolean record(BooleanSupplier f)
      Executes the Supplier f and records the time taken.
      Parameters:
      f - Function to execute and measure the execution time.
      Returns:
      The return value of f.
      Since:
      1.10.0
    • record

      default int record(IntSupplier f)
      Executes the Supplier f and records the time taken.
      Parameters:
      f - Function to execute and measure the execution time.
      Returns:
      The return value of f.
      Since:
      1.10.0
    • record

      default long record(LongSupplier f)
      Executes the Supplier f and records the time taken.
      Parameters:
      f - Function to execute and measure the execution time.
      Returns:
      The return value of f.
      Since:
      1.10.0
    • record

      default double record(DoubleSupplier f)
      Executes the Supplier f and records the time taken.
      Parameters:
      f - Function to execute and measure the execution time.
      Returns:
      The return value of f.
      Since:
      1.10.0
    • recordCallable

      @Nullable <T> T recordCallable(Callable<T> f) throws 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:
      Exception - Any exception bubbling up from the callable.
    • record

      void record(Runnable f)
      Executes the runnable f and records the time taken.
      Parameters:
      f - Function to execute and measure the execution time.
    • wrap

      default Runnable wrap(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> Callable<T> wrap(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> Supplier<T> wrap(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(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(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(TimeUnit unit)
      Parameters:
      unit - The base unit of time to scale the max to.
      Returns:
      The maximum time of a single event.
    • measure

      default 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, 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

      TimeUnit baseTimeUnit()
      Returns:
      The base time unit of the timer to which all published metrics will be scaled