Updated docs

.gitea/workflows/docker-tag-build.yml

@@ -38,5 +38,6 @@ jobs:
           docker buildx build \
             --platform linux/amd64 \
             -t "${IMAGE_NAME}:${IMAGE_TAG}" \
+            -t "${IMAGE_NAME}:latest" \
             --push \
-            .
+            .

README.md

@@ -69,31 +69,36 @@ unusable subscription.
 The ZFS collector discovers all pools on every node and exports their recursive
 topology with `cluster`, `node`, `pool`, `component`, `path`, and `leaf` labels:
 
-- `pve_node_zfs_state` (`1` for `ONLINE`, otherwise `0`)
+- `pve_node_zfs_state` (`0=UNKNOWN`, `1=ONLINE`, `2=DEGRADED`, `3=FAULTED`,
+  `4=OFFLINE`, `5=REMOVED`, `6=UNAVAIL`)
 - `pve_node_zfs_read_errors`
 - `pve_node_zfs_write_errors`
 - `pve_node_zfs_checksum_errors`
 
-## Build
+## Pull the Latest Image
+
+The latest published version can be downloaded from the Gitea container registry:
+
+```sh
+docker pull gitea.lostak.dev/lostakj/pve-exporter:latest
+```
+
+## Build Locally
 
 To build the Docker image for PVE Exporter, use the following command:
 
 ```sh
-docker build --rm -t gitea.lostak.dev/lostakj/pve-exporter:version .
+docker build --rm -t gitea.lostak.dev/lostakj/pve-exporter:latest .
 ```
 
-Replace `version` with the appropriate version tag you want to use.
-
 ## Run
 
-To run the Docker image, use the following command:
+To run the downloaded or locally built image, use the following command:
 
 ```sh
-docker run --rm -d -p 9090:9090 --name pve-exporter gitea.lostak.dev/lostakj/pve-exporter:version
+docker run --rm -d -p 9090:9090 --name pve-exporter gitea.lostak.dev/lostakj/pve-exporter:latest
 ```
 
-Replace `version` with the appropriate version tag you used during the build.
-
 ## Usage
 
 Once the Docker container is running, the exporter will be available on port `9090`. You can configure Prometheus to scrape metrics from the exporter by adding a new scrape configuration to your Prometheus configuration file.

configuration/configuration.go

@@ -63,6 +63,10 @@ func (c *Configuration) Validate() error {
 		if !(u.Scheme == "http" || u.Scheme == "https") {
 			return fmt.Errorf("PVE host '%s' must be protocol type of HTTP or HTTPS.", host)
 		}
+
+		if u.Hostname() == "" {
+			return fmt.Errorf("PVE host '%s' must contain an IP address or DNS name.", host)
+		}
 	}
 
 	// Validate PVE token

configuration/configuration_test.go

@@ -0,0 +1,32 @@
+package configuration
+
+import "testing"
+
+func TestConfigurationValidateAcceptsIPAndDNSPveHosts(t *testing.T) {
+	tests := []struct {
+		name string
+		host string
+	}{
+		{name: "IP address", host: "https://192.168.0.10:8006"},
+		{name: "DNS name", host: "https://pve.example.com:8006"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			configuration := Configuration{
+				Host: "0.0.0.0",
+				PVE: PveConfiguration{
+					Hosts: []string{tt.host},
+					Token: PveTokenConfiguration{
+						TokenId: "token",
+						Secret:  "secret",
+					},
+				},
+			}
+
+			if err := configuration.Validate(); err != nil {
+				t.Fatalf("Validate() rejected %s host %q: %v", tt.name, tt.host, err)
+			}
+		})
+	}
+}

metrics/pve_node_zfs_collector.go

@@ -26,17 +26,26 @@ type zfsMetricComponent struct {
 	Path string
 }
 
+var zfsStateValues = map[string]float64{
+	"ONLINE":   1,
+	"DEGRADED": 2,
+	"FAULTED":  3,
+	"OFFLINE":  4,
+	"REMOVED":  5,
+	"UNAVAIL":  6,
+}
+
 // NewPveNodeZfsCollector creates a ZFS metrics collector.
 func NewPveNodeZfsCollector(apiClient *proxmox.PveApiClient, registry *TTLRegistry) *PveNodeZfsCollector {
 	c := PveNodeZfsCollector{apiClient: apiClient, registry: registry}
-	labelNames := []string{"cluster", "node", "pool", "component", "path", "leaf"}
+	componentLabelNames := []string{"cluster", "node", "pool", "component", "path", "leaf"}
 
 	c.state = NewTTLGaugeVec(
 		prometheus.GaugeOpts{
 			Name: "pve_node_zfs_state",
-			Help: "ZFS pool component state (1 = ONLINE, 0 = any other state).",
+			Help: "ZFS pool component state (0 = UNKNOWN, 1 = ONLINE, 2 = DEGRADED, 3 = FAULTED, 4 = OFFLINE, 5 = REMOVED, 6 = UNAVAIL).",
 		},
-		labelNames,
+		componentLabelNames,
 		5*time.Minute,
 	)
 	c.registry.Register(c.state)
@@ -46,7 +55,7 @@ func NewPveNodeZfsCollector(apiClient *proxmox.PveApiClient, registry *TTLRegist
 			Name: "pve_node_zfs_read_errors",
 			Help: "ZFS pool component read error count.",
 		},
-		labelNames,
+		componentLabelNames,
 		5*time.Minute,
 	)
 	c.registry.Register(c.readErrors)
