001package org.avaje.metric;
002
003import java.util.List;
004
005/**
006 * API for requesting and
007 */
008public interface RequestTimingManager {
009
010  /**
011   * Return the request timings that have been collected since the last collection.
012   */
013  List<RequestTiming> collectRequestTimings();
014
015  /**
016   * Return all the timing metrics that are currently collecting per request timings and whose name
017   * matches the name expression.
018   * <p>
019   * If the name match expression is null or empty then all timing metrics are returned.
020   * </p>
021   * <p>
022   * These are TimingMetric that have {@link TimedMetric#getRequestTimingCollection()}
023   * greater than 0.
024   * </p>
025   * <h3>Example name match expressions:</h3>
026   * <pre>{@code
027   *
028   *   // starts with web.
029   *   "web.*"
030   *
031   *   // end with resource
032   *   "*resource"
033   *
034   *   // starts with web. and contains customer
035   *   "web.*customer*"
036   *
037   *   // starts with web. and contains customer and ends with resource
038   *   "web.*customer*resource"
039   *
040   * }</pre>
041   *
042   * @param nameMatchExpression the expression used to match/filter metric names. Null or empty means match all.
043   *
044   * @return timing metrics that are actively collecting request timings.
045   */
046  List<TimingMetricInfo> getRequestTimingMetrics(String nameMatchExpression);
047
048  /**
049   * Return the list of all timing metrics that match the name expression.
050   * <p>
051   * If the name match expression is null or empty then all timing metrics are returned.
052   * </p>
053   *
054   * <h3>Example name match expressions:</h3>
055   * <pre>{@code
056   *
057   *   // starts with web.
058   *   "web.*"
059   *
060   *   // end with resource
061   *   "*resource"
062   *
063   *   // starts with web. and contains customer
064   *   "web.*customer*"
065   *
066   *   // starts with web. and contains customer and ends with resource
067   *   "web.*customer*resource"
068   *
069   * }</pre>
070   *
071   * @param nameMatchExpression the expression used to match/filter metric names. Null or empty means match all.
072   * @return all timing metrics those name matches the expression.
073   */
074  List<TimingMetricInfo> getAllTimingMetrics(String nameMatchExpression);
075
076  /**
077   * Set request timing on for a metric matching the name.
078   *
079   * @param collectionCount the number of requests to collect request timings for
080   * @return true if request timing was set, false if the metric was not found.
081   */
082  boolean setRequestTimingCollection(String metricName, int collectionCount);
083
084  /**
085   * Set request timing on for a metric matching the class and name.
086   *
087   * @param collectionCount the number of requests to collect request timings for
088   * @return true if request timing was set, false if the metric was not found.
089   */
090  boolean setRequestTimingCollection(Class<?> cls, String name, int collectionCount);
091
092  /**
093   * Set request timing on all the timed metrics whose name starts with a given prefix.
094   * <p>
095   * If for example all the web endpoints have a prefix of "web." then these can all be
096   * set to collect say 10 requests.
097   * </p>
098   *
099   * <h3>Example name match expressions:</h3>
100   * <pre>{@code
101   *
102   *   // starts with web.
103   *   "web.*"
104   *
105   *   // end with resource
106   *   "*resource"
107   *
108   *   // starts with web. and contains customer
109   *   "web.*customer*"
110   *
111   *   // starts with web. and contains customer and ends with resource
112   *   "web.*customer*resource"
113   *
114   * }</pre>
115   *
116   *
117   * @param nameMatchExpression       The expression used to match timing metrics
118   * @param collectionCount           The number of requests to collect
119   * @return The timing metrics that had the request timing collection set
120   */
121  List<TimingMetricInfo> setRequestTimingCollectionUsingMatch(String nameMatchExpression, int collectionCount);
122
123}