You can use the Cloud SDK to query telemetry stream data for analysis. Telemetry stream data must be ingested by the Formant agent before it can be queried. For more information on data ingestion, see Data ingestion from a device and Data ingestion from anywhere.
Querying data from the command line
If you want to query data directly from the command line, you'll want to use the
fctltool. For more information onfctl, see Installing and credentialing fctl.
Query syntax and parameters
For a code sample which shows query syntax and relevant parameters, see the following example on our GitHub page: GitHub: query_stream_latest.py.
Required parameters
You'll notice that the query contains start and end parameters. If a query contains only those two parameters, all telemetry datapoints from all devices in your organization whose timestamps fall between start and end will be returned. As seen in the above example, you'll want to use other parameters, such as device ID or tags, to narrow down your query response.
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.
Other parameters
To further narrow down your query, you can use the optional query parameters:
| Query parameter | Usage |
|---|---|
deviceIds | Filter by device ID. |
names | Filter by device name. |
notNames | Exclude devices with this name. |
types | Filter by stream type. For a complete list of stream types, see How telemetry streams work. |
tags | Filter by tags applied to the device. |
Queries can be too large
Your query may be unsuccessful if you request too much data. If this happens, you'll see the following error:
requests.exceptions.HTTPError: 413 Client Error: Payload Too Large for url: https://api.formant.io/v1/queries/queries
Try narrowing your query further by applying more parameters, or by narrowing your time range.
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.