Package com.mapr.org.apache.hadoop.metrics

Interface MetricsRecord

All Known Implementing Classes:
MetricsRecordImpl
@Private @Evolving 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

    Modifier and Type
    Method
    Description
    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 Details

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