Reference Guide

•
When the value of the TimeStampedMetric that the data point was formulated from was last
updated
•
How many milliseconds (prior to the last update time) are encompassed by the reported
value
•
The value measured over the milliseconds spanned by the data point
•
Sufficient information is thus provided should the data recipient wish to normalize the data to
a standard interval length to smooth fluctuations in value that may be introduced by
variations in the milliseconds spanned by time series values.
Summarized Values
Time series values may also be requested from the REST API in a form that is not "raw", such that
each value returned represents a longer interval than the "raw" values persisted for a
TimeStampedMetric. In this case the necessary data must be read in "raw" form from the data
store and further summarized to produce values that span the requested interval before being
returned. For example, if a particular TimeStampedMetric's values were persisted every five
minutes and the REST API was invoked to retrieve hourly time series values for that
TimeStampedMetric, twelve "raw" values that each span five minutes would be read from the data
store and combined to produce a single resulting data point that spans the same hour
encompassed by the twelve "raw" data points.
There may be gaps in the "raw" data points that span a specific interval when summarized values
are returned. Continuing the preceding example of returning values that each represent an hour
interval with "raw" data points that each represent five minutes, one would typically expect that
twelve such "raw" data values would be summarized to produce one returned value. But in some
cases there could be gaps in the "raw" data for a given hour, for example for one hour span there
may be only ten "raw" data points persisted. Such gaps should be relatively infrequent and may
be caused by various situations; the source of the metric's data, perhaps a device on the network,
might be inaccessible, or perhaps the controller rebooted. The effect of any such gaps will be
accounted for in the summarized values that are returned; the information provided by each
resulting value is sufficient for the recipient to normalize the data to smooth any inconsistencies
introduced by gaps if so desired.
When summarized values are returned each resulting value represents the summary of a set of
"raw" data points. These sets must be anchored somehow in the total time span encompassed by
the REST request. For example, the time series data requested could be for a week of hourly data
ending at the current time. Suppose that the "raw" data points for the specified metric were
persisted at one-minute intervals, but that they started only four days ago; the first hour of data
returned will span a time interval that starts at the time of the oldest data point within the time
span encompassed by the REST request, in this case beginning four days ago. Each summarized
value will be produced from "raw" data points that are offset from the starting time of the first data
point returned. Continuing our example every hour value returned will be produced by "raw"
minute data points that are offset by some multiple of 60 minutes from starting time of the first
returned data point, four days ago in this case.
The technique used to summarize "raw" TimeStampedMetric values to produce summarized values
is contingent upon the type of TimeStampedMetric the data resulted from. For all
TimeStampedMetric types, the milliseconds spanned by each "raw" value are simply summed over
the specified interval and the latest update time stamp among the "raw" values is reported as the
last updated time stamp of the resulting value.
54