bambulab-metrics-exporter

Production-oriented Prometheus exporter for Bambu Lab printers (homelab/self-hosted friendly).

Note: Development and real-world validation of this exporter are currently done only on an X1C printer. If you want to help improve support for additional printer models, please get in touch with me via GitHub.

Docs / Wiki

Full operator documentation lives in the GitHub Wiki.

Table of contents

• What this does
• Quick start
• Local mode vs Cloud mode
• Cloud authentication
• Environment variables
• Docker
• Prometheus integration
• Operator PromQL examples
• Exported metrics (core)
• Testing
• Known limitations

What this does

• Connects to Bambu printer over LAN MQTT (default) or Cloud MQTT
• Periodically requests a full state snapshot (pushall)
• Parses print state/telemetry into stable Prometheus metrics
• Exposes:
  • GET / — landing page with version and status
  • GET /metrics
  • GET /health
  • GET /ready

Implementation notes

• Supports both LAN MQTT (local_mqtt) and Cloud MQTT (cloud_mqtt).
• Uses device/<serial>/report and device/<serial>/request topics.
• Requests full snapshots with pushall and maps stable telemetry fields to Prometheus metrics.
• Printer model detection uses a table-driven resolver pipeline (product_name → hw_ver+project_name → SN prefix → legacy fallbacks), including newer SN prefixes such as 22E (P2S), 093 (H2S), and 094 (H2D).

Deployment: This project is deployed via Docker. There is no pip/PyPI distribution. See Installation for full setup instructions.

Quick start

# Pull and run (Local mode — printer must be on same LAN)
docker run -d \
  --name bambulab-exporter \
  -p 9109:9109 \
  -e BAMBULAB_HOST=192.168.1.100 \
  -e BAMBULAB_SERIAL=01P00A000000000 \
  -e BAMBULAB_ACCESS_CODE=12345678 \
  ghcr.io/theblackbush/bambulab_metrics_exporter:latest

Or with an env file:

cp .env.example .env
# edit .env with your values
docker run -d --name bambulab-exporter -p 9109:9109 --env-file .env \
  ghcr.io/theblackbush/bambulab_metrics_exporter:latest

Then verify:

curl http://localhost:9109/health
curl http://localhost:9109/metrics | grep bambulab_printer_connected

For a step-by-step walkthrough see Quick Start in the Wiki.

Local mode vs Cloud mode

The exporter supports two transport modes. local_mqtt is the default — no extra configuration needed if your printer is on the same LAN.

Local mode — required vars:

BAMBULAB_HOST=192.168.1.100
BAMBULAB_SERIAL=01P00A000000000
BAMBULAB_ACCESS_CODE=12345678

Cloud mode — required vars:

BAMBULAB_TRANSPORT=cloud_mqtt
BAMBULAB_SERIAL=01P00A000000000
BAMBULAB_SECRET_KEY=<openssl rand -hex 32>
BAMBULAB_CLOUD_EMAIL=you@example.com

See Configuration for the full variable reference.

Cloud authentication

Cloud credentials are obtained via the bambulab-cloud-auth CLI bundled in the container image. No local Python installation is required.

Container-native OTP flow (recommended)

1. Set BAMBULAB_CLOUD_EMAIL in your .env. Do not set BAMBULAB_CLOUD_CODE yet.
2. Start the container. It detects no valid credentials, sends a verification code to your Bambu account email, and exits.
3. Check your email for the code.
4. Add BAMBULAB_CLOUD_CODE=<code> to .env and restart the container.
5. The container authenticates, stores encrypted credentials to the config volume, and starts normally.
6. Remove BAMBULAB_CLOUD_CODE from .env — codes are single-use; it is not needed for normal operation.

On every subsequent restart, stored credentials are loaded automatically.

BAMBULAB_CLOUD_CODE lifecycle

BAMBULAB_CLOUD_CODE is a one-time bootstrap variable. It is needed again only if:

• Stored credentials are missing or cleared (fresh config volume, accidental deletion).
• The Bambu Cloud session expired or account password changed.
• BAMBULAB_SECRET_KEY was changed — the encrypted credential file can no longer be decrypted.

In any of these cases, start the container without BAMBULAB_CLOUD_CODE to trigger a new code delivery, then follow steps 3–6 above.

For the manual bambulab-cloud-auth flow and full credential lifecycle details, see Installation and Quick Start.

Environment variables

