HUB
Sign inSign up

blackbush/bambulab_metrics_exporter

By blackbush

•Updated 43 minutes ago

Prometheus exporter for Bambu Lab 3D printers (LAN or Bambu Cloud), with a Grafana dashboard

Image
0

6.4K

blackbush/bambulab_metrics_exporter repository overview

bambulab_metrics_exporter

Not affiliated with Bambu Lab.

⁠bambulab_metrics_exporter

Python 3.11 GitHub Release Docker Publish GHCR Package GHCR Pulls Docker Hub Pulls Grafana Dashboard Downloads Ko-fi

A Prometheus exporter for Bambu Lab 3D printers. It runs as a small Docker container, reads your printer's live status on your home network or through Bambu Cloud, and publishes it for Prometheus⁠ to collect and Grafana⁠ to chart: prints, temperatures, fans, AMS filament, errors and firmware, with history and alerts. It only reads; it never controls the printer.

Grafana dashboard: printer status, print progress, temperatures, AMS and trends

The ready-made Grafana dashboard (grafana.com ID 25033) with an H2D. Your dashboard shows your own printers.

Full documentation is in the wiki⁠.

⁠Contents


⁠Supported printers

SeriesModelsTested on real hardware
AA1, A1 mini, A2L
PP1P, P1S, P2S
XX1, X1 Carbon, X1E, X2DX1 Carbon
HH2C, H2D, H2D Pro, H2S, H3CH2D (idle and printing)

AMS units: AMS, AMS Lite, AMS 2 Pro, AMS HT and AMS 3H, plus the external spool.

Every model in the table is recognized, and the exporter leaves out metrics for hardware a model does not have (for example the chamber heater on a P1S). Models not yet tested on real hardware are recognized from their data and may report some values differently. The Metrics Reference⁠ lists what each model has.

Own a model that is not tested yet, or one marked "Unsupported printer"? Open the exporter's Diagnostics page and click Create GitHub issue. It sends a report with serial numbers, addresses, names and credentials removed, so the model can be checked or added.


⁠How it works

Printer (LAN or Bambu Cloud)  ->  exporter :9109/metrics  ->  Prometheus  ->  Grafana

Bambu Lab printers publish their state over MQTT. The exporter listens to that feed, asks for a full update every 10 seconds, and turns it into Prometheus metrics.

ConnectionWhat you provideGood to know
Local (LAN)Printer IP address, serial number and LAN access code (on the printer: Settings, Network)Talks to the printer directly; no Bambu Cloud account needed
Bambu CloudYour Bambu Lab account email and the code it emails you, then tick the printers to monitorNo IP or access code needed; the login renews itself and is stored encrypted

You set up both in your browser on the exporter's Printer Connection page (/auth), and you can mix them: one exporter monitors up to 32 printers.


⁠Features

⁠Printer status

Connection, state and stage, HMS errors by severity, door and top lid, lights, camera, Wi-Fi or wired network, SD card or USB drive, mounted tool head and accessories, firmware versions and available updates.

⁠Print progress

Percent, layers, time left, stage countdown, job source, file download progress, skipped objects and fail reason.

⁠Temperatures and fans

Nozzle (per extruder, and the active one on dual-nozzle printers), bed and chamber with their targets, every fan, and the airduct mode.

⁠AMS and filament

AMS model and status, filament type, color and remaining amount per slot, humidity and temperature, and drying (time left, target, phase and why drying cannot start). On the AMS 3H these are per zone.

⁠Extruders and nozzles

Filament change steps, filament sensors and buffer, nozzle type, diameter and wear, and the hotend rack on the H2C and H3C.

⁠Built for homelabs
  • Easy setup: connect printers in the browser; settings are stored encrypted and survive restarts.
  • Model aware: detects the model and skips hardware it does not have.
  • Diagnostics: a built-in page builds a sanitized report and opens a prefilled GitHub issue.
  • Read-only: never sends control commands to the printer.
  • Ready to use: Grafana dashboard, Prometheus alert and recording rules, and an Unraid template.

⁠Quick start

You need a machine that runs Docker, and Prometheus and Grafana to store and chart the data.

  1. Create a secret key once and keep it safe. It encrypts the saved printer settings and cloud login:

    openssl rand -hex 32
    
  2. Start the container:

    docker run -d \
      --name bambulab-exporter \
      --restart unless-stopped \
      -p 9109:9109 \
      -v /path/to/config:/config/bambulab-metrics-exporter \
      -e BAMBULAB_SECRET_KEY=<your-secret-key> \
      ghcr.io/theblackbush/bambulab_metrics_exporter:latest
    
  3. Open http://<your-server-ip>:9109/auth, choose Local or Bambu Cloud, and connect. No restart is needed.

  4. Add <your-server-ip>:9109 as a Prometheus scrape target (keep bambulab in the job name) and import Grafana dashboard 25033.

The image is also on Docker Hub as blackbush/bambulab_metrics_exporter, and an Unraid template is available. Docker Compose, Unraid and environment-variable setup are in the wiki: Quick Start⁠ and Installation⁠.

The exporter's pages have no password of their own. Keep port 9109 on your home network.


⁠Grafana dashboard

BambuLab Metrics⁠ on grafana.com (ID 25033), also in examples/grafana/⁠:

RowWhat it shows
Printer StatusConnection, model, state, errors, door, lid, lights, AI features, tool head, accessories
Print ProgressStage, time left, progress, layers, job name, speed, fail reason
TemperaturesNozzle, bed and chamber gauges scaled to the model, fans and trends
Extruders & NozzlesPer-extruder status, active nozzle, nozzle wear
AMSSpool cards with real filament colors, humidity, temperature, drying, AMS 3H zones
Airduct, Health & TrendsAirduct fans, HMS errors, firmware per module, connection and Wi-Fi history

Use the Job and Printer dropdowns to switch printers. The AMS spool cards need the free Business Text plugin; see the Grafana Dashboard⁠ guide.


⁠Documentation

PageWhat it covers
Quick Start⁠Step-by-step setup and the /auth connection page
Installation⁠Docker, Docker Compose, Unraid and environment-variable setup
Configuration⁠Every environment variable
Prometheus Setup⁠Scrape config, alert and recording rules
Grafana Dashboard⁠Import steps and panels
Metrics Reference⁠Every metric, per-model support and PromQL examples
Troubleshooting⁠Common problems and fixes
Diagnostic Report⁠The report to send with issues for new printers, metrics or fixes

How the exporter works in detail and its known limitations are on the wiki home page⁠. Release notes are in CHANGELOG.md⁠, and examples (dashboard JSON, Prometheus rules, sample output) in examples/⁠.


⁠Help and feedback

  • Something wrong or missing? Run the Diagnostics page and click Create GitHub issue, or open an issue⁠ yourself. The Troubleshooting⁠ page covers the common problems.
  • Running several printers in one exporter? This has only been tested with simulated printers, so feedback is very welcome: tell us your printer models and whether they use cloud or LAN.

⁠Development

The project ships as a Docker image only (no PyPI package). To run the tests:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt && .venv/bin/python -m pip install -e .
make test   # full suite with coverage gate
make lint

To build the image locally: docker build -t bambulab-metrics-exporter:latest .

⁠License

GPL-3.0⁠

Tag summary

Content type

Image

Digest

sha256:a6fb5465e…

Size

66.9 MB

Last updated

11 days ago

docker pull blackbush/bambulab_metrics_exporter