View source for Monitoring Using Kwollect

{{Portal|User}}
{{Portal|Tutorial}}
{{TutorialHeader}}

This page describes the monitoring service available in Grid’5000 based on [https://gitlab.inria.fr/grid5000/kwollect Kwollect] to retrieve environmental and performance metrics from nodes.

The service currently provides metrics for:
* Energy consumption from dedicated “wattmetre” devices (currently available for some clusters in Lyon, Grenoble, Nancy)
* Metrics collected from nodes’ Board Management Controller ("BMC": out-of-band management hardware, such as Dell iDRAC), such as ambient temperature, hardware component temperature, energy consumption from PSU, fan speed, etc.
* Traffic collected from network devices
* Energy consumption from PDU, when available
* Node metrics from Prometheus node exporter (and Nvidia DCGM exporter when GPU is available)


= Metrics available =

The list of metrics available for a given Grid’5000 cluster is described in the Reference API, under the “metrics” entry of the cluster description. For instance, to get the list of available metrics for nodes of ''taurus'' cluster, you can use (API requests must be performed from inside Grid'5000 or need to supply authentication credentials):

 $ curl https://api.grid5000.fr/stable/sites/lyon/clusters/taurus | jq .metrics

This returns a list where each element describes a single metric. Most important fields of that description are:
* ''name'': The name identifying the metric
* ''description'': A human-readable description of the metric
* ''labels'' (optional): A “label” that will be used to distinguish two metrics of the same kind, but targeting different objects (e.g. temperature of CPU #1 vs temperature of CPU #2)
* ''period'' and ''optional_period'': The interval (in milli-seconds) under which the metric is collected. The former is the default interval, the latter is the interval used when the metric is activated “on demand” (see below). A metric with ''period'' value at 0 is not collected by default.
* ''only_for'' (optional): When the metric is not available on all nodes of the cluster, the list of nodes where it is available

The full list of metrics is available at the [[Monitoring_Using_Kwollect#Metrics_available_in_Grid.275000|end of this page]].

= Getting metrics values =

The metrics values are stored by Kwollect and available using the Metrology API by performing a GET request with appropriate parameters at URL:

<pre>https://api.grid5000.fr/stable/sites/<site>/metrics</pre>

For instance, to:
* get all metrics collected inside job 1304978 at Lyon:

<pre>curl 'https://api.grid5000.fr/stable/sites/lyon/metrics?job_id=1304978'</pre>

* get all metrics from chifflot-5 and chifflot-6 between 2021-06-08 15:00 and 2021-06-08 17:00:

<pre>curl 'https://api.grid5000.fr/stable/sites/lille/metrics?nodes=chifflot-5,chifflot-6&start_time=2021-06-08T15:00&end_time=2021-06-08T17:00'</pre>

* get all values from Wattmetre for taurus-10, during last 15 minutes:

<pre>curl "https://api.grid5000.fr/stable/sites/lyon/metrics?nodes=taurus-10&metrics=wattmetre_power_watt&start_time=$(date -d '15 min ago' +%s)"</pre>

The request will return a JSON-formatted list of metrics values and their associated timestamp.


For a complete description of parameters and returned fields, see the API specification at: https://api.grid5000.fr/doc/stable/#tag/metrics


'''Important note:''' To avoid overloading Kwollect servers, request size is limited. When too much metrics values are requested, you may hit that limit and receive an error message. In such case, try to reduce the size of your request by selecting less nodes or a shorter time period.


'''Tip''': If you need metrics formatted as CSV, you can use this command line :
 curl <URL_to_request_some_metrics> | jq -r '.[] | [.timestamp, .device_id, .metric_id, .value, .labels|tostring] | @csv'

= On-demand metrics =

Some metrics are not collected by default and must be activated “on-demand”. These metrics have a ''period'' field equal to 0 in their description ([[Monitoring_Using_Kwollect#Metrics available|see above]]).

“On-demand” can be enabled for specific jobs by adding the “-t monitor=<metric_to_enable>” option to oarsub. E.g:

 $ oarsub -I -t monitor=bmc_cpu_temp_celsius

The provided argument can be a regular expression For instance, to enable all metrics related to temperature:

 $ oarsub -I -t monitor='.*temp.*'

To enable all “On-demand” metrics available, the <code>-t monitor</code> option can be used.


'''Note''':

* Dedicated wattmetre devices (metric “wattmetre_power_watt”) are able to perform one measurement every 20 milli-seconds. However, this high frequency is only provided using “on demand” activation. For instance, submit your job using:

 $ oarsub -I -t monitor='wattmetre_power_watt'

By default, only the value averaged over one second is provided.

* As prometheus metrics depend on node characteristics, they cannot be fully described. Only a subset of prometheus metrics will be collected by default (described in the API by the ''prom_default_metrics'' and ''prom_nvgpu_default_metrics'', when relevant). To enable collecting all prometheus metrics, use "on-demand" activation on ''prom_all_metrics'' or ''prom_nvgpu_all_metrics'' (for instance, use <code>monitor='prom_.*'</code>)

* Monitoring of default set of prometheus metrics (''prom_default_metrics'') is enabled for job running the standard environment. For deployed nodes, prometheus monitoring must be activated "on-demand"

= Visualization Dashboard =

A visualization dashboard based on Grafana is available. Metrics can be displayed by job ID or by date and graphics can be updated in real time with new values.

Dashboards are available at:

<pre>https://api.grid5000.fr/stable/sites/<site>/metrics/dashboard</pre>

For instance, at Lyon: https://api.grid5000.fr/stable/sites/lyon/metrics/dashboard

Notes:
* If dashboard's time frame is longer than 30 minutes, some "summarized" values (averaged over 5 minutes) will be displayed instead of the actual values.
* Metrics whose name end by "_total" are displayed as a "per second changing rate".
* When filling a job number, the dashboard's displayed time frame may not be adjusted automatically to the job's begin and end date.
* The list of devices and metrics is retrieved from what's available at the end of the displayed time frame when the dashboard is loaded. If the device or metric you are looking for does not appear, be sure to adjust the time frame to a period where your device or metric exists and force refreshing the lists by reloading the web page from your browser.

= Pushing custom metrics =

A simple mechanism is available to let you push your own, arbitrary, custom metrics to Kwollect (internally it uses [https://github.com/prometheus/node_exporter#textfile-collector Prometheus Node Exporter "Textfile Collector"]). From a node, a custom metric will be collected by writing to a specific file (you currently need ''root'' privileges to do so):

 $ echo 'kwollect_custom{_metric_id="my_metric"} 42' > /var/lib/prometheus/node-exporter/kwollect.prom

This will push a custom metric named ''my_metric'' and with value "42" (this file may contain several lines to push different values at a time).


The associated timestamp will be the time when Kwollect fetches metrics on the node (every 15 seconds under Grid'5000). You may override the timestamp by adding ''_timestamp="your_timestamp_in_unix_seconds"''. For instance:

 $ echo 'kwollect_custom{_metric_id="my_metric", _timestamp="1606389005.1234"} 42' > /var/lib/prometheus/node-exporter/kwollect.prom

(You can also add your own labels. See Prometheus metrics [https://prometheus.io/docs/practices/naming/ naming] and [https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md format] for more information).


Kwollect will continuously pull values from <code>/var/lib/prometheus/node-exporter/kwollect.prom</code> file. It is your responsibility to keep its content updated (for instance, only one value for a particular metric should be present in this file at anytime).

= Known problems =
[[File:Kwollect bmc vs wattmetre.png|thumb|right|Comparison of the power comsumption reported by a BMC vs. a wattmeter.]]

* Metrics from BMC are quite unreliable. They may be inaccurate, highly averaged, or unavailable on some nodes from time to time.
* Some metrics are not available for every nodes of a cluster: For grcinq and hercule clusters, one every four nodes have more metrics available than the others ; on parasilo and paravance clusters, the measurement of the power consumption by PDUs is only available on some nodes, wattmeters are only available on the gros-[41-76] nodes. Such metric have and "only_for" entry in their description indicating nodes where it is available.
* It may happen that few values of a metric are not collected quickly enough to comply with interval described in the Reference API (for instance, when the targeted device is overloaded).
* Electrical consumption reported by PDU is not always reliable, see [[Power_Monitoring_Devices#measurement_artifacts_and_pitfalls]]

= Metrics available in Grid'5000 =

{{:Generated/KwollectMetrics}}