content: package act.metric;
  
  /*-
   * #%L
   * ACT Framework
   * %%
   * Copyright (C) 2014 - 2017 ActFramework
   * %%
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   * 
   *      http://www.apache.org/licenses/LICENSE-2.0
   * 
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   * #L%
   */
  
  /**
   * `Metric` is used to measure the application and framework performance.
   *
   * Two kinds of metrics are been implemented in ActFramework:
   *
   *
   * * Counter - count number of time an event occurred</li>
   * * Timer - measure the time spent on a specific event</li>
   *
   * ActFramework supports hierarchical metric. For example, suppose you want to measure
   * the time spent on direct web request handling and background jobs:
   *
   * measure direct request handling
   *
   * ```
   *     {@literal @}PostAction("/xyz")
   *     public void handleXyzRequest(String param) {
   *         Timer timer = metric.startTimer("direct_req_handling:xyz");
   *         try {
   *             // your logic to handle xyz request
   *         } finally {
   *             timer.stop();
   *         }
   *     }
   * ```
   *
   * measure a background job
   *
   * ```
   *     {@literal @}Every("1hr")
   *     public void scanDatabase() {
   *         Timer timer = metric.startTimer("background_job:scan_db");
   *         try {
   *             // your logic to scan database
   *         } finally {
   *             timer.stop();
   *         }
   *     }
   * ```
   *
   *  In the sample code shown above, the name used to start timers are `direct_req_handling:xyz`
   *  and `background_job:scan_db` respectively. Both name contains a metric hierarchy, say
   *  `direct_req_handling` followed by `xyz` and `background_job` followed by
   *  `scan_db`. The benefit of metric hierarchy is the value measured on child name will get
   *  aggregated automatically on parent name: Suppose you have two counters: "a:b": 100, and "a:c": 105,
   *  then your "a" counter will be 205.
   *
   */
  public interface Metric {
  
      /**
       * {@code PATH_SEPARATOR} is provided to support hierarchical metric
       */
      String PATH_SEPARATOR = ":";
  
      /**
       * The do-nothing metric instance
       */
      Metric NULL_METRIC = NullMetric.INSTANCE;
  
      /**
       * Call this method to increase one time for the counter specified
       * @param name A string specifies the counter
       */
      void countOnce(String name);
  
      /**
       * Call this method to start a {@link Timer} before starting a process.
       *
       * Note calling this method should automatically call {@link #countOnce(String)}
       * method with the `name` specified
       *
       * @param name A string specifies the timer
       * @return a Timer instance
       */
      Timer startTimer(String name);
  
  }
  