Monitoring outputs

Where the measures of a monitoring profile go, the OML and JSON lines files of the experiment and the live streaming to the IoT-LAB database, and how to read them.

A monitoring profile measures the consumption, the radio and the GPIO events of the nodes. Its outputs tell where the measures go. They are independent, choose one or several:

Output	Where	Rate	Format
`oml` (default, deprecated)	files of the experiment	every measure	OML
`jsonl`	files of the experiment	every measure	JSON lines
`streaming`	IoT-LAB database, 30 days	consumption averaged	Prometheus queries

The OML format is deprecated: prefer jsonl in new profiles. The OML files stay available for the existing profiles and tools, until a date to be announced.

Choose the outputs of a profile

In the web portal, tick them in Outputs of the monitoring profile form.

With the command line tools:

$ iotlab-profile addm3 -n live -current -voltage -power -period 140 -avg 16 \
    -outputs jsonl streaming -stream-period 100

The outputs are set when the experiment starts. Updating the profile of a running node changes the measures, not the outputs.

JSON lines files

Each measure is one line, a JSON object, in the directory of the experiment on the SSH frontend of the site:

Measures	File
Consumption	`~/.iot-lab/<exp_id>/consumption/<node>.jsonl`
Radio (RSSI)	`~/.iot-lab/<exp_id>/radio/<node>.jsonl`
Radio sniffer	`~/.iot-lab/<exp_id>/sniffer/<node>.jsonl`
GPIO events	`~/.iot-lab/<exp_id>/event/<node>.jsonl`

The file of the node m3-1 is m3_1.jsonl. Every line has the time of the measure, in seconds and microseconds, and only the measures of the profile:

{"timestamp_s":1793839256,"timestamp_us":296898,"current":0.0164543502}
{"timestamp_s":1793839256,"timestamp_us":362290,"channel":11,"rssi":-62}
{"timestamp_s":1793839256,"timestamp_us":427681,"channel":11,"rssi":-62,"lqi":108,"crc_ok":true,"length":24}
{"timestamp_s":1793839256,"timestamp_us":493073,"value":1,"name":"gpio2"}

Stream	Fields
consumption	`power` (W), `voltage` (V), `current` (A)
radio	`channel`, `rssi` (dBm)
sniffer	`channel`, `rssi` (dBm), `lqi`, `crc_ok`, `length`
event	`value` (level of the line), `name`

The files are easy to read with any language, for example in Python:

import json

with open("m3_1.jsonl") as measures:
    points = [json.loads(line) for line in measures]
times = [p["timestamp_s"] + p["timestamp_us"] / 1e6 for p in points]
current = [p["current"] for p in points]

Streaming

With the streaming output, the measures reach the IoT-LAB database during the experiment: follow them live, without waiting for the end. The database, VictoriaMetrics, keeps them 30 days. You only see your own measures. The files remain the complete record: when the network or the database is down, streamed measures are lost.

the consumption is averaged over -stream-period, 100 ms by default (the Period of the streaming settings in the web portal); radio measures and events are sent as they come
the packets of the radio sniffer are not streamed: see the live sniffer
50 streaming nodes at most per experiment
by default every measure of the profile is streamed; -streams consumption event selects some of them (consumption, radio, event)

Measure names

The measures of the database are called metrics. Each one has a name, and labels telling where it comes from:

Metric	Unit	Stream
`consumption_current`	A	consumption
`consumption_voltage`	V	consumption
`consumption_power`	W	consumption
`radio_rssi`	dBm	radio
`radio_channel`		radio
`event_value`	level of the line, 0 or 1	GPIO events

Label	Value
`site`	site of the node, `grenoble`
`node`	name of the node, `m3-1`
`archi`	type of the node, `m3`
`exp_id`	experiment id
`user`	your login
`name`	GPIO line of an event, `gpio2`

See the measures in your browser

Open vmui, the interface of VictoriaMetrics, and log in with your IoT-LAB login and password:

type a query in the query field, for example consumption_current{node="m3-1"}, and press Enter
choose the time range at the top right, it must cover your experiment
turn on the auto refresh next to it to follow an experiment live

Write a query

A query is a metric name followed by labels between braces. These examples can be pasted in vmui. Replace 1234 by your experiment id:

You want	Query
all the current of an experiment, one curve per node	`consumption_current{exp_id="1234"}`
one node of an experiment	`consumption_current{exp_id="1234", node="m3-1"}`
several nodes	`consumption_power{exp_id="1234", node=~"m3-1\\|m3-2"}`
the RSSI of a channel	`radio_rssi{exp_id="1234"}`
the events of a line	`event_value{exp_id="1234", name="gpio2"}`
the mean power over a minute	`avg_over_time(consumption_power{exp_id="1234"}[1m])`
the mean power of all the nodes	`avg(consumption_power{exp_id="1234"})`
the events per minute	`count_over_time(event_value{exp_id="1234"}[1m])`
the metrics of your account	`{__name__=~".+"}`

= matches a value, =~ a regular expression. To display a current in mA, multiply it: consumption_current{exp_id="1234"} * 1000. The query language is MetricsQL, compatible with the PromQL of Prometheus.

Fetch the measures from a script

The Prometheus API is available with the same login:

$ API=https://www.iot-lab.info/streaming/select/prometheus/api/v1
# names of your metrics
$ curl -s --compressed -u <login> $API/label/__name__/values
# the last hour of an experiment
$ curl -s --compressed -u <login> -G $API/query \
    --data-urlencode 'query=consumption_current{exp_id="1234"}[1h]'
# every point, one JSON object per series and line
$ curl -s --compressed -u <login> -G $API/export \
    --data-urlencode 'match[]=consumption_current{exp_id="1234"}'

Tools speaking this API, such as Grafana, can use https://www.iot-lab.info/streaming/select/prometheus as a Prometheus data source, with basic authentication.