001package org.avaje.metric;
002
003/**
004 * A group of TimedMetric that share a common base name.
005 * <p>
006 * This is intended to be used when the full metric name is determined at runtime.
007 */
008public interface TimedMetricGroup {
009
010  /**
011   * Start the event for the given name.
012   * <p>
013   * The group and type parts of the metric name are common and the metrics only differ by this
014   * name.
015   * <p>
016   * Typically the underlying implementation uses a cache to lookup the TimedMetric and create it if
017   * necessary.
018   * 
019   * @param name
020   *          the specific name for the metric (group and type name parts are common).
021   * 
022   * @return the TimedMetricEvent that has started.
023   */
024  TimedEvent start(String name);
025
026  /**
027   * Return the TimedMetric for the specific name.
028   */
029  TimedMetric getTimedMetric(String name);
030
031  /**
032   * Add an event based on a startNanos (determined by {@link System#nanoTime()}).
033   * <p>
034   * Success and failure statistics are kept separately.
035   * <p>
036   * This is an alternative to using {@link #start(String)}. Note that using startEvent() has
037   * slightly higher overhead as it instantiates a TimedEvent object which must be later GC'ed. In
038   * this sense generally addEventSince() is the preferred method to use.
039   */
040  void addEventSince(String name, boolean success, long startNanos);
041
042  /**
043   * Add an event duration in nanoseconds noting if it was a success or failure result.
044   * <p>
045   * Success and failure statistics are kept separately.
046   * <p>
047   * This is an alternative to using {@link #addEventSince(String, boolean, long)} where you pass in the
048   * duration rather than the start nanoseconds.
049   */
050  void addEventDuration(String name, boolean success, long durationNanos);
051}