Prometheus Exporter for Klipper

Prometheus exporter for Klipper to capture operational metrics. This is a very rough first implementation and subject to potentially significant changes.

Implementation is based on the Multi-Target Exporter Pattern to enabled a single exporter to collect metrics from multiple Klipper instances. Metrics for the exporter itself are served from the /metrics endpoint and Klipper metrics are serviced from the /probe endpoint with a specified target.

Usage

To start the Prometheus Klipper Exporter from the command line

$ prometheus-klipper-exporter
INFO[0000] Beginning to serve on port :9101             

Then add a Klipper job to the Prometheus configuration file /etc/prometheus/prometheus.yml

scrape_configs:

  - job_name: "klipper"
    scrape_interval: 5s
    metrics_path: /probe
    static_configs:
      - targets: [ 'klipper-host:7125' ]
    params:
      modules: [
        "process_stats",
        "job_queue",
        "system_info",
        "network_stats",
        "directory_info",
        "printer_objects",
        "history",
        "mmu",
      ]
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: klipper-exporter:9101

  # optional exporter metrics
  - job_name: "klipper-exporter"
    scrape_interval: 5s
    metrics_path: /metrics
    static_configs:
      - targets: [ 'klipper-exporter:9101' ]

The exporter can be run on the host running Klipper, or on a separate machine. Replace klipper-host with the hostname or IP address of the Klipper host, and replace klipper-exporter with the hostname or IP address of the host runnging prometheus-klipper-exporter.

