SgtSmuckers/ProxMon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
ProxMon/README.md
Dan Snyder 34b7048d2f Updated documentation
2025-05-23 18:32:24 -04:00

4.9 KiB
Raw Permalink Blame History

ProxMon

Prometheus exporter that monitors LXC, process and node metrics for Proxmox. This is comprised of two components:

  1. node-exporter
    • Publicly available "node exporter" from Prometheus. This provides a wide range of system metrics, and by default serves metrics on port 9100.
    • Pre-built binary in this repo for ease of installation.
    • Configuration details can be found here.
  2. proxmon
    • Provides supplemental metrics that node-exporter does not provide, and by default serves metrics on port 9101.
    • Metrics include resource usage on a per-LXC and per-process basis.

Also included is a Grafana dashboard tailored to the data exported by both components above.

Installation

  1. Install dependencies needed to build apt install git make gcc
  2. Create a directory for ProxMon to live mkdir /home/monitor NOTE: This does not create a new user. This guide does not include configuring the service to run under a different user, and will by default run it under root. See Customizing Services.
  3. cd /home/monitor
  4. git clone https://git.cozyclan.xyz/dan/ProxMon.git
  5. cd ProxMon
  6. If you wish to configure the services in any way, such as running them as a new user (note on step 2) or editing the port they use, skip the remaining steps and go to the Customizing Services section.
  7. Run make install
  8. Verify services are running: systemctl status node-exporter.service systemctl status proxmon-exporter.service
  9. Congratulations, you're done. Go to the Connecting section.

Customizing Services

The Makefile has various build targets that can be used for finer control over the installation process. A full list of targets can be viewed with make help.

  1. Build proxmon: make build. This will place the executables in the bin/ folder, and generate template service files in the systemd/ directory.
  2. Edit the service files in the systemd/ directory to enable node-exporter features or change the ports of the components. If you would like to run these as non-root users, ask ChatGPT.
  3. Install the service files: make install-services. This will copy the service files from systemd/ into /etc/systemd/system and will start the services in systemd. You can also use make reinstall-services if you have already installed the services and want to install updated versions of the service files.

Running inside an LXC

This is intended to be run on the host system. However, it is probably possible to run it in an LXC. Setting up a privileged LXC would probably be the most straightforward, but an unprivileged should be possible. It would just be annoying to set up because you'd have to map UIDs/GIDs between the LXC and host.

Either way, you will need to bind-mount the hosts root directory into the LXC, and point both node-exporter and proxmon components to read from the bind-mounted directory instead of the default /proc directory of the LXC.

If for instance you bind-mounted the hosts root directory to /host in the LXC, you could add the startup parameter to node-exporter: --path.rootfs=/host And the following startup parameter to proxmon: --path.rootfs /host. See the Customizing Services section.

Connecting

Prometheus

  1. Install Prometheus if you haven't already with the Prometheus Helper Script. Save the web URL displayed at the end of the setup script.
  2. Open your Prometheus LXC console.
  3. Edit the file /etc/prometheus/prometheus.yml
  4. Under scrape_configs add the following job. You can edit the job_name as you wish. Set the IP address in the targets to the IP of the host you wish to scrape data from.
  5. You can also edit the polling rates in the yml file.
scrape_configs:
  - job_name: "node"
    static_configs:
    - targets: ['<HOST_IP>:9100', '<HOST_IP>:9101']
  1. Restart prometheus: systemctl restart prometheus.service

Grafana

  1. Install Grafana if you haven't already with the Grafana Helper Script. Save the web URL displayed at the end of the setup script.
  2. Login to the Grafana web interface provided at the end of the helper script
  3. On the left side, go to Connections->Add new connection.
  4. Search for and click on "Prometheus".
  5. Click Add new data source in the top right.
  6. Under Connection and Prometheus server URL paste in the web URL of your Prometheus server listed at the end of the Prometheus Helper Script.
  7. On the left side, go to Dashboards
  8. In the top right, click New->Import
  9. Copy the contents of Proxmox-Dashboard.json from this git repository, and paste it into the text field.
  10. Click Import