@@ -56,7 +65,7 @@ func NewPveNodeZfsCollector(apiClient *proxmox.PveApiClient, registry *TTLRegist
 			Name: "pve_node_zfs_write_errors",
 			Help: "ZFS pool component write error count.",
 		},
-		labelNames,
+		componentLabelNames,
 		5*time.Minute,
 	)
 	c.registry.Register(c.writeErrors)
@@ -66,7 +75,7 @@ func NewPveNodeZfsCollector(apiClient *proxmox.PveApiClient, registry *TTLRegist
 			Name: "pve_node_zfs_checksum_errors",
 			Help: "ZFS pool component checksum error count.",
 		},
-		labelNames,
+		componentLabelNames,
 		5*time.Minute,
 	)
 	c.registry.Register(c.checksumErrors)
@@ -146,8 +155,8 @@ func appendZfsComponent(components *[]zfsMetricComponent, component proxmox.PveZ
 }
 
 func zfsStateNumeric(state string) float64 {
-	if strings.EqualFold(state, "ONLINE") {
-		return 1
+	if value, ok := zfsStateValues[strings.ToUpper(state)]; ok {
+		return value
 	}
 	return 0
 }

metrics/pve_node_zfs_collector_test.go

@@ -55,10 +55,24 @@ func TestFlattenZfsComponents(t *testing.T) {
 }
 
 func TestZfsStateNumeric(t *testing.T) {
-	if got := zfsStateNumeric("ONLINE"); got != 1 {
-		t.Fatalf("zfsStateNumeric(ONLINE) = %v, want 1", got)
+	tests := []struct {
+		state string
+		want  float64
+	}{
+		{state: "UNKNOWN", want: 0},
+		{state: "ONLINE", want: 1},
+		{state: "DEGRADED", want: 2},
+		{state: "FAULTED", want: 3},
+		{state: "OFFLINE", want: 4},
+		{state: "REMOVED", want: 5},
+		{state: "UNAVAIL", want: 6},
 	}
-	if got := zfsStateNumeric("DEGRADED"); got != 0 {
-		t.Fatalf("zfsStateNumeric(DEGRADED) = %v, want 0", got)
+
+	for _, tt := range tests {
+		t.Run(tt.state, func(t *testing.T) {
+			if got := zfsStateNumeric(tt.state); got != tt.want {
+				t.Fatalf("zfsStateNumeric(%q) = %v, want %v", tt.state, got, tt.want)
+			}
+		})
 	}
 }

proxmox/api_client.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"net"
 	"net/http"
+	"strings"
 	"sync"
 	"time"
 
@@ -55,7 +56,7 @@ func NewApiClient(endpoints []string, tokenId string, secret string, checkInterv
 	// Prepare API endpoints.
 	for _, endpoint := range endpoints {
 		apiEndpoint := ApiEndpoint{
-			host:  endpoint,
+			host:  normalizeApiHost(endpoint),
 			alive: false,
 		}
 		instance.endpoints = append(instance.endpoints, &apiEndpoint)
@@ -86,6 +87,11 @@ func NewApiClient(endpoints []string, tokenId string, secret string, checkInterv
 	return &instance
 }
 
+// normalizeApiHost ensures API paths can be appended to either IP- or DNS-based hosts.
+func normalizeApiHost(host string) string {
+	return strings.TrimRight(strings.TrimSpace(host), "/") + "/"
+}
+
 // Check endpoint liveness state.
 func (instance *ApiClient) checkEndpointsLiveness() {
 	// We want to make sure other routines won't make any requests until we have checked for alive connections.

proxmox/api_client_test.go

@@ -0,0 +1,49 @@
+package proxmox
+
+import (
+	"testing"
+	"time"
+)
+
+func TestNewApiClientNormalizesEndpointHosts(t *testing.T) {
+	tests := []struct {
+		name string
+		host string
+		want string
+	}{
+		{
+			name: "IP without trailing slash",
+			host: "https://192.168.0.10:8006",
+			want: "https://192.168.0.10:8006/",
+		},
+		{
+			name: "IP with trailing slash",
+			host: "https://192.168.0.10:8006/",
+			want: "https://192.168.0.10:8006/",
+		},
+		{
+			name: "DNS without trailing slash",
+			host: "https://pve.example.com:8006",
+			want: "https://pve.example.com:8006/",
+		},
+		{
+			name: "DNS with trailing slash",
+			host: "https://pve.example.com:8006/",
+			want: "https://pve.example.com:8006/",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			client := NewApiClient([]string{tt.host}, "token", "secret", time.Second)
+			defer client.httpClient.CloseIdleConnections()
+
+			if got := client.endpoints[0].host; got != tt.want {
+				t.Fatalf("normalized endpoint host = %q, want %q", got, tt.want)
+			}
+			if got := client.endpoints[0].host + "api2/json/"; got != tt.want+"api2/json/" {
+				t.Fatalf("liveness URL = %q, want %q", got, tt.want+"api2/json/")
+			}
+		})
+	}
+}