Skip to main content

Prometheus SDK for CircuitPython Express ARM devices

Project description


A Prometheus SDK for CircuitPython/MicroPython boards, allowing sensor data to be integrated into existing Prometheus/Grafana monitoring infrastructure.

  • only depends on socket
  • runs on CircuitPython 4.x for embedded devices
  • runs on CPython 3.x for local testing
  • API compatible with the official prometheus/client_python
  • basic HTTP server with path/method routing
  • not terribly slow (wrk reports upwards of 10 rps with routing)

For those unfamiliar with Prometheus, the examples expose an HTTP server on port :8080 that reports metrics in a plaintext format:

# HELP prom_express_gas gas from the bme680 sensor
# TYPE prom_express_gas gauge
prom_express_gas 1060948
# HELP prom_express_humidity humidity from both sensors
# TYPE prom_express_humidity gauge
prom_express_humidity{sensor="None"} 0
prom_express_humidity{sensor="bme680"} 49.4062
prom_express_humidity{sensor="si7021"} 49.7976
# HELP prom_express_pressure pressure from the bme680 sensor
# TYPE prom_express_pressure gauge
prom_express_pressure 983.25
# HELP prom_express_temperature temperature from both sensors
# TYPE prom_express_temperature gauge
prom_express_temperature{sensor="None"} 0
prom_express_temperature{sensor="bme680"} 24.7359
prom_express_temperature{sensor="si7021"} 24.3325



Pipeline Status Test Coverage MIT license

Open bug count Open issue count Closed issue count

Maintainability Technical debt ratio Quality issues LGTM Language grade: Python LGTM Total alerts


github release link github release version github commits since release

PyPI release link PyPI release version

Supported Hardware

This library is developed for the Adafruit Feather M4 Express running MicroPython 4.1.0 or better, with an Adafruit Ethernet FeatherWing attached.

Supported Features


This module implements a very rudimentary HTTP server that likely violates some part of the spec. However, it works with Chrome, curl, and Prometheus itself.


Labels are stored and used to accumulate values. Missing labels are reported as None.

Metric Types

Counter, Gauge, and Summary are implemented with labels.


Incremental values. Implements inc(value) and dec(value).


Absolute values. Extends counter with set(value).


Individual values. Prints count and total of observe(value).


Registries may be created with a namespace: CollectorRegistry(namespace='foo')

Call registry.render() to format metrics in Prometheus' plain text exposition format:

# HELP prom_express_test_counter a test counter
# TYPE prom_express_test_counter counter
prom_express_test_counter 1588
# HELP prom_express_test_gauge a test gauge
# TYPE prom_express_test_gauge gauge
prom_express_test_gauge 3887

Metrics may be registered with multiple registries.

Planned Features

  • push support: push_to_gateway
  • remaining metric types: Histogram
  • tests for API compatibility

Known Issues

Load Causes OSError

Load testing the HTTP endpoint may cause one of a variety of OSErrors, often errno 3, 4, or 7.

Not sure what is causing the errors, but it is not predictable and may not appear immediately:

> ./wrk -c 1 -d 60s -t 1 http://server:8080/
Running 1m test @ http://server:8080/
  1 threads and 1 connections
    Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     8.64ms  485.57us  12.81ms   97.75%
    Req/Sec   111.60      5.21   121.00     71.00%
  2222 requests in 20.61s, 671.83KB read
  Socket errors: connect 0, read 1, write 2743, timeout 0
Requests/sec:    107.82
Transfer/sec:     32.60KB

Some are fatal:

Connection from ('client', 8080)
Connection from ('client', 8080)
Error accepting request: [Errno 128] ENOTCONN
Binding: server:8080
Traceback (most recent call last):
  File "", line 90, in <module>
  File "", line 87, in main
  File "", line 87, in main
  File "", line 55, in bind
  File "/lib/prometheus_express/", line 11, in start_http_server
OSError: 4

Others require the socket to be rebound:

Connection from ('client', 8080)
Error accepting request: 7
Binding: server:8080

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

prometheus_express-0.0.4.tar.gz (6.9 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page