001package org.avaje.metric;
002
003import java.util.Map;
004
005/**
006 * A TimedMetric for measuring execution time for methods and events.
007 */
008public interface TimedMetric extends Metric {
009
010  /**
011   * Start an event.
012   * <p>
013   * At the completion of the event one of {@link TimedEvent#endWithSuccess()},
014   * {@link TimedEvent#endWithError()} or {@link TimedEvent#end(boolean)} is called to record the
015   * event duration and success or otherwise.
016   * <p>
017   * This is an alternative to using {@link #addEventSince(boolean, long)} or
018   * {@link #addEventDuration(boolean, long)}. Note that this startEvent() method has slightly
019   * higher overhead as it instantiates a TimedEvent object which must be later GC'ed. In this sense
020   * generally addEventSince() is the preferred method to use.
021   */
022  TimedEvent startEvent();
023
024  /**
025   * Add an event based on a startNanos (determined by {@link System#nanoTime()}).
026   * <p>
027   * Success and failure statistics are kept separately.
028   * <p>
029   * This is an alternative to using {@link #startEvent()}. Note that using startEvent() has
030   * slightly higher overhead as it instantiates a TimedEvent object which must be later GC'ed. In
031   * this sense generally addEventSince() is the preferred method to use.
032   */
033  void addEventSince(boolean success, long startNanos);
034
035  /**
036   * Add an event duration in nanoseconds noting if it was a success or failure result.
037   * <p>
038   * Success and failure statistics are kept separately.
039   * <p>
040   * This is an alternative to using {@link #addEventSince(boolean, long)} where you pass in the
041   * duration rather than the start nanoseconds.
042   */
043  void addEventDuration(boolean success, long durationNanos);
044
045  /**
046   * Return true if this timed metric is part of a bucket range (and hence only hold statistics for the
047   * bucket range returned by <code>bucketRange()</code>.
048   */
049  boolean isBucket();
050
051  /**
052   * Return the bucket range or empty string if not a bucket.
053   */
054  String getBucketRange();
055
056  /**
057   * Add an event duration with opCode indicating success or failure. This is intended for use by
058   * enhanced code and not general use.
059   * <p>
060   * Although this looks redundant and a little ugly having this method means that for enhancement
061   * the added byte code is minimised. In the case where metric collection is turned off overhead is
062   * limited to a System.nanoTime() call and a noop method call.
063   */
064  void operationEnd(int opCode, long startNanos, boolean activeThreadContext);
065
066  /**
067   * Add an event duration with opCode indicating success or failure. This is intended for use by
068   * enhanced code and not general use.
069   */
070  void operationEnd(int opCode, long startNanos);
071
072  /**
073   * Return true if this TimedMetric has been pushed onto an active context for this thread.
074   * <p>
075   * This means that the current thread is actively collecting timing entries and this metric
076   * has been pushed onto the nested context.
077   * </p>
078   */
079  boolean isActiveThreadContext();
080
081  /**
082   * Specify to collect per request detailed timing collection. The collectionCount is the number
083   * of requests to collect detailed timing for and then automatically turn off.
084   * <p>
085   * This is expected to only be explicitly called on 'top level' metrics such as web endpoints.
086   * Once a request timing context has been created by the top level metric then 'nested metrics'
087   * (typically service and data access layers) can append to that existing context.  In this way
088   * detailed per request level timing entries can be collected for only selected endpoints.
089   * </p>
090   */
091  void setRequestTimingCollection(int collectionCount);
092
093  /**
094   * Return the number of remaining requests to collect detailed timing on.
095   * <p>
096   * This value starts out as the value set by #setRequestTimingCollection and then decrements
097   * after a request timing is reported until it reaches 0 at which point request timing automatically
098   * turns off for this metric.
099   * </p>
100   */
101  int getRequestTimingCollection();
102
103  /**
104   * Decrement the request timing collection count.
105   * <p>
106   * This is typically called internally when a request timing is reported and generally not
107   * expected to be called by application code.
108   */
109  void decrementCollectionCount();
110
111  /**
112   * Return extra attributes that can be included in the request logging.
113   */
114  Map<String, String> attributes();
115}