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.