From 4dc5bb1bd8ab5c09dabf34287f4089445040e343 Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Fri, 11 Mar 2022 12:39:25 +0100 Subject: [PATCH] docs: refactor usage section and add label description (#170) --- .dictionary | 6 +- README.md | 2 +- docs/.hugo_build.lock | 0 docs/config.yaml | 2 +- docs/content/_index.md | 2 +- docs/content/usage/_index.md | 102 ---------------------- docs/content/usage/getting-started.md | 118 ++++++++++++++++++++++++++ docs/data/menu/main.yml | 4 +- 8 files changed, 129 insertions(+), 107 deletions(-) create mode 100644 docs/.hugo_build.lock create mode 100644 docs/content/usage/getting-started.md diff --git a/.dictionary b/.dictionary index eebc640..8def8e9 100644 --- a/.dictionary +++ b/.dictionary @@ -14,4 +14,8 @@ Codecov IPv4 IPv6 Alertmanager -VM \ No newline at end of file +VM +VMID +Telegraf +QEMU +cloud-init diff --git a/README.md b/README.md index 21ad656..847fd81 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Prometheus Service Discovery for Proxmox VE [![Source: GitHub](https://img.shields.io/badge/source-github-blue.svg?logo=github&logoColor=white)](https://github.com/thegeeklab/prometheus-pve-sd) [![License: MIT](https://img.shields.io/github/license/thegeeklab/prometheus-pve-sd)](https://github.com/thegeeklab/prometheus-pve-sd/blob/main/LICENSE) -This project provides a simple custom service discovery for [Prometheus](https://prometheus.io/). It is using the Proxmox PVE API to fetch Hosts and it's meta information to generate a Prometheus compatible [file based](https://prometheus.io/docs/guides/file-sd/) service discovery. Releases are available as Python Packages on [GitHub](https://github.com/thegeeklab/prometheus-pve-sd/releases) or [PyPI](https://pypi.org/project/prometheus-pve-sd/) and as Docker Image on [Docker Hub](https://hub.docker.com/r/thegeeklab/prometheus-pve-sd). +This project provides a simple custom service discovery for [Prometheus](https://prometheus.io/). It is using the [Proxmox VE](https://www.proxmox.com/de/proxmox-ve) (PVE) API to fetch Hosts and it's meta information to generate a Prometheus compatible [file based](https://prometheus.io/docs/guides/file-sd/) service discovery. Releases are available as Python Packages on [GitHub](https://github.com/thegeeklab/prometheus-pve-sd/releases) or [PyPI](https://pypi.org/project/prometheus-pve-sd/) and as Docker Image on [Docker Hub](https://hub.docker.com/r/thegeeklab/prometheus-pve-sd). You can find the full documentation at [https://prometheus-pve-sd.geekdocs.de](https://prometheus-pve-sd.geekdocs.de). diff --git a/docs/.hugo_build.lock b/docs/.hugo_build.lock new file mode 100644 index 0000000..e69de29 diff --git a/docs/config.yaml b/docs/config.yaml index 9ce55a6..6ac82e3 100644 --- a/docs/config.yaml +++ b/docs/config.yaml @@ -19,7 +19,7 @@ markup: params: description: > - prometheus-pve-sd is a simple custom service discovery for Prometheus. It is using the Proxmox PVE API + prometheus-pve-sd is a simple custom service discovery for Prometheus. It is using the Proxmox VE API to fetch Hosts and it's meta information to generate a Prometheus compatible file based service discovery. images: - "socialmedia2.png" diff --git a/docs/content/_index.md b/docs/content/_index.md index bafea00..eeb83c1 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -13,4 +13,4 @@ title: Documentation [![Source: GitHub](https://img.shields.io/badge/source-github-blue.svg?logo=github&logoColor=white)](https://github.com/thegeeklab/prometheus-pve-sd) [![License: MIT](https://img.shields.io/github/license/thegeeklab/prometheus-pve-sd)](https://github.com/thegeeklab/prometheus-pve-sd/blob/main/LICENSE) -This project provides a simple custom service discovery for [Prometheus](https://prometheus.io/). It is using the Proxmox PVE API to fetch Hosts and it's meta information to generate a Prometheus compatible [file based](https://prometheus.io/docs/guides/file-sd/) service discovery. Releases are available as Python Packages on [GitHub](https://github.com/thegeeklab/prometheus-pve-sd/releases) or [PyPI](https://pypi.org/project/prometheus-pve-sd/) and as Docker Image on [Docker Hub](https://hub.docker.com/r/thegeeklab/prometheus-pve-sd). +This project provides a simple custom service discovery for [Prometheus](https://prometheus.io/). It is using the [Proxmox VE](https://www.proxmox.com/de/proxmox-ve) (PVE) API to fetch Hosts and it's meta information to generate a Prometheus compatible [file based](https://prometheus.io/docs/guides/file-sd/) service discovery. Releases are available as Python Packages on [GitHub](https://github.com/thegeeklab/prometheus-pve-sd/releases) or [PyPI](https://pypi.org/project/prometheus-pve-sd/) and as Docker Image on [Docker Hub](https://hub.docker.com/r/thegeeklab/prometheus-pve-sd). diff --git a/docs/content/usage/_index.md b/docs/content/usage/_index.md index 3cf46d4..6486c07 100644 --- a/docs/content/usage/_index.md +++ b/docs/content/usage/_index.md @@ -1,105 +1,3 @@ --- title: Usage --- - -{{< toc >}} - -## Start PVE SD - -Create a [configuration file](/configuration/defaults/) with the required parameters to connect to your PVE server before you start the service. - -```Shell -run prometheus-pve-sd -vv --loop-delay 900 -o /etc/prometheus/pve.json -``` - -## Available Labels - -The following list of meta labels can be used to relabel your scrape results: - -`__meta_pve_ipv4` - -`__meta_pve_ipv6` - -`__meta_pve_name` - -`__meta_pve_type` - -`__meta_pve_vmid` - -`__meta_pve_cpu` - -`__meta_pve_cores` - -`__meta_pve_memory` - -`__meta_pve_status` - -`__meta_pve_tags` -: A comma-separated list of tags, as set on Proxmox. Tags are supported by Proxmox 6+, and the field is missing if no tags are present on a VM. - -`__meta_pve_groups` -: Groups will be discovered from the `Notes` field of a host and need to be set as JSON e.g. `{"groups":["group1","group2"]}` - -## Prometheus configuration - -This example configuration snippet for the Prometheus `scrape_config` Prometheus to scrape `telegraf` assuming that it is deployed on all your servers. - -```YAML -- file_sd_configs: - - files: - - /opt/prometheus/conf/file_sd/proxmox.json - job_name: telegraf-pve - metrics_path: /metrics - relabel_configs: - - replacement: telegraf - target_label: job - - replacement: ${1}:9273 - source_labels: - - __meta_pve_name - target_label: __address__ - - source_labels: - - __meta_pve_name - target_label: instance -``` - -### IPv4 or c usage - -Set the address from the IPv4 or IPv4 meta label, and not the name - -```YAML -relabel_configs: -- replacement: ${1}:9273 - source_labels: - - __meta_pve_ipv4 - target_label: __address__ -``` - -## Convert tags to custom labels - -E.g. Extract `group` and `alert` from a list of tags like this: `__meta_pve_tags="alert:team-1,group:cluster-1,node:node-1"` - -```YAML -relabel_configs: -- source_labels: - - __meta_pve_tags - regex: ".*group:([\w\-_]*)" - target_label: "group" - replacement: "${1}" -- source_labels: - - __meta_pve_tags - regex: ".*alert:([\w\-_]*)" - target_label: "alert" - replacement: "${1}" -``` - -Using the `alert` label, you can then for example set an Alertmanager route, for this alert - -```YAML -routes: -- receiver: "empty" - matchers: - - alert = muted -- receiver: "team-1" - matchers: - - alert = team-1 -``` diff --git a/docs/content/usage/getting-started.md b/docs/content/usage/getting-started.md new file mode 100644 index 0000000..829b4b7 --- /dev/null +++ b/docs/content/usage/getting-started.md @@ -0,0 +1,118 @@ +--- +title: Getting Started +--- + +{{< toc >}} + +## Start PVE SD + +Create a [configuration file](/configuration/defaults/) with the required parameters to connect to your Proxmox VE (PVE) server before you start the service. + +```Shell +prometheus-pve-sd -vv --loop-delay 900 -o /etc/prometheus/pve.json +``` + +## Available Labels + +The following list of meta labels can be used to relabel your scrape results: + +`__meta_pve_ipv4` +: Discovered IPv4 address or `False` if not found. To discover the IP address either QEMU guest agent or a cloud-init configuration is required. + +`__meta_pve_ipv6` +: Discovered IPv6 address or `False` if not found. To discover the IP address either QEMU guest agent or a cloud-init configuration is required. + +`__meta_pve_name` +: Name of the node. + +`__meta_pve_type` +: Node type, either `qemu` or `lxc`. + +`__meta_pve_vmid` +: VMID of the node. + +`__meta_pve_cpu` +: Current CPU load of the node. + +`__meta_pve_cores` +: Assigned CPU cores for the node. + +`__meta_pve_memory` +: Assigned RAM for the node. + +`__meta_pve_status` +: Current state of the node. + +`__meta_pve_tags` +: A comma-separated list of tags, as set on the node. The label is not getting exported if no tags were found. (Requires PVE 6+) + +`__meta_pve_groups` +: Groups discovered from the `Notes` field of the node. Need to be a valid JSON string e.g. `{"groups":["group1","group2"]}`. + +## Prometheus configuration + +Prometheus needs a basic file service discovery configuration to fetch system metrics from the host's discovered from PVE. Depending on the used metrics exporter the configuration need to be adjusted, using [Telegraf](https://github.com/influxdata/telegraf/#telegraf) a starter configuration might look like this: + +```YAML +- file_sd_configs: + - files: + - /opt/prometheus/conf/file_sd/proxmox.json + job_name: telegraf-pve + metrics_path: /metrics + relabel_configs: + - replacement: telegraf + target_label: job + - replacement: ${1}:9273 + source_labels: + - __meta_pve_name + target_label: __address__ + - source_labels: + - __meta_pve_name + target_label: instance +``` + +### Use IP address labels + +Instead of `__meta_pve_name`, it is also possible to configure Prometheus to use the address provided by `__meta_pve_ipv4` or `__meta_pve_ipv4` for connections: + +```YAML +relabel_configs: +- replacement: ${1}:9273 + source_labels: + - __meta_pve_ipv4 + target_label: __address__ +``` + +### Convert tags to custom labels + +Tags of a node exposed by the `__meta_pve_tags` might be useful to build more complex configurations in Prometheus. As an example, an `alert` tag can be extracted to dine alerting routes based on the tag value. + +**Example:** + +Extract `group` and `alert` from a list of tags like this: `__meta_pve_tags="alert:team-1,group:cluster-1,node:node-1"` + +```YAML +relabel_configs: +- source_labels: + - __meta_pve_tags + regex: ".*group:([\w\-_]*)" + target_label: "group" + replacement: "${1}" +- source_labels: + - __meta_pve_tags + regex: ".*alert:([\w\-_]*)" + target_label: "alert" + replacement: "${1}" +``` + +Use the extracted `alert` label to set an Alertmanager route: + +```YAML +routes: +- receiver: "empty" + matchers: + - alert = muted +- receiver: "team-1" + matchers: + - alert = team-1 +``` diff --git a/docs/data/menu/main.yml b/docs/data/menu/main.yml index da79e25..1ccb147 100644 --- a/docs/data/menu/main.yml +++ b/docs/data/menu/main.yml @@ -16,4 +16,6 @@ main: - name: Environment variables ref: "/configuration/env" - name: Usage - ref: "/usage" + sub: + - name: Getting Started + ref: "/usage/getting-started"