Full reference including PUID/PGID/UMASK and advanced options: Configuration.

Docker

GHCR pre-built image (recommended)

docker run -d --name bambulab-exporter -p 9109:9109 --env-file .env \
  ghcr.io/theblackbush/bambulab_metrics_exporter:latest

Docker Compose

docker compose up -d

The included docker-compose.yml is cloud-first and minimal by default. Required cloud fields are active; optional fields are commented with inline hints. Works for Linux hosts and Unraid (PUID/PGID/UMASK optional).

Build locally

docker build -t bambulab-metrics-exporter:latest .
docker run -d --name bambulab-exporter -p 9109:9109 --env-file .env \
  bambulab-metrics-exporter:latest

Unraid

A ready-to-import template is included: unraid-bambulab-metrics-exporter.xml

1. Docker → Add Container → Template — paste XML content or use Template URL.
2. Fill in BAMBULAB_SECRET_KEY and required transport fields.
3. Start container and verify /metrics.

See Installation for full Unraid and PUID/PGID setup.

Prometheus integration

Use examples/prometheus/prometheus.scrape.yml snippet, or equivalent:

scrape_configs:
  - job_name: bambulab
    scrape_interval: 15s
    metrics_path: /metrics
    static_configs:
      - targets: ["bambulab-metrics-exporter:9109"]

See Prometheus Setup for full scrape config, alerting rules, and recording rules.

Operator PromQL examples

AMS metrics

• Average humidity index per AMS unit over 15 minutes:

avg_over_time(bambulab_ams_unit_humidity_index{printer_name="$printer"}[15m])

• Lowest remaining filament percentage per printer (all AMS slots):

min by (printer_name) (bambulab_ams_slot_remaining_percent)

• Slots below 15% remaining filament:

bambulab_ams_slot_remaining_percent{printer_name="$printer"} < 15

Alert tuning examples

• Door open while printing, less sensitive (require 2 minutes open):

bambulab_door_open{printer_name="$printer"} == 1
and on(printer_name, serial)
bambulab_printer_gcode_state{printer_name="$printer", state="RUNNING"} == 1

Suggested alert rule tuning:

for: 2m
labels:
  severity: warning

• Stale exporter threshold tuned for slower polling environments:

time() - bambulab_exporter_last_success_unixtime{printer_name="$printer"} > 300

Suggested alert rule tuning:

for: 2m
labels:
  severity: warning

• SD card abnormal status:

bambulab_sdcard_status_info{printer_name="$printer", status="abnormal"} == 1

More PromQL examples and alert rules: Metrics Reference and Grafana Dashboard.

Exported metrics (core)

All metrics include stable labels:

• printer_name (from PRINTER_NAME_LABEL or BAMBULAB_PRINTER_NAME)
• serial (from BAMBULAB_SERIAL)

Migration note (stage metrics)

• bambulab_mc_print_stage_state{stage} was removed.
• Use bambulab_print_stage_info{stage} for stage labels and bambulab_stg_cur for numeric stage IDs.

Testing

pip install -r requirements-dev.txt
# or: pip install -e .[dev]
pytest --cov=src --cov-report=term-missing

Maintaining >90% test coverage for core modules.

Test command profiles

make test              # full suite with coverage gate
make test-unit         # unit suite with coverage gate
make test-integration  # integration-only (runs with --no-cov)
make test-e2e          # e2e-only (runs with --no-cov)
make test-profile      # deterministic smoke profile (integration + e2e)

Why --no-cov for integration/e2e-only runs? The project enforces a global coverage threshold in default pytest options, so subset-only runs use --no-cov to avoid false negatives unrelated to test correctness.

Sample payload and expected metrics

• MQTT sample payload: examples/sample_mqtt_message.json
• Sample metrics excerpt: examples/sample_metrics.prom

These are useful for quick regression checks and dashboard/query validation.

Known limitations

1. Cloud mode requires a valid access token (a helper tool is included for obtaining it).
2. TLS cert verification is disabled in both LAN/cloud MQTT paths for compatibility with current broker behavior.
3. Some firmware fields can be missing or model-specific; exporter degrades gracefully (NaN for missing scalar values).

Future enhancements

• Automatic access-token refresh using refresh token
• Optional job-name metric via controlled allow-listing (avoid cardinality issues)
• Better fan mapping per model/firmware
• Integration tests with recorded MQTT fixtures

Dashboard Preview

The dashboard is available on the Grafana.com dashboard listing.