Overview
Engineers and data scientists can use the Cloud SDK to query telemetry stream data for analysis. Telemetry stream data must have been ingested by one of the many methods found in Data ingestion from a device or Data ingestion from anywhere before it can be queried.
Querying data from the command line
If you are more interested in querying from the command line, you can do that using the
fctltool. Please check fctl documentation for more information.
Queries
Required parameters
Queries for telemetry data have two required parameters: start and end timestamps.
If a query contains only those two parameters, all telemetry datapoints from all devices in your organization whose timestamp falls between start and end will be returned.
Timestamp formatting
start and end are RFC3339 formatted timestamps. (e.g. 2021-01-01T01:00:00.000Z)
All timestamps are UTC. When using the Cloud SDK, it may be useful to toggle UTC timestamps in the Formant web application.
Toggling UTC timestamps may make life easier while using the Cloud SDK
Optional parameters
To filter the query down more, you can use the optional query parameters: deviceIds, names, notNames, types, and tags.
Queries can be too large
If you see this:
requests.exceptions.HTTPError: 413 Client Error: Payload Too Large for url: https://api.formant.io/v1/queries/queries
The query contained too much data to return. Try narrowing the query further via parameters and try again.
Basic script for querying telemetry data from one device
This script will query for Network and CPU data (default streams), for a specific device, in a 1-minute period in February 2021:
from formant.sdk.cloud.v1 import Client as FormantClient
if __name__ == "__main__":
# to authenticate set FORMANT_EMAIL and FORMANT_PASSWORD
# environment variables for an existing service account
fclient = FormantClient()
# use the url on a device telemetry page to find a device's ID,
# or use the query_devices method
device_id = "2c18bc8b-c5e4-4ea0-8886-a8363d185597"
result = fclient.query(
{
"start": "2021-02-22T23:59:00.000Z",
"end": "2021-02-23T00:00:00.000Z",
"deviceIds": [device_id],
"names": ["$.host.network", "$.host.cpu"],
}
)
print(result)
If datapoints are present on those default streams, at that time, for the device ID provided, the result will look something like this:
{'items': [{'agentId': '2c18bc8b-c5e4-4ea0-8886-a8363d185597',
'deviceId': '2c18bc8b-c5e4-4ea0-8886-a8363d185597',
'name': '$.host.cpu',
'points': [[1614038340636,
[{'label': 'utilization',
'unit': '%',
'value': 9.166666666654544},
{'label': 'load avg 1 min', 'value': 0.96}]],
[1614038341642,
[{'label': 'utilization',
'unit': '%',
'value': 7.833333333352732},
{'label': 'load avg 1 min', 'value': 0.96}]],
[1614038342649,
[{'label': 'utilization',
'unit': '%',
'value': 9.499999999995145},
{'label': 'load avg 1 min', 'value': 0.96}]],
[1614038343655,
[{'label': 'utilization',
'unit': '%',
'value': 9.666666666695766},
{'label': 'load avg 1 min', 'value': 0.96}]],
[1614038344663,
[{'label': 'utilization',
'unit': '%',
'value': 10.499999999956344},
{'label': 'load avg 1 min', 'value': 0.96}]],
[1614038345668,
[{'label': 'utilization',
'unit': '%',
'value': 7.166666666671517},
{'label': 'load avg 1 min', 'value': 0.96}]],
[1614038346673,
[{'label': 'utilization',
'unit': '%',
'value': 9.166666666654544},
{'label': 'load avg 1 min', 'value': 0.96}]],
[1614038347678,
[{'label': 'utilization',
'unit': '%',
'value': 7.666666666712752},
{'label': 'load avg 1 min', 'value': 0.96}]],
[1614038348684,
[{'label': 'utilization',
'unit': '%',
'value': 7.833333333292103},
{'label': 'load avg 1 min', 'value': 0.89}]],
[1614038349690,
[{'label': 'utilization',
'unit': '%',
'value': 10.00000000003638},
{'label': 'load avg 1 min', 'value': 0.89}]],
[1614038350695,
[{'label': 'utilization',
'unit': '%',
'value': 7.999999999992724},
{'label': 'load avg 1 min', 'value': 0.89}]],
[1614038351700,
[{'label': 'utilization',
'unit': '%',
'value': 6.999999999970896},
{'label': 'load avg 1 min', 'value': 0.89}]],
[1614038352706,
[{'label': 'utilization',
'unit': '%',
'value': 10.500000000016973},
{'label': 'load avg 1 min', 'value': 0.89}]],
[1614038353717,
[{'label': 'utilization',
'unit': '%',
'value': 7.666666666652111},
{'label': 'load avg 1 min', 'value': 0.81}]],
[1614038354722,
[{'label': 'utilization',
'unit': '%',
'value': 11.33333333333818},
{'label': 'load avg 1 min', 'value': 0.81}]],
[1614038355727,
[{'label': 'utilization',
'unit': '%',
'value': 8.500000000033959},
{'label': 'load avg 1 min', 'value': 0.81}]],
[1614038356732,
[{'label': 'utilization',
'unit': '%',
'value': 8.499999999973317},
{'label': 'load avg 1 min', 'value': 0.81}]],
[1614038357740,
[{'label': 'utilization',
'unit': '%',
'value': 7.33333333331151},
{'label': 'load avg 1 min', 'value': 0.81}]],
[1614038358748,
[{'label': 'utilization',
'unit': '%',
'value': 8.500000000033959},
{'label': 'load avg 1 min', 'value': 0.75}]],
[1614038359753,
[{'label': 'utilization',
'unit': '%',
'value': 8.83333333331393},
{'label': 'load avg 1 min', 'value': 0.75}]],
[1614038360758,
[{'label': 'utilization',
'unit': '%',
'value': 7.500000000012131},
{'label': 'load avg 1 min', 'value': 0.75}]],
[1614038361763,
[{'label': 'utilization',
'unit': '%',
'value': 8.499999999973317},
{'label': 'load avg 1 min', 'value': 0.75}]],
[1614038362768,
[{'label': 'utilization',
'unit': '%',
'value': 9.833333333335759},
{'label': 'load avg 1 min', 'value': 0.75}]],
[1614038363771,
[{'label': 'utilization',
'unit': '%',
'value': 8.500000000033959},
{'label': 'load avg 1 min', 'value': 0.69}]],
[1614038364777,
[{'label': 'utilization',
'unit': '%',
'value': 9.499999999995145},
{'label': 'load avg 1 min', 'value': 0.69}]],
[1614038365780,
[{'label': 'utilization',
'unit': '%',
'value': 7.833333333352732},
{'label': 'load avg 1 min', 'value': 0.69}]],
[1614038366785,
[{'label': 'utilization',
'unit': '%',
'value': 7.33333333331151},
{'label': 'load avg 1 min', 'value': 0.69}]],
[1614038367790,
[{'label': 'utilization',
'unit': '%',
'value': 8.166666666693345},
{'label': 'load avg 1 min', 'value': 0.69}]],
[1614038368795,
[{'label': 'utilization',
'unit': '%',
'value': 8.499999999973317},
{'label': 'load avg 1 min', 'value': 0.63}]],
[1614038369800,
[{'label': 'utilization',
'unit': '%',
'value': 8.499999999973317},
{'label': 'load avg 1 min', 'value': 0.63}]],
[1614038370805,
[{'label': 'utilization',
'unit': '%',
'value': 8.000000000053353},
{'label': 'load avg 1 min', 'value': 0.63}]],
[1614038371811,
[{'label': 'utilization',
'unit': '%',
'value': 7.999999999992724},
{'label': 'load avg 1 min', 'value': 0.63}]],
[1614038372818,
[{'label': 'utilization',
'unit': '%',
'value': 9.166666666654544},
{'label': 'load avg 1 min', 'value': 0.63}]],
[1614038373823,
[{'label': 'utilization',
'unit': '%',
'value': 9.833333333335759},
{'label': 'load avg 1 min', 'value': 0.74}]],
[1614038374826,
[{'label': 'utilization',
'unit': '%',
'value': 8.333333333333337},
{'label': 'load avg 1 min', 'value': 0.74}]],
[1614038375832,
[{'label': 'utilization',
'unit': '%',
'value': 8.83333333331393},
{'label': 'load avg 1 min', 'value': 0.74}]],
[1614038376839,
[{'label': 'utilization',
'unit': '%',
'value': 8.166666666693345},
{'label': 'load avg 1 min', 'value': 0.74}]],
[1614038377844,
[{'label': 'utilization',
'unit': '%',
'value': 8.166666666632716},
{'label': 'load avg 1 min', 'value': 0.74}]],
[1614038378849,
[{'label': 'utilization',
'unit': '%',
'value': 8.500000000033959},
{'label': 'load avg 1 min', 'value': 0.68}]],
[1614038379855,
[{'label': 'utilization',
'unit': '%',
'value': 8.666666666673938},
{'label': 'load avg 1 min', 'value': 0.68}]],
[1614038380862,
[{'label': 'utilization',
'unit': '%',
'value': 8.333333333333337},
{'label': 'load avg 1 min', 'value': 0.68}]],
[1614038381867,
[{'label': 'utilization',
'unit': '%',
'value': 7.666666666652111},
{'label': 'load avg 1 min', 'value': 0.68}]],
[1614038382874,
[{'label': 'utilization',
'unit': '%',
'value': 9.666666666635138},
{'label': 'load avg 1 min', 'value': 0.68}]],
[1614038383879,
[{'label': 'utilization',
'unit': '%',
'value': 9.000000000014552},
{'label': 'load avg 1 min', 'value': 0.71}]],
[1614038384884,
[{'label': 'utilization',
'unit': '%',
'value': 9.166666666654544},
{'label': 'load avg 1 min', 'value': 0.71}]],
[1614038385889,
[{'label': 'utilization',
'unit': '%',
'value': 9.333333333355165},
{'label': 'load avg 1 min', 'value': 0.71}]],
[1614038386894,
[{'label': 'utilization',
'unit': '%',
'value': 8.166666666632716},
{'label': 'load avg 1 min', 'value': 0.71}]],
[1614038387899,
[{'label': 'utilization',
'unit': '%',
'value': 8.166666666693345},
{'label': 'load avg 1 min', 'value': 0.71}]],
[1614038388905,
[{'label': 'utilization',
'unit': '%',
'value': 9.999999999975751},
{'label': 'load avg 1 min', 'value': 0.73}]],
[1614038389911,
[{'label': 'utilization',
'unit': '%',
'value': 7.833333333352732},
{'label': 'load avg 1 min', 'value': 0.73}]],
[1614038390918,
[{'label': 'utilization',
'unit': '%',
'value': 8.166666666693345},
{'label': 'load avg 1 min', 'value': 0.73}]],
[1614038391923,
[{'label': 'utilization',
'unit': '%',
'value': 8.333333333333337},
{'label': 'load avg 1 min', 'value': 0.73}]],
[1614038392929,
[{'label': 'utilization',
'unit': '%',
'value': 9.333333333294524},
{'label': 'load avg 1 min', 'value': 0.73}]],
[1614038393934,
[{'label': 'utilization',
'unit': '%',
'value': 9.333333333355165},
{'label': 'load avg 1 min', 'value': 0.67}]],
[1614038394940,
[{'label': 'utilization',
'unit': '%',
'value': 8.666666666673938},
{'label': 'load avg 1 min', 'value': 0.67}]],
[1614038395945,
[{'label': 'utilization',
'unit': '%',
'value': 12.166666666659387},
{'label': 'load avg 1 min', 'value': 0.67}]],
[1614038396950,
[{'label': 'utilization',
'unit': '%',
'value': 9.999999999975751},
{'label': 'load avg 1 min', 'value': 0.67}]],
[1614038397954,
[{'label': 'utilization',
'unit': '%',
'value': 11.666666666678793},
{'label': 'load avg 1 min', 'value': 0.67}]],
[1614038398960,
[{'label': 'utilization',
'unit': '%',
'value': 10.00000000003638},
{'label': 'load avg 1 min', 'value': 0.62}]],
[1614038399965,
[{'label': 'utilization',
'unit': '%',
'value': 9.833333333335759},
{'label': 'load avg 1 min', 'value': 0.62}]]],
'tags': {},
'type': 'numeric set'},
{'agentId': '2c18bc8b-c5e4-4ea0-8886-a8363d185597',
'deviceId': '2c18bc8b-c5e4-4ea0-8886-a8363d185597',
'name': '$.host.network',
'points': [[1614038340101,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.043528},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.027896}]],
[1614038341104,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.030912},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.00876}]],
[1614038342107,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.019864},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.00828}]],
[1614038343110,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.044552},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.016352}]],
[1614038344113,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.053104},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.0648}]],
[1614038345119,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.024616},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.019144}]],
[1614038346122,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.031888},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.011456}]],
[1614038347125,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.036728},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.013496}]],
[1614038348127,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.023368},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.003544}]],
[1614038349128,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.040496},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.022392}]],
[1614038350134,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.043344},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.025168}]],
[1614038351138,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.013008},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.002728}]],
[1614038352141,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.037608},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.016416}]],
[1614038353143,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.042824},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.009576}]],
[1614038354144,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.022832},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.008344}]],
[1614038355147,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.047016},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.03284}]],
[1614038356148,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.030928},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.008752}]],
[1614038357150,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.020088},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.008288}]],
[1614038358153,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.031864},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.011456}]],
[1614038359157,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.043264},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.013648}]],
[1614038360159,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.03136},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.024704}]],
[1614038361162,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.03188},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.01168}]],
[1614038362164,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.036736},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.013496}]],
[1614038363166,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.01452},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.003552}]],
[1614038364167,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.050904},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.056992}]],
[1614038365170,
[{'label': 'transmit', 'unit': 'Mbps', 'value': 0.0616},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.04484}]],
[1614038366171,
[{'label': 'transmit', 'unit': 'Mbps', 'value': 0.013},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.003552}]],
[1614038367175,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.018808},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.00828}]],
[1614038368176,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.049784},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.017704}]],
[1614038369179,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.024144},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.006816}]],
[1614038370182,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.031264},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.024744}]],
[1614038371184,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.049832},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.017712}]],
[1614038372186,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.019824},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.00828}]],
[1614038373188,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.014496},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.003552}]],
[1614038374189,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.069472},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.069688}]],
[1614038375192,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.032896},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.024704}]],
[1614038376196,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.01296},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.002736}]],
[1614038377198,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.055576},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.023064}]],
[1614038378203,
[{'label': 'transmit', 'unit': 'Mbps', 'value': 0.013},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.003544}]],
[1614038379206,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.026368},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.00916}]],
[1614038380208,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.067848},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.039432}]],
[1614038381210,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.012984},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.002728}]],
[1614038382212,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.027256},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.007472}]],
[1614038383215,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.042312},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.018304}]],
[1614038384218,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.026576},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.008352}]],
[1614038385222,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.055296},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.075184}]],
[1614038386224,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.04132},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.017512}]],
[1614038387226,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.019176},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.00828}]],
[1614038388228,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.022184},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.002736}]],
[1614038389231,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.060624},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.070728}]],
[1614038390233,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.030376},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.023888}]],
[1614038391235,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.021456},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.002736}]],
[1614038392237,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.042816},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.017712}]],
[1614038393239,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.017944},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.008288}]],
[1614038394242,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.035576},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.011888}]],
[1614038395244,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.06056},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.036952}]],
[1614038396246,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.013472},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.003504}]],
[1614038397249,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.030104},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.005456}]],
[1614038398251,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.038392},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.01972}]],
[1614038399255,
[{'label': 'transmit',
'unit': 'Mbps',
'value': 0.026616},
{'label': 'receive',
'unit': 'Mbps',
'value': 0.008344}]]],
'tags': {},
'type': 'numeric set'}]}
Each item in the results contains a deviceId, name (stream name), tags, type, and points, which is the sequence of datapoints that fell between the start and end timestamps.
Each datapoint is a list with two values: the first is the millisecond UTC unix timestamp of the datapoint, and the second is the datapoint payload.