mirror of
https://github.com/thegeeklab/prometheus-pve-sd.git
synced 2024-11-17 07:00:40 +00:00
docs: refactor usage section and add label description (#170)
This commit is contained in:
GitHub
parent
a2f7422591
commit
4dc5bb1bd8
@ -14,4 +14,8 @@ Codecov
|
||||
IPv4
|
||||
IPv6
|
||||
Alertmanager
|
||||
VM
|
||||
VM
|
||||
VMID
|
||||
Telegraf
|
||||
QEMU
|
||||
cloud-init
|
||||
|
||||
@ -13,7 +13,7 @@ Prometheus Service Discovery for Proxmox VE
|
||||
[](https://github.com/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).
|
||||
|
||||
|
||||
0
docs/.hugo_build.lock
Normal file
0
docs/.hugo_build.lock
Normal file
@ -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"
|
||||
|
||||
@ -13,4 +13,4 @@ title: Documentation
|
||||
[](https://github.com/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).
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
118
docs/content/usage/getting-started.md
Normal file
118
docs/content/usage/getting-started.md
Normal file
@ -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
|
||||
```
|
||||
@ -16,4 +16,6 @@ main:
|
||||
- name: Environment variables
|
||||
ref: "/configuration/env"
|
||||
- name: Usage
|
||||
ref: "/usage"
|
||||
sub:
|
||||
- name: Getting Started
|
||||
ref: "/usage/getting-started"
|
||||
|
||||
Loading…
Reference in New Issue
Block a user