Prometheus Dasboards on ESP32

I work in IT, using Prometheus for more than 10 Years already, and of course, I use Grafana to create nice and colorful dashboards. In our offices, we used to set some big monitors or TV in the walls playing the dashboards with the most important metrics.

Very nice, if you are in the office, with a lot of space.... but is different when you are in smart working.Likely, you have only a desk available and that is all the space you can allocate to the job. What if I tell you there is a different option ?

Small screen, inexpensive device and very low power consumption, this is what makes sense to have at home.

The library I'm proposing works on ESP32 devices on Arduino IDE, generate images of your metrics in 3 different formats: Time series Graph, Gauge and Simple Stat. You need to provide the metrics and push the image into your screen in the layout you define. I attached as the example 3 different demos: 1 Simple with only one metric running on a tiny screen (M5AtomS3) and 2 full demo running on bigger screen, loading the config from SD card. Will push the demo firmware into M5Burner, so if you have a compatible device, you don't need to compile the code.

Hardware required

You can use any board powered by ESP32, better, but not mandatory, with PSRAM. Initially, it was supporting also Arduino Giga, which is temporarily disabled, and it will be added again later in a future release along with more architectures.As I own several M5Stack devices, I tested the code in almost all of them, attached on the library you can find the examples for M5Tab5, M5CoreS3 and AtomS3. Using the M5Unified library allow extending the demo to any M5Stack device with a display. You can of course build your own device, adding the battery if required, a buzzer to ring when metrics are deviating, and a Display as big as you need. Maybe you want some button to navigate on the metrics if you don't have a touch screen, or even a servo motor to raise a red flag on alert.Will not give any hint or layout, it depends on your need and your budget.

How to install the library

From my repo, download the Zip file and then, on the Arduino IDE, from Sketch->Include Library -> add.Zip Library

Once you select the right Zip file, you will see my 3 examples

How to use the examples provided:

M5AtomS3_simple

This simple example is generated for M5AtomS3, but can work with minimal change in any device, as it uses LovyanGFX library to manage the screen and push the image. first, you need to set Wi-Fi and Prometheus target

// WiFi credentials
const char* ssid = "< YOUR SSID >";
const char* password = "< YOUR PASSWORD >";
// Prometheus settings
char* prometheushost = "192.168.2.8";  // <- My Raspberry PI
int prometheusport = 9090;

Then next step is to customize the metrics you want to scrape

c1.setMetric("100*avg(rate(node_cpu_seconds_total{mode='user'}[1m]))");
c1.setTitle("Cpu util - %");
c1.setThr1(50);   // Warning Threshold 
c1.setThr2(75);   // Critical Threshold
c1.enableThr(true);  // Enable Threshold Visualization

Once configured that part, you can build and deploy on the device. After connecting to the Wi-Fi, in one second you should see the graph, which in this example is a time series.

CoreS3_from_SD and M5Tab5_from_SD

The 2 examples mentioned differs only from the number of metrics you can visualize concurrently on screen, having the display different size, but the procedure is the same. Get a small SD card, max 8GB to be sure, and copy on it all files from the folder SD in my code. Rename the config_M5CoreS3.txt or config_M5Tab5.txt (depending on your device) into config.txt

In that file, you have a global section for Wi-Fi and Prometheus Server, which need to be customized to make the demo working, and then 5 or 9 sections for the different images. Let's check

ssid=<YOUR SSID>
password=<YOUR PASSWORD>
prometheushost=< YOUR SERVER >
prometheusport=9090
enablehttps=0

#Metric
0_metric=100*avg(rate(node_cpu_seconds_total{mode='user'}[1m]))    

# Title of the panel 
0_title=Cpu utilization

#Type: 0 = Gauge, 1 = Stats, 2 = Time Series 
0_type=1

# Width of The image
0_w=250

# Height of the image 
0_h=300

# Starting points ( x and Y ) of te top left corner or the image on screen 
0_x=0
0_y=50

# Threshold for Warning 
0_thr1=50

#Threshold for Critical
0_thr2=80

# Enable threshold Visualization
0_enableThr=1

# Enable trend visualization
0_enableTrend=0

# Timerange (seconds) of the metrics collected
0_timerange=3600

You can change any of the image, except the last one (5_ or 9_), which is used only as virtual zoom: when you touch one panel, the device will show you only that panel in full screen, which is actually the last image as big as the screen showing the same metric. The PNG images are used during the boot and on normal usage. The M5Tab5, on the right bottom corner will show one of normal.png, warning.png or critical.png according to the max alert we have. You can customize that images to display your logo or anything you want. After putting the SD card on the device and building the code, the device will boot showing the loading icon, then Wi-Fi not connected and finally Wi-Fi connected. After a few seconds, you will see the dashboard. You can change the layout as you prefer, by just editing the config.txt.

HTTPS endpoints and authentication

The library can connect to HTTPS and authenticated endpoints, like Grafana cloud. Is not included in the demo, will do on the next release. Take a look at this setup:

myBuffer10 = c10.init(w10, h10);
c10.setMetric("heap_free_bytes/1000");
c10.setTitle("Free mem KB - Grafana Cloud ");
c10.setHttps(true);
c10.setCredentials("1234567", "glc_your_beatiful_token_able_to_read");
c10.setHost("prometheus-1234-prod-eu-west-2.grafana.net", 443);
c10.setURI("/api/prom/api/v1/query_range");
c10.setThr1(215);
c10.setThr2(235);
c10.enableThr(true);

The main difference from other examples is the method setHttps(true) and setCredentials("username", "password").

If you have Prometheus on Kubernetes, you may require HTTPS but not authentication, while other servers may require authentication.

If you use Grafana Cloud, the username is provided by the console, while the password is an API Token created with permissions to read metrics. Check on Grafana Cloud documentation for more details

API reference

I documented all the options on API Reference

Future improvement

As mentioned, the first step will be adding support again for Arduino Giga and other boards from the Arduino family. The annoying part is the different approach on HTTPS from the different architecture.

I would like also to include support for black and white devices, like mini OLED or E-Ink.

The last planned improvement is to extend the time series panel to add multiple series on the same panel.Let me know, any hint is welcomed.

For the Demo, as the refresh of the metrics when I'm using the bigger screen requires more than one second, I would like to use tasks to not block the main look if I'm using the touch. On the Demo video, we see sometime I need to touch again the screen when the CPU is busy refreshing