voxel.devices.metrics.read

Get the raw data from a monitored metric on a device.

Parameters

device_id (required)
Numeric Voxel device id, available from voxel.devices.list
metric (required)
The name of the metric for which to get data. Possible metrics include memory, io, hdd, load, cpu, and bandwidth. Not all metrics are available for all device types.
start_time (optional)
Unix timestamp specifying the time at which the returned metric data should begin.
end_time (optional)
Unix timestamp specifying the time at which the returned metric data should end.
step_size (optional)
Amount of time between datapoints. One of Minute, Hour, Day, Week, Month, Year.
steps (optional)
The number of data points to return.
interface (optional)
An interface (for example "eth0") to use when trying to fetch "bandwidth" metrics. Not required for VoxCAST devices.
port (optional)
A switch port (for example: "Fa4/1") on which to check io metrics. Only applicable when fetching "io" metrics for devices of type switch

Example Response


<rsp stat="ok">
    <metric name="hdd" start_time="1275555600" step_size="Hour">
        <datapoints device_id="16">
            <datapoint start_time="1275555600">
                <metric_data>
                    <value label="used" source="/" type="4used">119701492041</value>
                    <value label="size" source="/" type="4size">278436429824</value>
                    <value label="used" source="/boot" type="7used">12548096</value>
                    <value label="size" source="/boot" type="7size">95546368</value>
                </metric_data>
            </datapoint>
            <datapoint start_time="1275559200">
                <metric_data>
                    <value label="used" source="/" type="4used">119727933966</value>
                    <value label="size" source="/" type="4size">278436429824</value>
                    <value label="used" source="/boot" type="7used">12548096</value>
                    <value label="size" source="/boot" type="7size">95546368</value>
                </metric_data>
            </datapoint>
        </datapoints>
    </metric>
</rsp>

 

Notes

If time interval parameters are not specified, a default set of recent data points will be returned.

The underlying data powering this method may be Minute or Hourly data. Minute data is limited to one day for most metrics, and two months for bandwidth metrics. Hourly data is stored for two years.

Underlying data is aggregated over the specified step_size by averaging. This means that some data such as load averages may be averaged more than once.

The "type" attributes are labels that can be used to programmatically reference a particular piece of metric data. The "label" attribute is intended to be user-readable, and is subject to change. The "source" attribute is only set for certain metrics which require additional hardware information in order to make the data more useful.

See voxel.devices.metrics.list for a list of available metric types.

Method Specific Error Codes

100: Unknown device
The device_id passed in can't be matched to a valid device.
105: Unknown metric
The metric passed in can't be matched to a valid metric for this device.