MetricsRecord (Hadoop 0.20.2-CDH3B4 API)
Date: 2011-02-21

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.hadoop.metrics
Interface MetricsRecord

All Known Implementing Classes:
  MetricsRecordImpl

    public interface MetricsRecord

A named and optionally tagged set of records to be sent to the metrics system.

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".

A record has zero or more tags. 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.

A record also has zero or more metrics. 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.

The general procedure for using a MetricsRecord is to fill in its tag and metric values, and then call `update()` to pass the record to the client library. Metric data is not immediately sent to the metrics system each time that `update()` 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.

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 `remove()` method can be used to remove the row and thus stop the data from being sent.

Note that the `update()` 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 `update()` on MetricsRecord instances with the same set of tag names and tag values. Different threads should not use the same MetricsRecord instance at the same time.

Method Summary
`String` | `getRecordName()` Returns the record name.
`void` | `incrMetric(String metricName, byte metricValue)` Increments the named metric by the specified value.
`void` | `incrMetric(String metricName, float metricValue)` Increments the named metric by the specified value.
`void` | `incrMetric(String metricName, int metricValue)` Increments the named metric by the specified value.
`void` | `incrMetric(String metricName, long metricValue)` Increments the named metric by the specified value.
`void` | `incrMetric(String metricName, short metricValue)` Increments the named metric by the specified value.
`void` | `remove()` Removes, from the buffered data table, all rows having tags that equal the tags that have been set on this record.
`void` | `removeTag(String tagName)` Removes any tag of the specified name.
`void` | `setMetric(String metricName, byte metricValue)` Sets the named metric to the specified value.
`void` | `setMetric(String metricName, float metricValue)` Sets the named metric to the specified value.
`void` | `setMetric(String metricName, int metricValue)` Sets the named metric to the specified value.
`void` | `setMetric(String metricName, long metricValue)` Sets the named metric to the specified value.
`void` | `setMetric(String metricName, short metricValue)` Sets the named metric to the specified value.
`void` | `setTag(String tagName, byte tagValue)` Sets the named tag to the specified value.
`void` | `setTag(String tagName, int tagValue)` Sets the named tag to the specified value.
`void` | `setTag(String tagName, long tagValue)` Sets the named tag to the specified value.
`void` | `setTag(String tagName, short tagValue)` Sets the named tag to the specified value.
`void` | `setTag(String tagName, String tagValue)` Sets the named tag to the specified value.
`void` | `update()` Updates the table of buffered data which is to be sent periodically.

Method Detail

### getRecordName

    String getRecordName()

  Returns the record name.

  Returns:
    the record name

### setTag

    void setTag(String tagName,
                String tagValue)

  Sets the named tag to the specified value. The tagValue may be null, which is treated the same as an empty String.

  Parameters:
    `tagName` - name of the tag
    `tagValue` - new value of the tag
  Throws:
    `MetricsException` - if the tagName conflicts with the configuration

### setTag

    void setTag(String tagName,
                int tagValue)

  Sets the named tag to the specified value.

  Parameters:
    `tagName` - name of the tag
    `tagValue` - new value of the tag
  Throws:
    `MetricsException` - if the tagName conflicts with the configuration

### setTag

    void setTag(String tagName,
                long tagValue)

  Sets the named tag to the specified value.

  Parameters:
    `tagName` - name of the tag
    `tagValue` - new value of the tag
  Throws:
    `MetricsException` - if the tagName conflicts with the configuration

### setTag

    void setTag(String tagName,
                short tagValue)

  Sets the named tag to the specified value.

  Parameters:
    `tagName` - name of the tag
    `tagValue` - new value of the tag
  Throws:
    `MetricsException` - if the tagName conflicts with the configuration

### setTag

    void setTag(String tagName,
                byte tagValue)

  Sets the named tag to the specified value.

  Parameters:
    `tagName` - name of the tag
    `tagValue` - new value of the tag
  Throws:
    `MetricsException` - if the tagName conflicts with the configuration

### removeTag

    void removeTag(String tagName)

  Removes any tag of the specified name.

  Parameters:
    `tagName` - name of a tag

### setMetric

    void setMetric(String metricName,
                   int metricValue)

  Sets the named metric to the specified value.

  Parameters:
    `metricName` - name of the metric
    `metricValue` - new value of the metric
  Throws:
    `MetricsException` - if the metricName or the type of the metricValue conflicts with the configuration

### setMetric

    void setMetric(String metricName,
                   long metricValue)

  Sets the named metric to the specified value.

  Parameters:
    `metricName` - name of the metric
    `metricValue` - new value of the metric
  Throws:
    `MetricsException` - if the metricName or the type of the metricValue conflicts with the configuration

### setMetric

    void setMetric(String metricName,
                   short metricValue)

  Sets the named metric to the specified value.

  Parameters:
    `metricName` - name of the metric
    `metricValue` - new value of the metric
  Throws:
    `MetricsException` - if the metricName or the type of the metricValue conflicts with the configuration

### setMetric

    void setMetric(String metricName,
                   byte metricValue)

  Sets the named metric to the specified value.

  Parameters:
    `metricName` - name of the metric
    `metricValue` - new value of the metric
  Throws:
    `MetricsException` - if the metricName or the type of the metricValue conflicts with the configuration

### setMetric

    void setMetric(String metricName,
                   float metricValue)

  Sets the named metric to the specified value.

  Parameters:
    `metricName` - name of the metric
    `metricValue` - new value of the metric
  Throws:
    `MetricsException` - if the metricName or the type of the metricValue conflicts with the configuration

### incrMetric

    void incrMetric(String metricName,
                    int metricValue)

  Increments the named metric by the specified value.

  Parameters:
    `metricName` - name of the metric
    `metricValue` - incremental value
  Throws:
    `MetricsException` - if the metricName or the type of the metricValue conflicts with the configuration

### incrMetric

    void incrMetric(String metricName,
                    long metricValue)

  Increments the named metric by the specified value.

  Parameters:
    `metricName` - name of the metric
    `metricValue` - incremental value
  Throws:
    `MetricsException` - if the metricName or the type of the metricValue conflicts with the configuration

### incrMetric

    void incrMetric(String metricName,
                    short metricValue)

  Increments the named metric by the specified value.

  Parameters:
    `metricName` - name of the metric
    `metricValue` - incremental value
  Throws:
    `MetricsException` - if the metricName or the type of the metricValue conflicts with the configuration

### incrMetric

    void incrMetric(String metricName,
                    byte metricValue)

  Increments the named metric by the specified value.

  Parameters:
    `metricName` - name of the metric
    `metricValue` - incremental value
  Throws:
    `MetricsException` - if the metricName or the type of the metricValue conflicts with the configuration

### incrMetric

    void incrMetric(String metricName,
                    float metricValue)

  Increments the named metric by the specified value.

  Parameters:
    `metricName` - name of the metric
    `metricValue` - incremental value
  Throws:
    `MetricsException` - if the metricName or the type of the metricValue conflicts with the configuration

### update

    void update()

  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.

### remove

    void remove()

  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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2009 The Apache Software Foundation