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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.lang.String getRecordName()
      Returns the record name.
      void incrMetric​(java.lang.String metricName, byte metricValue)
      Increments the named metric by the specified value.
      void incrMetric​(java.lang.String metricName, float metricValue)
      Increments the named metric by the specified value.
      void incrMetric​(java.lang.String metricName, int metricValue)
      Increments the named metric by the specified value.
      void incrMetric​(java.lang.String metricName, long metricValue)
      Increments the named metric by the specified value.
      void incrMetric​(java.lang.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​(java.lang.String tagName)
      Removes any tag of the specified name.
      void setMetric​(java.lang.String metricName, byte metricValue)
      Sets the named metric to the specified value.
      void setMetric​(java.lang.String metricName, float metricValue)
      Sets the named metric to the specified value.
      void setMetric​(java.lang.String metricName, int metricValue)
      Sets the named metric to the specified value.
      void setMetric​(java.lang.String metricName, long metricValue)
      Sets the named metric to the specified value.
      void setMetric​(java.lang.String metricName, short metricValue)
      Sets the named metric to the specified value.
      void setTag​(java.lang.String tagName, byte tagValue)
      Sets the named tag to the specified value.
      void setTag​(java.lang.String tagName, int tagValue)
      Sets the named tag to the specified value.
      void setTag​(java.lang.String tagName, long tagValue)
      Sets the named tag to the specified value.
      void setTag​(java.lang.String tagName, short tagValue)
      Sets the named tag to the specified value.
      void setTag​(java.lang.String tagName, java.lang.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

        java.lang.String getRecordName()
        Returns the record name.
        Returns:
        the record name

      • setTag

        void setTag​(java.lang.String tagName,
            java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String tagName)
        Removes any tag of the specified name.
        Parameters:
        tagName - name of a tag

      • setMetric

        void setMetric​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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.