| /* |
| * MetricsRecord.java |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you 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. |
| */ |
| |
| package org.apache.hadoop.metrics; |
| |
| import org.apache.hadoop.classification.InterfaceAudience; |
| import org.apache.hadoop.classification.InterfaceStability; |
| |
| /** |
| * A named and optionally tagged set of records to be sent to the metrics |
| * system. <p/> |
| * |
| * A record name identifies the kind of data to be reported. For example, a |
| * program reporting statistics relating to the disks on a computer might use |
| * a record name "diskStats".<p/> |
| * |
| * A record has zero or more <i>tags</i>. A tag has a name and a value. To |
| * continue the example, the "diskStats" record might use a tag named |
| * "diskName" to identify a particular disk. Sometimes it is useful to have |
| * more than one tag, so there might also be a "diskType" with value "ide" or |
| * "scsi" or whatever.<p/> |
| * |
| * A record also has zero or more <i>metrics</i>. These are the named |
| * values that are to be reported to the metrics system. In the "diskStats" |
| * example, possible metric names would be "diskPercentFull", "diskPercentBusy", |
| * "kbReadPerSecond", etc.<p/> |
| * |
| * The general procedure for using a MetricsRecord is to fill in its tag and |
| * metric values, and then call <code>update()</code> to pass the record to the |
| * client library. |
| * Metric data is not immediately sent to the metrics system |
| * each time that <code>update()</code> is called. |
| * An internal table is maintained, identified by the record name. This |
| * table has columns |
| * corresponding to the tag and the metric names, and rows |
| * corresponding to each unique set of tag values. An update |
| * either modifies an existing row in the table, or adds a new row with a set of |
| * tag values that are different from all the other rows. Note that if there |
| * are no tags, then there can be at most one row in the table. <p/> |
| * |
| * Once a row is added to the table, its data will be sent to the metrics system |
| * on every timer period, whether or not it has been updated since the previous |
| * timer period. If this is inappropriate, for example if metrics were being |
| * reported by some transient object in an application, the <code>remove()</code> |
| * method can be used to remove the row and thus stop the data from being |
| * sent.<p/> |
| * |
| * Note that the <code>update()</code> method is atomic. This means that it is |
| * safe for different threads to be updating the same metric. More precisely, |
| * it is OK for different threads to call <code>update()</code> on MetricsRecord instances |
| * with the same set of tag names and tag values. Different threads should |
| * <b>not</b> use the same MetricsRecord instance at the same time. |
| * |
| * @deprecated Use {@link org.apache.hadoop.metrics2.MetricsRecord} instead. |
| */ |
| @Deprecated |
| @InterfaceAudience.Private |
| @InterfaceStability.Evolving |
| public interface MetricsRecord { |
| |
| /** |
| * Returns the record name. |
| * |
| * @return the record name |
| */ |
| public abstract String getRecordName(); |
| |
| /** |
| * Sets the named tag to the specified value. The tagValue may be null, |
| * which is treated the same as an empty String. |
| * |
| * @param tagName name of the tag |
| * @param tagValue new value of the tag |
| * @throws MetricsException if the tagName conflicts with the configuration |
| */ |
| public abstract void setTag(String tagName, String tagValue); |
| |
| /** |
| * Sets the named tag to the specified value. |
| * |
| * @param tagName name of the tag |
| * @param tagValue new value of the tag |
| * @throws MetricsException if the tagName conflicts with the configuration |
| */ |
| public abstract void setTag(String tagName, int tagValue); |
| |
| /** |
| * Sets the named tag to the specified value. |
| * |
| * @param tagName name of the tag |
| * @param tagValue new value of the tag |
| * @throws MetricsException if the tagName conflicts with the configuration |
| */ |
| public abstract void setTag(String tagName, long tagValue); |
| |
| /** |
| * Sets the named tag to the specified value. |
| * |
| * @param tagName name of the tag |
| * @param tagValue new value of the tag |
| * @throws MetricsException if the tagName conflicts with the configuration |
| */ |
| public abstract void setTag(String tagName, short tagValue); |
| |
| /** |
| * Sets the named tag to the specified value. |
| * |
| * @param tagName name of the tag |
| * @param tagValue new value of the tag |
| * @throws MetricsException if the tagName conflicts with the configuration |
| */ |
| public abstract void setTag(String tagName, byte tagValue); |
| |
| /** |
| * Removes any tag of the specified name. |
| * |
| * @param tagName name of a tag |
| */ |
| public abstract void removeTag(String tagName); |
| |
| /** |
| * Sets the named metric to the specified value. |
| * |
| * @param metricName name of the metric |
| * @param metricValue new value of the metric |
| * @throws MetricsException if the metricName or the type of the metricValue |
| * conflicts with the configuration |
| */ |
| public abstract void setMetric(String metricName, int metricValue); |
| |
| /** |
| * Sets the named metric to the specified value. |
| * |
| * @param metricName name of the metric |
| * @param metricValue new value of the metric |
| * @throws MetricsException if the metricName or the type of the metricValue |
| * conflicts with the configuration |
| */ |
| public abstract void setMetric(String metricName, long metricValue); |
| |
| /** |
| * Sets the named metric to the specified value. |
| * |
| * @param metricName name of the metric |
| * @param metricValue new value of the metric |
| * @throws MetricsException if the metricName or the type of the metricValue |
| * conflicts with the configuration |
| */ |
| public abstract void setMetric(String metricName, short metricValue); |
| |
| /** |
| * Sets the named metric to the specified value. |
| * |
| * @param metricName name of the metric |
| * @param metricValue new value of the metric |
| * @throws MetricsException if the metricName or the type of the metricValue |
| * conflicts with the configuration |
| */ |
| public abstract void setMetric(String metricName, byte metricValue); |
| |
| /** |
| * Sets the named metric to the specified value. |
| * |
| * @param metricName name of the metric |
| * @param metricValue new value of the metric |
| * @throws MetricsException if the metricName or the type of the metricValue |
| * conflicts with the configuration |
| */ |
| public abstract void setMetric(String metricName, float metricValue); |
| |
| /** |
| * Increments the named metric by the specified value. |
| * |
| * @param metricName name of the metric |
| * @param metricValue incremental value |
| * @throws MetricsException if the metricName or the type of the metricValue |
| * conflicts with the configuration |
| */ |
| public abstract void incrMetric(String metricName, int metricValue); |
| |
| /** |
| * Increments the named metric by the specified value. |
| * |
| * @param metricName name of the metric |
| * @param metricValue incremental value |
| * @throws MetricsException if the metricName or the type of the metricValue |
| * conflicts with the configuration |
| */ |
| public abstract void incrMetric(String metricName, long metricValue); |
| |
| /** |
| * Increments the named metric by the specified value. |
| * |
| * @param metricName name of the metric |
| * @param metricValue incremental value |
| * @throws MetricsException if the metricName or the type of the metricValue |
| * conflicts with the configuration |
| */ |
| public abstract void incrMetric(String metricName, short metricValue); |
| |
| /** |
| * Increments the named metric by the specified value. |
| * |
| * @param metricName name of the metric |
| * @param metricValue incremental value |
| * @throws MetricsException if the metricName or the type of the metricValue |
| * conflicts with the configuration |
| */ |
| public abstract void incrMetric(String metricName, byte metricValue); |
| |
| /** |
| * Increments the named metric by the specified value. |
| * |
| * @param metricName name of the metric |
| * @param metricValue incremental value |
| * @throws MetricsException if the metricName or the type of the metricValue |
| * conflicts with the configuration |
| */ |
| public abstract void incrMetric(String metricName, float metricValue); |
| |
| /** |
| * Updates the table of buffered data which is to be sent periodically. |
| * If the tag values match an existing row, that row is updated; |
| * otherwise, a new row is added. |
| */ |
| public abstract void update(); |
| |
| /** |
| * Removes, from the buffered data table, all rows having tags |
| * that equal the tags that have been set on this record. For example, |
| * if there are no tags on this record, all rows for this record name |
| * would be removed. Or, if there is a single tag on this record, then |
| * just rows containing a tag with the same name and value would be removed. |
| */ |
| public abstract void remove(); |
| |
| } |