To monitor multiple Klipper instances add multiple entries to the static_config.targets for the klipper job. e.g.

    ...
    static_configs:
      - targets: [ 'klipper-host-1:7125', 'klipper-host-2:7125 ]
    ...

If you have have multiple printers manaaged by the same Klipper host then you can use relabeling to differentiate between them. The following example extracts the klipper host name and port as the __param_target, and the printer name following the @ as the printer label.

    static_configs:
      - targets: [ 'klipper-host-1:7125@Ender-3-V2', 'klipper-host-1:7125@Ender-3-Pro']
    ...
    relabel_configs:
      - source_labels: [__address__]
        regex: '(.*)@.*'
        replacement: $1
        target_label: __param_target
      - source_labels: [__address__]
        regex: '.*@(.*)'
        replacement: $1
        target_label: printer
    ...

Build

$ make build

For detailed build, test, and development setup instructions, see the Developers Guide.

A Docker Compose test environment with a virtual Klipper printer, Prometheus, and Grafana is available in the test/ directory.

Installation

You will typically want to install the exporter binary on a host that will be constantly running, either the Klipper host iteself, or a separate server, and ensure that the process restarts on system restart.

systemd

Example installation on Raspberry Pi, using systemd to run the exporter.

$ ssh pi@klipper-host
[klipper]$ mkdir /home/pi/klipper-exporter
[klipper]$ exit

$ scp prometheus-klipper-exporter pi@klipper-host:/home/pi/klipper-exporter
$ scp klipper-exporter.service pi@klipper-host:/home/pi/

$ ssh pi@klipper-host
[klipper]$ sudo mv klipper-exporter.service /etc/systemd/system/
[klipper]$ sudo systemctl daemon-reload
[klipper]$ sudo systemctl enable klipper-exporter.service
[klipper]$ sudo systemctl start klipper-exporter.service
[klipper]$ sudo systemctl status klipper-exporter.service
[klipper]$ exit

docker

To run the exporter as a docker container.

$ docker run -d -p 9101:9101 ghcr.io/scross01/prometheus-klipper-exporter:latest

See the example/README.md for a complete example running Prometheus, Grafana, and the klipper-exporter in Docker using docker compose.

Modules

You can configure different sets of metrics to be collected by including the modules parameter in the prometheus.yml configuration file.

    ...
    params:
      modules: [ "process_stats", "job_queue", "system_info" ]
    ...

If the modules params are omitted then only the default metrics are collected. Each group of metrics is queried from a different Moonraker API endpoint.

Module	Default	Description
server_info	x	Moonraker server version info
process_stats	x	Moonraker process and system CPU/memory
job_queue	x	Job queue length
system_info	x	System CPU count
query_endstops	x	Endstop states
device_power	x	Device power state (e.g. Sambaquis)
network_stats		Network interface traffic and errors
directory_info		Disk usage for gcodes directory
history		Historical print job statistics
printer_objects		Klipper printer object state (temperature, fans, MCU, etc.)
mmu		Happy Hare Multi-Material Unit metrics
cfs		Creality Filament System (CFS) slot and rack metrics
spoolman		Spoolman filament tracking

For a complete list of all exported metrics with types, labels, and descriptions, see the Metrics Reference. For full documentation on configuration, installation, and authentication, see the Guide.

Authentication

Trusted Client

The simplest deployment option is to run the Klipper Exporter on a host that is in the Moonraker trusted clients configuration. This is typically configured by default to include all hosts in the local network. If you have a more restrictive configuration then add the host to the moonraker.conf [authorization] configuration section.

# moonraker.conf

[authorization]
trusted_clients:
  klipper-exporter
  ...

API Key Authentication

Untrusted clients must use an API key to access Moonraker's HTTP APIs. To fetch the current API key run the following on the Klipper host:

$ cd ~/moonraker/scripts
$ ./fetch-apikey.sh
abcdef01234567890123456789012345

The API key can be set in one of three ways, from the scrape job configuraion in prometheus.yml, using the -moonraker-apikey command line argument, or setting the MOONRAKER_APIKEY environment variable.

Environment variable

Set in the MOONRAKER_APIKEY environment variable.

$ export MOONRAKER_APIKEY='abcdef01234567890123456789012345'
$ prometheus-klipper-exporter

Command line argument

Set on the klipper exporter command line using -moonraker.apikey option.

$ prometheus-klipper-exporter -moonraker.apikey='abcdef01234567890123456789012345'

Prometheus scrape configuration

Add the API key to the prometheus.yml scrape config, Add authorization configuration with the type set to APIKEY. The key can either to set directly in the config or referenced from file.

  - job_name: "klipper"
    ...
    authorization:
      type: APIKEY
      credentials: 'abcdef01234567890123456789012345'
      # credentials_file: /path/to/private/apikey.txt
    ...

Only one API key can be set for each job. If you have multiple klipper hosts with different API keys, create a separate job for each host.

Command line options

-help

Display the command line help.

-logging.level <level>

Set the logging output verbosity to one of Trace, Debug, Info, Warning, Error, Fatal and Panic. Default level is Info which will log anything that is info level or above (warning, error, fatal, panic).

Logging level can also be set using the LOGGING_LEVEL environment variable. The command line option takes precedence over the environment setting.

-moonraker.apikey <string>

Set the API Key to authenticate with the Klipper APIs. See API Key Authentication

-web.listen-address [<ip_address>]:<port>

Address on which to expose metrics and web interface. Default is :9101 which will listen on port 9101 on all interfaces, which is the equiviment of 0.0.0.0:9101. Include the IP address to limit to listening on a specific interface, e.g. 192.168.1.99:7070.

⚠️ History of breaking changes

Upgrading to v0.14.0

v0.14.0 removes the deprecated tempurature module option which contained a subset of the metrics reported by the printer_objects. If you where using the tempurature module then switch the configuration to use printer_objects instead.

Upgrading to v0.11.0

v0.11.0 removes the deprecated -debug and -verbose command line options. Use the -logging.level option or LOGGING_LEVEL environment setting instead.

Upgrading to v0.8.0

v0.8.0 deprecates the tempurature module option which contains a subset of the metrics reported by the printer_objects. If you where using the tempurature module then switch the configuration to use printer_objects instead.

Upgrading to v0.7.0

The v0.7.0 release introduces several metric changes that will break any grafana charts that have previously been defined using the old metric names from v0.6.x or earlier.

v0.7.0 now uses labels for network interfaces, temperature sensors, temperature fans, and output pins, rather than defining separate metrics for each unique entity.

These changes affect the following metrics groups

• klipper_network_*
• klipper_temperature_sensor_*
• klipper_temperature_fan_*
• klipper_output_pin_*

For example:

• klipper_network_wlan0_rx_bytes becomes klipper_network_rx_bytes{interface="wlan0"}
• klipper_temperature_sensor_mtu_temperature becomes klipper_temperature_sensor_temperature{probe="mtu"}