Interface Timer

All Superinterfaces:
HistogramSupport, Meter, Wrapper, Wrapper
public interface Timer extends Meter, HistogramSupport
Accumulates timing information about large numbers of short-running events (e.g., HTTP requests), each with a Duration value, and reports statistics over all samples (count, total time, mean, max) as well as grouping samples using percentiles or bucket boundaries.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Timer.Builder
    Builder for a new Timer.
    static interface 
    Timer.Sample
    Measures an interval of time from instantiation to an explicit invocation of Timer.Sample.stop(io.helidon.metrics.api.Timer).

    Nested classes/interfaces inherited from interface Meter

    Meter.BaseUnits, Meter.Id, Meter.Scope, Meter.Type
    Modifier and Type
    Interface
    Description
    static class 
    Meter.BaseUnits
    Common unit declarations (inspired by the list from MicroProfile metrics).
    static interface 
    Meter.Id
    Unique idenfier for a meter.
    static class 
    Meter.Scope
    Deprecated, for removal: This API element is subject to removal in a future version.
    Core metrics ignores scope values, and this type will be removed.
    static enum 
    Meter.Type
    Type of meter.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Timer.Builder
    builder(String name)
    Deprecated, for removal: This API element is subject to removal in a future version.
    this method gets MetricsFactory from ServiceRegistry, which may be inefficient.
    long
    count()
    Returns the current count of completed events measured by the timer.
    double
    max(TimeUnit unit)
    Returns the maximum value, expressed in the specified units, consumed by a completed event measured by the timer.
    double
    mean(TimeUnit unit)
    Returns the average time, expressed in the specified units, consumed by completed events measured by the timer.
    void
    record(long amount, TimeUnit unit)
    Updates the statistics kept by the timer with the specified amount.
    void
    record(Runnable f)
    Executes the Runnable f and records the time it takes.
    void
    record(Duration duration)
    Updates the statistics kept by the timer with the specified amount.
    <T> T
    record(Callable<T> f)
    Executes the Callable f and records the time spent it, returning the callable's result.
    <T> T
    record(Supplier<T> f)
    Executes the Supplier f and records the time spent invoking the function.
    static Timer.Sample
    start()
    Deprecated, for removal: This API element is subject to removal in a future version.
    this method gets MetricsFactory from ServiceRegistry, which may be inefficient.
    static Timer.Sample
    start(Clock clock)
    Deprecated, for removal: This API element is subject to removal in a future version.
    this method gets MetricsFactory from ServiceRegistry, which may be inefficient.
    static Timer.Sample
    start(MeterRegistry registry)
    Deprecated, for removal: This API element is subject to removal in a future version.
    call MetricsFactory.timerStart(MeterRegistry) on the registry's owning factory instead
    double
    totalTime(TimeUnit unit)
    Returns the total time, expressed in the specified units, consumed by completed events measured by the timer.
    Runnable
    wrap(Runnable f)
    Wraps a Runnable so that it will be timed every time it is invoked via the return value from this method.
    <T> Callable<T>
    wrap(Callable<T> f)
    Wraps a Callable so that it is will be timed every time it is invoked via the return value from this method.
    <T> Supplier<T>
    wrap(Supplier<T> f)
    Wraps a Supplier so that it will be timed every time it is invoked via the return value from this method.

    Methods inherited from interface HistogramSupport

    snapshot
    Modifier and Type
    Method
    Description
    HistogramSnapshot
    snapshot()
    Returns a snapshot of the data in a histogram.

    Methods inherited from interface Meter

    baseUnit, description, id, scope, type
    Modifier and Type
    Method
    Description
    Optional<String>
    baseUnit()
    Returns the meter's base unit.
    Optional<String>
    description()
    Returns the meter's description.
    Meter.Id
    id()
    Returns the meter ID.
    default Optional<String>
    scope()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Core metrics does not assign scopes, and this method will be removed.
    Meter.Type
    type()
    Returns the meter type.

    Methods inherited from interface Wrapper

    unwrap
    Modifier and Type
    Method
    Description
    <T> T
    unwrap(Class<? extends T> type)
    Unwraps the delegate as the specified type.

  • Method Details

    • builder

      @Deprecated(forRemoval=true, since="27.0.0") static Timer.Builder builder(String name)
      Deprecated, for removal: This API element is subject to removal in a future version.
      this method gets MetricsFactory from ServiceRegistry, which may be inefficient. Call MetricsFactory.timerBuilder(String) instead
      Creates a builder for a new Timer.
      Parameters:
      name - timer name
      Returns:
      new builder

    • start

      @Deprecated(forRemoval=true, since="27.0.0") static Timer.Sample start()
      Deprecated, for removal: This API element is subject to removal in a future version.
      this method gets MetricsFactory from ServiceRegistry, which may be inefficient. call MetricsFactory.timerStart() instead
      Starts a timing sample using the default system clock.
      Returns:
      new sample

    • start

      @Deprecated(forRemoval=true, since="27.0.0") static Timer.Sample start(MeterRegistry registry)
      Deprecated, for removal: This API element is subject to removal in a future version.
      call MetricsFactory.timerStart(MeterRegistry) on the registry's owning factory instead
      Starts a timing sample using the clock associated with the specified MeterRegistry.
      Parameters:
      registry - the meter registry whose clock is to be used for measuring the interval
      Returns:
      new sample with start time recorded

    • start

      @Deprecated(forRemoval=true, since="27.0.0") static Timer.Sample start(Clock clock)
      Deprecated, for removal: This API element is subject to removal in a future version.
      this method gets MetricsFactory from ServiceRegistry, which may be inefficient. call MetricsFactory.timerStart(Clock) instead
      Starts a timing sample using the specified clock.
      Parameters:
      clock - a clock to be used
      Returns:
      new sample with start time recorded

    • 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

      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

      <T> T record(Supplier<T> f)
      Executes the Supplier f and records the time spent invoking the function.
      Type Parameters:
      T - return type of the Supplier
      Parameters:
      f - function to be timed
      Returns:
      return value from invoking the function f

    • record

      <T> T record(Callable<T> f) throws Exception
      Executes the Callable f and records the time spent it, returning the callable's result.
      Type Parameters:
      T - return type of the Callable
      Parameters:
      f - callable to be timed
      Returns:
      return value from invoking the callable f
      Throws:
      Exception - exception escaping from the callable

    • record

      void record(Runnable f)
      Executes the Runnable f and records the time it takes.
      Parameters:
      f - runnable to be timed

    • wrap

      Runnable wrap(Runnable f)
      Wraps a Runnable so that it will be timed every time it is invoked via the return value from this method.
      Parameters:
      f - runnable to time when it is invoked
      Returns:
      the wrapped runnable

    • wrap

      <T> Callable<T> wrap(Callable<T> f)
      Wraps a Callable so that it is will be timed every time it is invoked via the return value from this method.
      Type Parameters:
      T - return type of the callable
      Parameters:
      f - callable to time when it is invoked
      Returns:
      the wrapped callable

    • wrap

      <T> Supplier<T> wrap(Supplier<T> f)
      Wraps a Supplier so that it will be timed every time it is invoked via the return value from this method.
      Type Parameters:
      T - return type of the Supplier result
      Parameters:
      f - Supplier to time when it is invoked
      Returns:
      the wrapped supplier

    • count

      long count()
      Returns the current count of completed events measured by the timer.
      Returns:
      number of events recorded by the timer

    • totalTime

      double totalTime(TimeUnit unit)
      Returns the total time, expressed in the specified units, consumed by completed events measured by the timer.
      Parameters:
      unit - time unit in which to express the total accumulated time
      Returns:
      total time of recorded events

    • mean

      double mean(TimeUnit unit)
      Returns the average time, expressed in the specified units, consumed by completed events measured by the timer.
      Parameters:
      unit - time unit in which to express the mean
      Returns:
      average for all events recorded by this timer

    • max

      double max(TimeUnit unit)
      Returns the maximum value, expressed in the specified units, consumed by a completed event measured by the timer.
      Parameters:
      unit - time unit in which to express the maximum
      Returns:
      maximum time recorded by a single event measured by this timer