MetricsRecord.java
上传用户:quxuerui
上传日期:2018-01-08
资源大小:41811k
文件大小:9k
源码类别:

网格计算

开发平台:

Java

  1. /*
  2.  * MetricsRecord.java
  3.  *
  4.  * Licensed to the Apache Software Foundation (ASF) under one
  5.  * or more contributor license agreements.  See the NOTICE file
  6.  * distributed with this work for additional information
  7.  * regarding copyright ownership.  The ASF licenses this file
  8.  * to you under the Apache License, Version 2.0 (the
  9.  * "License"); you may not use this file except in compliance
  10.  * with the License.  You may obtain a copy of the License at
  11.  *
  12.  *     http://www.apache.org/licenses/LICENSE-2.0
  13.  *
  14.  * Unless required by applicable law or agreed to in writing, software
  15.  * distributed under the License is distributed on an "AS IS" BASIS,
  16.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17.  * See the License for the specific language governing permissions and
  18.  * limitations under the License.
  19.  */
  20. package org.apache.hadoop.metrics;
  21. /**
  22.  * A named and optionally tagged set of records to be sent to the metrics
  23.  * system. <p/>
  24.  *
  25.  * A record name identifies the kind of data to be reported. For example, a
  26.  * program reporting statistics relating to the disks on a computer might use
  27.  * a record name "diskStats".<p/>
  28.  *
  29.  * A record has zero or more <i>tags</i>. A tag has a name and a value. To
  30.  * continue the example, the "diskStats" record might use a tag named
  31.  * "diskName" to identify a particular disk.  Sometimes it is useful to have
  32.  * more than one tag, so there might also be a "diskType" with value "ide" or
  33.  * "scsi" or whatever.<p/>
  34.  *
  35.  * A record also has zero or more <i>metrics</i>.  These are the named
  36.  * values that are to be reported to the metrics system.  In the "diskStats"
  37.  * example, possible metric names would be "diskPercentFull", "diskPercentBusy", 
  38.  * "kbReadPerSecond", etc.<p/>
  39.  * 
  40.  * The general procedure for using a MetricsRecord is to fill in its tag and
  41.  * metric values, and then call <code>update()</code> to pass the record to the
  42.  * client library.
  43.  * Metric data is not immediately sent to the metrics system
  44.  * each time that <code>update()</code> is called. 
  45.  * An internal table is maintained, identified by the record name. This
  46.  * table has columns 
  47.  * corresponding to the tag and the metric names, and rows 
  48.  * corresponding to each unique set of tag values. An update
  49.  * either modifies an existing row in the table, or adds a new row with a set of
  50.  * tag values that are different from all the other rows.  Note that if there
  51.  * are no tags, then there can be at most one row in the table. <p/>
  52.  * 
  53.  * Once a row is added to the table, its data will be sent to the metrics system 
  54.  * on every timer period, whether or not it has been updated since the previous
  55.  * timer period.  If this is inappropriate, for example if metrics were being
  56.  * reported by some transient object in an application, the <code>remove()</code>
  57.  * method can be used to remove the row and thus stop the data from being
  58.  * sent.<p/>
  59.  *
  60.  * Note that the <code>update()</code> method is atomic.  This means that it is
  61.  * safe for different threads to be updating the same metric.  More precisely,
  62.  * it is OK for different threads to call <code>update()</code> on MetricsRecord instances 
  63.  * with the same set of tag names and tag values.  Different threads should 
  64.  * <b>not</b> use the same MetricsRecord instance at the same time.
  65.  */
  66. public interface MetricsRecord {
  67.     
  68.   /**
  69.    * Returns the record name. 
  70.    *
  71.    * @return the record name
  72.    */
  73.   public abstract String getRecordName();
  74.     
  75.   /**
  76.    * Sets the named tag to the specified value.  The tagValue may be null, 
  77.    * which is treated the same as an empty String.
  78.    *
  79.    * @param tagName name of the tag
  80.    * @param tagValue new value of the tag
  81.    * @throws MetricsException if the tagName conflicts with the configuration
  82.    */
  83.   public abstract void setTag(String tagName, String tagValue);
  84.     
  85.   /**
  86.    * Sets the named tag to the specified value.
  87.    *
  88.    * @param tagName name of the tag
  89.    * @param tagValue new value of the tag
  90.    * @throws MetricsException if the tagName conflicts with the configuration
  91.    */
  92.   public abstract void setTag(String tagName, int tagValue);
  93.     
  94.   /**
  95.    * Sets the named tag to the specified value.
  96.    *
  97.    * @param tagName name of the tag
  98.    * @param tagValue new value of the tag
  99.    * @throws MetricsException if the tagName conflicts with the configuration
  100.    */
  101.   public abstract void setTag(String tagName, long tagValue);
  102.     
  103.   /**
  104.    * Sets the named tag to the specified value.
  105.    *
  106.    * @param tagName name of the tag
  107.    * @param tagValue new value of the tag
  108.    * @throws MetricsException if the tagName conflicts with the configuration
  109.    */
  110.   public abstract void setTag(String tagName, short tagValue);
  111.     
  112.   /**
  113.    * Sets the named tag to the specified value.
  114.    *
  115.    * @param tagName name of the tag
  116.    * @param tagValue new value of the tag
  117.    * @throws MetricsException if the tagName conflicts with the configuration
  118.    */
  119.   public abstract void setTag(String tagName, byte tagValue);
  120.     
  121.   /**
  122.    * Removes any tag of the specified name.
  123.    *
  124.    * @param tagName name of a tag
  125.    */
  126.   public abstract void removeTag(String tagName);
  127.   
  128.   /**
  129.    * Sets the named metric to the specified value.
  130.    *
  131.    * @param metricName name of the metric
  132.    * @param metricValue new value of the metric
  133.    * @throws MetricsException if the metricName or the type of the metricValue 
  134.    * conflicts with the configuration
  135.    */
  136.   public abstract void setMetric(String metricName, int metricValue);
  137.     
  138.   /**
  139.    * Sets the named metric to the specified value.
  140.    *
  141.    * @param metricName name of the metric
  142.    * @param metricValue new value of the metric
  143.    * @throws MetricsException if the metricName or the type of the metricValue 
  144.    * conflicts with the configuration
  145.    */
  146.   public abstract void setMetric(String metricName, long metricValue);
  147.     
  148.   /**
  149.    * Sets the named metric to the specified value.
  150.    *
  151.    * @param metricName name of the metric
  152.    * @param metricValue new value of the metric
  153.    * @throws MetricsException if the metricName or the type of the metricValue 
  154.    * conflicts with the configuration
  155.    */
  156.   public abstract void setMetric(String metricName, short metricValue);
  157.     
  158.   /**
  159.    * Sets the named metric to the specified value.
  160.    *
  161.    * @param metricName name of the metric
  162.    * @param metricValue new value of the metric
  163.    * @throws MetricsException if the metricName or the type of the metricValue 
  164.    * conflicts with the configuration
  165.    */
  166.   public abstract void setMetric(String metricName, byte metricValue);
  167.     
  168.   /**
  169.    * Sets the named metric to the specified value.
  170.    *
  171.    * @param metricName name of the metric
  172.    * @param metricValue new value of the metric
  173.    * @throws MetricsException if the metricName or the type of the metricValue 
  174.    * conflicts with the configuration
  175.    */
  176.   public abstract void setMetric(String metricName, float metricValue);
  177.     
  178.   /**
  179.    * Increments the named metric by the specified value.
  180.    *
  181.    * @param metricName name of the metric
  182.    * @param metricValue incremental value
  183.    * @throws MetricsException if the metricName or the type of the metricValue 
  184.    * conflicts with the configuration
  185.    */
  186.   public abstract void incrMetric(String metricName, int metricValue);
  187.     
  188.   /**
  189.    * Increments the named metric by the specified value.
  190.    *
  191.    * @param metricName name of the metric
  192.    * @param metricValue incremental value
  193.    * @throws MetricsException if the metricName or the type of the metricValue 
  194.    * conflicts with the configuration
  195.    */
  196.   public abstract void incrMetric(String metricName, long metricValue);
  197.     
  198.   /**
  199.    * Increments the named metric by the specified value.
  200.    *
  201.    * @param metricName name of the metric
  202.    * @param metricValue incremental value
  203.    * @throws MetricsException if the metricName or the type of the metricValue 
  204.    * conflicts with the configuration
  205.    */
  206.   public abstract void incrMetric(String metricName, short metricValue);
  207.     
  208.   /**
  209.    * Increments the named metric by the specified value.
  210.    *
  211.    * @param metricName name of the metric
  212.    * @param metricValue incremental value
  213.    * @throws MetricsException if the metricName or the type of the metricValue 
  214.    * conflicts with the configuration
  215.    */
  216.   public abstract void incrMetric(String metricName, byte metricValue);
  217.     
  218.   /**
  219.    * Increments the named metric by the specified value.
  220.    *
  221.    * @param metricName name of the metric
  222.    * @param metricValue incremental value
  223.    * @throws MetricsException if the metricName or the type of the metricValue 
  224.    * conflicts with the configuration
  225.    */
  226.   public abstract void incrMetric(String metricName, float metricValue);
  227.     
  228.   /**
  229.    * Updates the table of buffered data which is to be sent periodically.
  230.    * If the tag values match an existing row, that row is updated; 
  231.    * otherwise, a new row is added.
  232.    */
  233.   public abstract void update();
  234.     
  235.   /**
  236.    * Removes, from the buffered data table, all rows having tags 
  237.    * that equal the tags that have been set on this record. For example,
  238.    * if there are no tags on this record, all rows for this record name
  239.    * would be removed.  Or, if there is a single tag on this record, then
  240.    * just rows containing a tag with the same name and value would be removed.
  241.    */
  242.   public abstract void remove();
  243.     
  244. }