Skip to content

Add Prometheus metrics exporter and API docs#1697

Open
trcjr wants to merge 7 commits into
bitaxeorg:masterfrom
trcjr:add-prometheus-metrics
Open

Add Prometheus metrics exporter and API docs#1697
trcjr wants to merge 7 commits into
bitaxeorg:masterfrom
trcjr:add-prometheus-metrics

Conversation

@trcjr
Copy link
Copy Markdown

@trcjr trcjr commented May 20, 2026

Add Prometheus metrics exporter (/api/system/metrics)

Summary

Adds a new HTTP endpoint GET /api/system/metrics that exposes ESP-Miner telemetry in Prometheus text exposition format, enabling direct scraping by Prometheus or compatible monitoring tools (Grafana, VictoriaMetrics, etc.).

A Grafana dashboard JSON (dashboard.json) is included for quick visualization.

Changes

  • main/http_server/http_server.c — Implements the /api/system/metrics handler with:
    • Safe label-value escaping (", \, newlines, non-printable chars)
    • Full metric families for device info, uptime, heap, WiFi, hashrate, shares, pool, fans, temperatures, power, and frequency
    • Human-readable reset reason strings from esp_reset_reason_t
  • main/http_server/openapi.yaml — Adds the GET /api/system/metrics path and PrometheusMetrics schema component
  • main/http_server/axe-os/README.md — Documents the endpoint, example curl usage, example output, and the full list of metric families
  • dashboard.json — Grafana dashboard for visualizing all exported metrics

Exposed metrics

Metric Type Description
espminer_build_info gauge Build/device info labels (firmware, model, ASIC, board, hostname)
espminer_uptime_seconds gauge Device uptime
espminer_heap_free_bytes gauge Current free heap
espminer_heap_min_free_bytes gauge Minimum free heap since boot
espminer_wifi_rssi_dbm gauge WiFi signal strength
espminer_wifi_connected gauge WiFi connection state (0/1)
espminer_hashrate_hashes_per_second gauge Current hashrate
espminer_shares_accepted_total counter Accepted shares
espminer_shares_rejected_total counter Rejected shares
espminer_jobs_received_total counter Mining jobs received
espminer_best_share gauge Best share difficulty
espminer_pool_connected gauge Pool connection state (0/1)
espminer_mining_enabled gauge Mining enabled state (0/1)
espminer_fan_rpm / espminer_fan2_rpm gauge Fan speeds
espminer_chip_temp_celsius / espminer_vr_temp_celsius gauge Temperatures
espminer_voltage_volts gauge Input voltage
espminer_frequency_hz gauge ASIC frequency
espminer_power_watts gauge Power draw
espminer_current_amps gauge Current draw

Example usage

curl http://<device_ip>/api/system/metrics
# HELP espminer_uptime_seconds Device uptime in seconds
# TYPE espminer_uptime_seconds gauge
espminer_uptime_seconds 12345.67
# HELP espminer_hashrate_hashes_per_second Current hashrate
# TYPE espminer_hashrate_hashes_per_second gauge
espminer_hashrate_hashes_per_second 123.4

Testing

Scrape the endpoint with curl or point Prometheus at http://<device_ip>/api/system/metrics. Import dashboard.json into Grafana for a ready-made dashboard.

@mutatrum
Copy link
Copy Markdown
Collaborator

mutatrum commented May 20, 2026

Can you add a screenshot of the dashboard?

@mutatrum mutatrum added the enhancement New feature or request label May 21, 2026
@trcjr
Copy link
Copy Markdown
Author

trcjr commented May 21, 2026

Current dashboard, I'm open to changing it. I wasn't really sure what I wanted to see and was hoping it would make more sense as I saw more data.

bitaxe-grafana-dashboard

12hr look back
bitaxe-grafana-dashboard-12hr

@0xf0xx0 0xf0xx0 self-requested a review May 21, 2026 23:29
@0xf0xx0
Copy link
Copy Markdown
Collaborator

0xf0xx0 commented May 21, 2026

will look over in the next week or so

0xf0xx0
0xf0xx0 requested changes May 24, 2026
View reviewed changes
Copy link
Copy Markdown
Collaborator

@0xf0xx0 0xf0xx0 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

playin with the dashboard, we'll have to be sure the uid keys are removed so importing works as its using the uid of your prometheus

Comment thread main/http_server/http_server.c Outdated
Comment thread main/http_server/http_server.c Outdated
Comment thread main/http_server/http_server.c Outdated
Comment thread main/http_server/http_server.c Outdated
Comment thread main/http_server/http_server.c Outdated
trcjr added 2 commits May 24, 2026 19:15
@trcjr
Address PR review feedback for Prometheus metrics
404d953 
- remove duplicate mining_enabled metric (keep mining_paused)

- emit fan2/chip_temp2 metrics only on supported hardware

- broaden label sanitization for wifi/rejected-reason labels

- remove hardcoded Grafana datasource uid for portable dashboard imports

- update OpenAPI/README docs to match metric behavior
@trcjr
Use labeled per-device fan/chip metrics
63b48c0 
- export espminer_fan_rpm as fan=1|2 series based on detected hardware

- export espminer_chip_temp_celsius as chip=1|2 series based on detected sensors

- update dashboard queries to new labeled metric model

- keep OpenAPI and README metric docs in sync
@0xf0xx0
Copy link
Copy Markdown
Collaborator

0xf0xx0 commented May 25, 2026

somethin in latest commits seems to have broken metrics for me

trcjr added 3 commits May 26, 2026 12:59
@trcjr
Fix Prometheus label braces regression in fan/chip metrics
3b595ac 
- prometheus_format_label() is an internal helper that intentionally omits

  the surrounding {} braces; it must not be called by metric emitters directly.

- The fan/chip labeled metric code introduced in 63b48c0 incorrectly used

  prometheus_format_label() instead of prometheus_format_labels(), producing

  malformed output: espminer_fan_rpmfan="1" 4032

- Switch all 4 call sites to prometheus_format_labels() (count=1) so output

  is valid Prometheus text exposition: espminer_fan_rpm{fan="1"} 4032

- Extract the four prometheus formatting helpers into a standalone

  components/prometheus_format/ component so they can be unit-tested

  without bringing in the full HTTP-server context.

- Add Unity test suite covering: no-label, single-label, multi-label,

  board-601 fan RPM, board-601 chip-temp, and a regression guard that

  asserts the label string always starts with '{' and ends with '}'.

- Include prometheus_format in test/CMakeLists.txt TEST_COMPONENTS.

Voltage/current unit note (not fixed here): Power_get_input_voltage() returns

TPS546_get_vin()*1000 (mV), and Power_get_output() returns iout*1000 (mA),

but both are emitted as espminer_voltage_volts / espminer_current_amps.

This is a pre-existing inconsistency that warrants a separate investigation.
@trcjr
Add CMake registration for prometheus formatter tests
b68854d 
Fixes test project build by registering components/prometheus_format/test as an IDF test component.

Required for compiling the new label-format regression tests in test/.
@trcjr
Address PR feedback: remove dashboard UIDs and narrow label sanitization
a7ab983 
Drop Grafana UID fields from dashboard.json so imports are portable across instances.

Limit build_info sanitization in /api/system/metrics to hostname only, per review guidance.
@0xf0xx0
Copy link
Copy Markdown
Collaborator

0xf0xx0 commented May 29, 2026

functionality wise, acked, this is a good feat :3
what do you think about having 2 dashboards, one with cards showing all the tracked datapoints and the other cut-down?

@mutatrum
Copy link
Copy Markdown
Collaborator

mutatrum commented May 29, 2026

Can I propose to have the dashboards in a separate repository?

@mutatrum mutatrum added this to the 2.15.0 milestone May 29, 2026
@0xf0xx0
Copy link
Copy Markdown
Collaborator

0xf0xx0 commented May 29, 2026

would a separate repo be necessary? its not like theyll be updated very often, theyre just examples

@trcjr
Copy link
Copy Markdown
Author

trcjr commented May 30, 2026

functionality wise, acked, this is a good feat :3 what do you think about having 2 dashboards, one with cards showing all the tracked datapoints and the other cut-down?

I'm open to suggestions. It seems people are interested in different bits of the metrics.

@0xf0xx0
Copy link
Copy Markdown
Collaborator

0xf0xx0 commented May 31, 2026

workin on somethin...
image

also, if you could make a contrib/ dir and move the dashboard there thatd be great uwu

@0xf0xx0
Copy link
Copy Markdown
Collaborator

0xf0xx0 commented May 31, 2026

ok, final nit from me is i think the _online metric should be removed as it'd always be 1.

@0xf0xx0
Copy link
Copy Markdown
Collaborator

0xf0xx0 commented May 31, 2026 •
edited
Loading

also, give this dashboard a whirl: Bitaxe Quick Overview-1780267367205.json

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@0xf0xx0 0xf0xx0 0xf0xx0 requested changes

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

enhancement New feature or request

Projects

None yet

Milestone

2.15.0

Development

Successfully merging this pull request may close these issues.

3 participants

@trcjr @mutatrum @0xf0xx0