### HTTP Server Setup

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/COVERAGE.txt

Demonstrates the basic setup for an HTTP server, which is typically used to expose Prometheus metrics. This snippet likely forms part of the exporter's main execution flow.

```go
http.ListenAndServe(":9100", nil)

```

--------------------------------

### Install Pre-Commit Hooks

Source: https://github.com/natrontech/pbs-exporter/blob/main/CONTRIBUTING.md

Install the pre-commit framework to enforce code style checks before committing. This should be done after cloning the repository.

```bash
pre-commit install
```

--------------------------------

### Example: Initialize and Register Exporter

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/01-exporter-class.md

Demonstrates how to create a new Exporter instance and register it with the Prometheus registry.

```go
exporter := NewExporter(
	"http://10.10.10.10:8007",
	"root@pam",
	"beef-1337-cafe-beef-cafe-1337",
	"pbs-exporter",
)
prometheus.Register(exporter)
```

--------------------------------

### Example: Collecting Metric Descriptors

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/01-exporter-class.md

Shows how to call the Describe method and iterate over the collected metric descriptors.

```go
descriptors := make(chan *prometheus.Desc, 100)
exporter.Describe(descriptors)
for desc := range descriptors {
	fmt.Println(desc.String())
}
```

--------------------------------

### Install GoImports Tool

Source: https://github.com/natrontech/pbs-exporter/blob/main/CONTRIBUTING.md

Install the goimports tool, which automatically manages Go import lines. This is part of the pre-commit hooks.

```bash
go install golang.org/x/tools/cmd/goimports@latest
```

--------------------------------

### Run Exporter with Minimal Configuration

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/08-quick-start.md

Use this command for a basic setup with direct flag arguments for endpoint and API token.

```bash
./pbs-exporter \
  -pbs.endpoint=http://localhost:8007 \
  -pbs.api.token=<token-value>
```

--------------------------------

### Install and Run Gosec

Source: https://github.com/natrontech/pbs-exporter/blob/main/CLAUDE.md

Installs the latest version of `gosec` and runs it against the project's Go code to identify security vulnerabilities. This command is used for manual security scanning.

```bash
go install github.com/securego/gosec/v2/cmd/gosec@latest
gosec ./...
```

--------------------------------

### Example: Collecting Metrics

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/01-exporter-class.md

Demonstrates calling the Collect method and processing the returned Prometheus metrics.

```go
metrics := make(chan prometheus.Metric, 1000)
exporter.Collect(metrics)
// Process collected metrics
for metric := range metrics {
	// Send to Prometheus
}
```

--------------------------------

### Node Subscription Response Example

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/05-api-endpoints.md

An example of the dynamically typed JSON response for the node subscription endpoint, showing status and product information.

```json
{
  "data": {
    "status": "active",
    "productname": "proxmox-backup-3",
    "nextduedate": "2025-12-31",
    "serverid": "...",
    "key": "..."
  }
}
```

--------------------------------

### Example Metrics Endpoint Requests

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/07-http-server.md

Demonstrates how to request metrics from the exporter using curl. Examples show using a configured endpoint, a target from a query parameter, and multiple targets for Prometheus configuration.

```bash
# Use endpoint from flag
curl http://localhost:10019/metrics

# Use target from query parameter
curl http://localhost:10019/metrics?target=http://pbs.internal:8007

# Multiple targets in Prometheus config
curl http://localhost:10019/metrics?target=http://pbs1.example.com:8007
curl http://localhost:10019/metrics?target=http://pbs2.example.com:8007
```

--------------------------------

### Finding Backups

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/COVERAGE.txt

Provides an example of how to find backups. This function is likely used to retrieve information about available backups.

```go
backups, err := backup.FindBackups()

```

--------------------------------

### Install PBS Exporter on Proxmox Backup Server

Source: https://github.com/natrontech/pbs-exporter/blob/main/README.md

Follow these steps to download, extract, and install the PBS Exporter binary on a Proxmox Backup Server. Ensure you create a dedicated user for the exporter.

```bash
# Download prometheus-pbs-exporter
mkdir /opt/pbs-exporter
cd /opt/pbs-exporter
wget https://github.com/natrontech/pbs-exporter/releases/download/v0.6.4/pbs-exporter_v0.6.4_linux_amd64.tar.gz
tar xfvz pbs-exporter_v0.6.4_linux_amd64.tar.gz
cp pbs-exporter-linux-amd64 /bin/

# Create a dedicated user for running the prometheus-pbs-exporter
useradd -m pbs-exporter -s /sbin/nologin

# Download systemd unit file
cd /etc/systemd/system
wget https://raw.githubusercontent.com/natrontech/pbs-exporter/refs/heads/main/systemd/prometheus-pbs-exporter.service
systemd daemon-reload

# Create prometheus-pbs-exporter environment file (req. minimum the token)
vi /etc/pbs-exporter.env
# Add the token content and other options if required:
TOKEN=beef-1337-cafe-beef-cafe-1337

# Enable and start the service
systemctl enable prometheus-pbs-exporter.service
systemctl start prometheus-pbs-exporter.service
```

--------------------------------

### Setup Root Endpoint Handler

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/07-http-server.md

Sets up the HTTP handler for the root path ('/'). It serves a simple HTML page with a link to the metrics endpoint.

```go
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
	_, err := w.Write([]byte(`<html>
		<head><title>PBS Exporter</title></head>
		<body>
		<h1>Proxmox Backup Server Exporter</h1>
		<p><a href='` + *metricsPath + `'>Metrics</a></p>
		</body>
		</html>`))
	if err != nil {
		log.Printf("ERROR: Failed to write response: %s", err)
	}
})
```

--------------------------------

### Server Startup Log Output

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/07-http-server.md

Example log messages during server startup, indicating version, build time, and listening addresses. Debug mode provides additional connection details.

```text
INFO: Starting PBS Exporter <version>, commit <commit>, built at <buildtime>
INFO: Listening on: <listen-address>
INFO: Metrics path: <metrics-path>
```

```text
DEBUG: Using connection endpoint: <endpoint>
DEBUG: Using connection username: <username>
DEBUG: Using metrics path: <metrics-path>
DEBUG: Using listen address: <listen-address>
```

--------------------------------

### Version Endpoint Request

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/05-api-endpoints.md

Example HTTP request to the Proxmox Backup Server version endpoint. This endpoint retrieves version information about the PBS installation.

```http
GET /api2/json/version HTTP/1.1
Authorization: PBSAPIToken=root@pam!pbs-exporter:token
```

--------------------------------

### Configure Remote PBS with Custom Credentials

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/08-quick-start.md

Example demonstrating how to connect to a remote PBS instance with custom credentials, including insecure connection and timeout settings.

```bash
./pbs-exporter \
  -pbs.endpoint=https://pbs.example.com:8007 \
  -pbs.username=monitoring@pam \
  -pbs.api.token=beef-1337-cafe-beef-cafe-1337 \
  -pbs.api.token.name=prometheus-exporter \
  -pbs.insecure=false \
  -pbs.timeout=10s \
  -pbs.listen-address=:10019
```

--------------------------------

### Configuration Priority Example

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/INDEX.md

Demonstrates the order of precedence for configuration settings: environment variables, secret files, command-line flags, and finally defaults. Environment variables take the highest priority.

```bash
# This order is checked:
1. export PBS_API_TOKEN=...      # Environment variable wins
2. export PBS_API_TOKEN_FILE=... # Secret file as fallback
3. -pbs.api.token=...            # Flag as fallback
4. Required, no default          # Final fallback (error)
```

--------------------------------

### Example Output for pbs_version Metric

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/03-metrics-reference.md

Illustrates the output format for the 'pbs_version' gauge metric, including its labels and value.

```text
# HELP pbs_version Version of the PBS installation.
# TYPE pbs_version gauge
pbs_version{release="3.1",repoid="proxmox-backup-3.1",version="3.1.1"} 1
```

--------------------------------

### Example Output for pbs_up Metric

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/03-metrics-reference.md

Shows the expected output format for the 'pbs_up' gauge metric, indicating a successful scrape.

```text
# HELP pbs_up Was the last query of PBS successful.
# TYPE pbs_up gauge
pbs_up 1
```

--------------------------------

### Docker Service Creation with Secrets

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/08-quick-start.md

Example of creating a Docker service using docker service create, mounting secrets for authentication and configuration.

```bash
docker service create \
  --name pbs-exporter \
  --publish 10019:10019 \
  --secret pbs_token \
  --secret pbs_username \
  --secret pbs_token_name \
  --env PBS_ENDPOINT=http://pbs:8007 \
  --env PBS_API_TOKEN_FILE=/run/secrets/pbs_token \
  --env PBS_USERNAME_FILE=/run/secrets/pbs_username \
  --env PBS_API_TOKEN_NAME_FILE=/run/secrets/pbs_token_name \
  natrontech/pbs-exporter:latest
```

--------------------------------

### HTTP Server Instance Configuration

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/07-http-server.md

Configures and starts an HTTP server instance. Uses the DefaultServeMux for handling requests. The server listens on a configurable address and has defined read and write timeouts.

```go
server := &http.Server{
	Addr:         *listenAddress,
	Handler:      nil,
	ReadTimeout:  time.Second * 10,
	WriteTimeout: time.Second * 10,
}
log.Fatal(server.ListenAndServe())
```

--------------------------------

### Example Docker Compose Configuration for PBS Exporter

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/04-configuration.md

Demonstrates how to configure the PBS Exporter service in Docker Compose, including setting environment variables and defining secret mounts.

```yaml
services:
  pbs-exporter:
    image: pbs-exporter:latest
    environment:
      PBS_ENDPOINT: http://pbs.internal:8007
      PBS_API_TOKEN_FILE: /run/secrets/pbs_token
      PBS_USERNAME_FILE: /run/secrets/pbs_username
    secrets:
      - pbs_token
      - pbs_username
    ports:
      - "10019:10019"

secrets:
  pbs_token:
    external: true
  pbs_username:
    external: true
```

--------------------------------

### Status Metric Generation Example

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/05-api-endpoints.md

Illustrates the generation of Prometheus metrics for different subscription statuses, where a value of 1 indicates the active status.

```prometheus
pbs_host_subscription_status{status="new"} 0
pbs_host_subscription_status{status="notfound"} 0
pbs_host_subscription_status{status="active"} 1
pbs_host_subscription_status{status="invalid"} 0
pbs_host_subscription_status{status="expired"} 0
pbs_host_subscription_status{status="suspended"} 0
```

--------------------------------

### Systemd Service Management Commands

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/08-quick-start.md

Commands to enable, start, and check the status of the PBS exporter systemd service.

```bash
systemctl enable pbs-exporter
systemctl start pbs-exporter
systemctl status pbs-exporter
```

--------------------------------

### Total Memory Metric

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/03-metrics-reference.md

Shows the total memory installed on the host in bytes. This is a gauge metric.

```text
pbs_host_memory_total (gauge)

Total memory installed on the host.

| Property | Value |
|----------|-------|
| Type | Gauge |
| Unit | Bytes |
| Labels | None |
| Description | The total memory of the host |
```

```prometheus
# HELP pbs_host_memory_total The total memory of the host.
# TYPE pbs_host_memory_total gauge
pbs_host_memory_total 17179869184
```

--------------------------------

### Prometheus Configuration for Dynamic Targeting

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/07-http-server.md

Provides a Prometheus scrape configuration example for monitoring multiple PBS instances. It uses relabeling to dynamically set the target parameter for the exporter.

```yaml
scrape_configs:
  - job_name: pbs
    static_configs:
      - targets:
          - http://pbs1.example.com:8007
          - http://pbs2.example.com:8007
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - target_label: __address__
        replacement: localhost:10019
      - source_labels: [__param_target]
        target_label: instance
```

--------------------------------

### Configure Prometheus for PBS Exporter

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/INDEX.md

Add the PBS Exporter to your Prometheus scrape configuration. This example targets a single instance.

```yaml
scrape_configs:
  - job_name: pbs
    static_configs:
      - targets: ['localhost:10019']
```

--------------------------------

### Version Endpoint

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/05-api-endpoints.md

Retrieves version information about the Proxmox Backup Server installation. This endpoint is essential for verifying connectivity and understanding the PBS version.

```APIDOC
## GET /api2/json/version

### Description
Retrieves version information about the Proxmox Backup Server installation.

### Method
GET

### Endpoint
/api2/json/version

### Parameters
#### Common Headers
- **Authorization** (string) - Required - `PBSAPIToken=<username>!<tokenname>:<token>`

### Response
#### Success Response (200)
- **data.version** (string) - Full version number
- **data.repoid** (string) - Repository identifier
- **data.release** (string) - Release version identifier

### Response Example
```json
{
  "data": {
    "version": "3.1.1",
    "repoid": "proxmox-backup-3.1",
    "release": "3.1"
  }
}
```
```

--------------------------------

### Datastore Usage Endpoint Request

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/05-api-endpoints.md

Example HTTP request to the Proxmox Backup Server datastore usage endpoint. This endpoint lists all datastores and their storage usage.

```http
GET /api2/json/status/datastore-usage HTTP/1.1
Authorization: PBSAPIToken=root@pam!pbs-exporter:token
```

--------------------------------

### Setup Prometheus Metrics Handler

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/07-http-server.md

Configures the HTTP handler for the /metrics endpoint. It dynamically determines the PBS target URL from flags or query parameters, creates an exporter, registers it with Prometheus, serves metrics, and then unregisters the exporter.

```go
http.HandleFunc(*metricsPath, func(w http.ResponseWriter, r *http.Request) {
	target := ""

	// if endpoint was not set as flag or env variable, we try to get it from "target" query parameter
	if *endpoint != "" {
		target = *endpoint
	} else {
		target = r.URL.Query().Get("target")
		if target == "" {
			// if target is not set, we use the default
			target = "http://localhost:8007"
		}
	}

	// debug
	if *loglevel == "debug" {
		log.Printf("DEBUG: Using connection endpoint %s", strings.ReplaceAll(strings.ReplaceAll(target, "\n", ""), "\r", ""))
	}

	exporter := NewExporter(target, *username, *apitoken, *apitokenname)

	// catch if register of exporter fails
	err := prometheus.Register(exporter)
	if err != nil {
		// if register fails, we log the error and return
		log.Printf("ERROR: %s", err)
	}
	promhttp.Handler().ServeHTTP(w, r) // Serve the metrics
	prometheus.Unregister(exporter)    // Clean up after serving
})
```

--------------------------------

### Static Prometheus Configuration (Multiple PBS Instances)

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/08-quick-start.md

Configure Prometheus to scrape metrics from multiple PBS Exporter instances. This setup uses multiple targets and rewrites labels to correctly identify each instance.

```yaml
scrape_configs:
  - job_name: pbs
    static_configs:
      - targets:
          - http://pbs1.example.com:8007
          - http://pbs2.example.com:8007
          - http://pbs3.example.com:8007
    relabel_configs:
      # Copy target to __param_target
      - source_labels: [__address__]
        target_label: __param_target
      # Set scrape URL to exporter
      - target_label: __address__
        replacement: localhost:10019
      # Use original target as instance label
      - source_labels: [__param_target]
        target_label: instance
```

--------------------------------

### Get Latest Release Version

Source: https://github.com/natrontech/pbs-exporter/blob/main/SECURITY.md

Sets the VERSION environment variable to the latest release tag from the GitHub API. This is a prerequisite for many verification commands.

```bash
# get the latest release
export VERSION=$(curl -s "https://api.github.com/repos/natrontech/pbs-exporter/releases/latest" | jq -r '.tag_name')
```

--------------------------------

### Datastore Namespace Endpoint Request

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/05-api-endpoints.md

Example HTTP request to the Proxmox Backup Server datastore namespace endpoint. This endpoint lists all namespaces within a specific datastore.

```http
GET /api2/json/admin/datastore/local/namespace HTTP/1.1
Authorization: PBSAPIToken=root@pam!pbs-exporter:token
```

--------------------------------

### Scrape Specific PBS Instance with cURL

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/04-configuration.md

Example of using cURL to scrape metrics for a specific PBS instance by providing the target URL in the query parameter. This demonstrates the practical application of the 'target' parameter.

```bash
# Scrape metrics for a specific PBS instance
curl http://localhost:10019/metrics?target=http://pbs1.example.com:8007
```

--------------------------------

### Set Prometheus Metrics Path

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/04-configuration.md

Configure the HTTP path for exposing Prometheus metrics. Defaults to '/metrics'. Must start with '/'. The root path '/' serves an HTML page with a link to metrics. Can be set via PBS_METRICS_PATH environment variable.

```bash
./pbs-exporter -pbs.metrics-path=/pbs-metrics
```

--------------------------------

### Creating Exporter Instance

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/COVERAGE.txt

Demonstrates how to create an instance of the PBS Exporter. This is a foundational step for setting up the exporter.

```go
exporter := exporter.NewExporter()

```

--------------------------------

### Get Jobs API

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/COVERAGE.txt

This endpoint retrieves a list of all configured jobs.

```APIDOC
## GET /api/v1/jobs

### Description
Retrieves a list of all configured jobs.

### Method
GET

### Endpoint
/api/v1/jobs

### Response
#### Success Response (200 OK)
- **jobs** (array) - A list of job objects.
  - **id** (string) - The unique identifier of the job.
  - **name** (string) - The name of the job.
  - **command** (string) - The command executed by the job.
  - **schedule** (string) - The cron schedule of the job.
```

--------------------------------

### Set up PBS Exporter

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/INDEX.md

Run the exporter with the endpoint and API token. Ensure the token is kept secure.

```bash
./pbs-exporter \
  -pbs.endpoint=http://pbs.local:8007 \
  -pbs.api.token=<token>
```

--------------------------------

### Node Subscription Endpoint

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/05-api-endpoints.md

Retrieves the subscription status and related information for the Proxmox Backup Server installation.

```APIDOC
## GET /api2/json/nodes/localhost/subscription

### Description
Retrieves subscription status and information for the PBS installation.

### Method
GET

### Endpoint
/api2/json/nodes/localhost/subscription

### Parameters
#### Path Parameters
- **localhost** (string) - Description not available in source.

#### Query Parameters
None explicitly documented.

#### Request Body
None.

### Request Example
```http
GET /api2/json/nodes/localhost/subscription HTTP/1.1
Authorization: PBSAPIToken=root@pam!pbs-exporter:token
```

### Response
#### Success Response (200)
- **data.status** (string) - Status of the subscription: `new`, `notfound`, `active`, `invalid`, `expired`, `suspended`.
- **data.productname** (string) - The product identifier.
- **data.nextduedate** (string) - The renewal date in YYYY-MM-DD format.
- **data.*** (any) - Additional fields that may be present.

#### Response Example
```json
{
  "data": {
    "status": "active",
    "productname": "proxmox-backup-3",
    "nextduedate": "2025-12-31",
    "serverid": "...",
    "key": "..."
  }
}
```
```

--------------------------------

### Verify Go Build and Tests

Source: https://github.com/natrontech/pbs-exporter/blob/main/CLAUDE.md

After updating dependencies and configurations, run `go build ./...` to ensure all packages build successfully and `go test ./...` to verify that all tests pass.

```bash
go build ./...
go test ./...
```

--------------------------------

### Display Help Information

Source: https://github.com/natrontech/pbs-exporter/blob/main/README.md

Use this command to display available flags and configuration options for the PBS Exporter.

```bash
./pbs-exporter -help
```

--------------------------------

### Debug Logging at Application Startup

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/06-utility-functions.md

Logs debug information about the connection endpoint, username, timeout, and metrics path during application startup. Helps verify configuration settings.

```go
if *loglevel == "debug" {
	log.Printf("DEBUG: Using connection endpoint: %s", *endpoint)
	log.Printf("DEBUG: Using connection username: %s", *username)
	log.Printf("DEBUG: Using connection timeout: %s", client.Timeout)
	log.Printf("DEBUG: Using metrics path: %s", *metricsPath)
}
```

--------------------------------

### Basic Local PBS Exporter Configuration

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/04-configuration.md

Use this command to run the exporter with a local PBS instance, specifying the API token and listen address.

```bash
./pbs-exporter \
  -pbs.api.token=beef-1337-cafe-beef-cafe-1337 \
  -pbs.listen-address=:10019
```

--------------------------------

### Retrieve Node Subscription Status

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/05-api-endpoints.md

Fetches the subscription status and details for a Proxmox Backup Server installation. The response schema is dynamic and parsed as a map.

```http
GET /api2/json/nodes/localhost/subscription HTTP/1.1
Authorization: PBSAPIToken=root@pam!pbs-exporter:token
```

--------------------------------

### Docker Compose Configuration

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/08-quick-start.md

A Docker Compose setup for running the PBS exporter alongside Prometheus. It defines services, environment variables, ports, and networks.

```yaml
version: '3.8'

services:
  pbs-exporter:
    image: natrontech/pbs-exporter:latest
    environment:
      PBS_ENDPOINT: http://pbs:8007
      PBS_API_TOKEN: beef-1337-cafe-beef-cafe-1337
      PBS_LOGLEVEL: info
    ports:
      - "10019:10019"
    networks:
      - monitoring

  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge
```

--------------------------------

### Configure HTTP Client with TLS

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/05-api-endpoints.md

Sets up a shared HTTP client with TLS 1.2 or higher enabled. This client is used for all outgoing requests.

```go
tr = &http.Transport{
	TLSClientConfig: &tls.Config{
		MinVersion: tls.VersionTLS12, 
	},
}
client = &http.Client{
	Transport: tr,
}
```

--------------------------------

### Verify Exporter Metrics

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/08-quick-start.md

Fetch and display the first 20 metrics from the exporter to verify it is running correctly.

```bash
curl http://localhost:10019/metrics | head -20
```

--------------------------------

### Example Error Response

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/05-api-endpoints.md

Illustrates a typical API error response with a non-200 status code. The exporter reports the status code but does not parse error details from the body.

```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error": "authentication failed - invalid token"}
```

--------------------------------

### Download SBOM with Cosign

Source: https://github.com/natrontech/pbs-exporter/blob/main/SECURITY.md

This command downloads the SBOM in JSON format from a container image's attestation using `cosign`. It requires the `policy-sbom.cue` file and assumes the `$IMAGE` variable is set.

```bash
cosign verify-attestation --new-bundle-format \
  --type cyclonedx \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/natrontech/pbs-exporter/.github/workflows/release.yml@refs/tags/v[0-9]+.[0-9]+.[0-9]+(-rc.[0-9]+)?$' \
  --policy policy-sbom.cue \
  $IMAGE | jq -r '.payload' | base64 -d | jq -r '.predicate' > sbom.json
```

--------------------------------

### Systemd Service Unit File

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/08-quick-start.md

This systemd unit file defines how to run the PBS exporter as a service, including user, environment file, and restart policy.

```ini
[Unit]
Description=Proxmox Backup Server Exporter
After=network.target

[Service]
Type=simple
User=pbs-exporter
EnvironmentFile=/opt/pbs-exporter/pbs-exporter.env
ExecStart=/usr/local/bin/pbs-exporter
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Storage Utilization Queries

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/08-quick-start.md

Monitor datastore storage usage and free space. Use the free space alert for critical low-space conditions.

```promql
# Storage used percentage per datastore
(pbs_used / pbs_size) * 100
```

```promql
# Free space alerts
pbs_available < 100*1024*1024*1024  # Less than 100GB free
```

--------------------------------

### NewExporter Constructor

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/01-exporter-class.md

Creates a new Exporter instance. Requires PBS endpoint, username, API token, and token name for authentication.

```go
func NewExporter(endpoint string, username string, apitoken string, apitokenname string) *Exporter
```

--------------------------------

### NewExporter Function and Prometheus Registration

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/README.md

Demonstrates how to create a new exporter instance and register it with Prometheus. This is the entry point for using the exporter.

```go
exporter := NewExporter(endpoint, username, token, tokenname)
prometheus.Register(exporter)
```

--------------------------------

### Define pbs_version Gauge Metric

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/03-metrics-reference.md

Defines the 'pbs_version' gauge metric, which provides version information about the Proxmox Backup Server installation. It includes labels for version, repository ID, and release.

```go
version = prometheus.NewDesc(
	prometheus.BuildFQName("pbs", "", "version"),
	"Version of the PBS installation.",
	[]string{"version", "repoid", "release"}, nil,
)
```

--------------------------------

### Set Proxmox Backup Server Endpoint

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/04-configuration.md

Configure the base URL for Proxmox Backup Server monitoring. If not set, the 'target' query parameter from the HTTP request is used. Defaults to http://localhost:8007 if neither is set. Must include the protocol (http:// or https://).

```bash
./pbs-exporter -pbs.endpoint=http://pbs.internal:8007
```

--------------------------------

### Prometheus Error Response Example

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/07-http-server.md

When collection fails, the Prometheus handler returns a 200 OK status with the 'pbs_up' metric set to 0 to indicate failure, following Prometheus conventions.

```text
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

# HELP pbs_up Was the last query of PBS successful.
# TYPE pbs_up gauge
pbs_up 0
```

--------------------------------

### Docker Configuration for PBS Exporter

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/04-configuration.md

This command demonstrates how to run the PBS Exporter in a Docker container, setting essential environment variables for connection and logging.

```bash
docker run -d \
  -e PBS_ENDPOINT=http://pbs.docker.internal:8007 \
  -e PBS_API_TOKEN=beef-1337-cafe-beef-cafe-1337 \
  -e PBS_LOGLEVEL=info \
  -p 10019:10019 \
  pbs-exporter:latest
```

--------------------------------

### Describe Method

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/01-exporter-class.md

Sends all metric descriptors to a channel. This is used by Prometheus to discover available metrics.

```go
func (e *Exporter) Describe(ch chan<- *prometheus.Desc)
```

--------------------------------

### Get Node Status

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/05-api-endpoints.md

Fetches system metrics for a given node, including CPU, memory, swap, disk usage, and load averages. The node name is conventionally set to 'localhost'.

```http
GET /api2/json/nodes/localhost/status HTTP/1.1
Authorization: PBSAPIToken=root@pam!pbs-exporter:token
```

--------------------------------

### Run Exporter with Environment Variables

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/08-quick-start.md

Configure the exporter using environment variables for endpoint and API token. The exporter will automatically pick them up.

```bash
export PBS_ENDPOINT=http://localhost:8007
export PBS_API_TOKEN=<token-value>
./pbs-exporter
```

--------------------------------

### Display PBS Exporter Version

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/04-configuration.md

Use the `-version` flag to display the exporter's version, commit hash, and build time. This action exits the program without serving metrics.

```bash
./pbs-exporter -version
```

--------------------------------

### Host Load Average (5 minutes)

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/03-metrics-reference.md

Measures the system load average over the last 5 minutes. This metric is a gauge with no labels.

```go
pbs_host_load5 (gauge)
System load average over the last 5 minutes.
```

```text
# HELP pbs_host_load5 The load for 5 minutes of the host.
# TYPE pbs_host_load5 gauge
pbs_host_load5 1.15
```

--------------------------------

### Update Go Dependencies

Source: https://github.com/natrontech/pbs-exporter/blob/main/CLAUDE.md

Runs `go get -u ./...` to update all dependencies to their latest versions and `go mod tidy` to clean up the go.mod file. This command is part of the `make go-update` target.

```bash
# Update all dependencies to latest versions
make go-update   # runs: go get -u ./... && go mod tidy -compat=<major.minor>
```

```bash
go get -u ./...
go mod tidy
```

--------------------------------

### Host Load Average (15 minutes)

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/03-metrics-reference.md

Measures the system load average over the last 15 minutes. This metric is a gauge with no labels.

```go
pbs_host_load15 (gauge)
System load average over the last 15 minutes.
```

```text
# HELP pbs_host_load15 The load 15 minutes of the host.
# TYPE pbs_host_load15 gauge
pbs_host_load15 1.05
```

--------------------------------

### Verify Image Signature (Cosign)

Source: https://github.com/natrontech/pbs-exporter/blob/main/SECURITY.md

Use this command to verify the image signature for legacy releases. Ensure COSIGN_REPOSITORY is set to the correct signature repository.

```bash
COSIGN_REPOSITORY=ghcr.io/natrontech/signatures cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/natrontech/pbs-exporter/.github/workflows/release.yml@refs/tags/v[0-9]+.[0-9]+.[0-9]+(-rc.[0-9]+)?$' \
  $IMAGE | jq
```

--------------------------------

### Verify SBOM Provenance with Cosign

Source: https://github.com/natrontech/pbs-exporter/blob/main/SECURITY.md

Use this command to verify the provenance of the SBOM for container images using `cosign` and a policy file. Ensure `policy-sbom.cue` is downloaded first.

```bash
# download policy-sbom.cue
curl -L -O https://raw.githubusercontent.com/natrontech/pbs-exporter/main/policy-sbom.cue

cosign verify-attestation --new-bundle-format \
  --type cyclonedx \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/natrontech/pbs-exporter/.github/workflows/release.yml@refs/tags/v[0-9]+.[0-9]+.[0-9]+(-rc.[0-9]+)?$' \
  --policy policy-sbom.cue \
  $IMAGE | jq -r '.payload' | base64 -d | jq
```

--------------------------------

### Host Load Average (1 minute)

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/03-metrics-reference.md

Measures the system load average over the last 1 minute. This metric is a gauge with no labels.

```go
pbs_host_load1 (gauge)
System load average over the last 1 minute.
```

```text
# HELP pbs_host_load1 The load for 1 minute of the host.
# TYPE pbs_host_load1 gauge
pbs_host_load1 1.23
```

--------------------------------

### Query Storage Utilization with PromQL

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/INDEX.md

Use this PromQL query to calculate the percentage of storage used across your PBS instances.

```promql
(pbs_used / pbs_size) * 100
```

--------------------------------

### Construct Authorization Header in Go

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/05-api-endpoints.md

Constructs the Authorization header required for Proxmox Backup Server API requests. Ensure username, apitokenname, and apitoken are correctly provided.

```go
authorizationHeader := "PBSAPIToken=" + username + "!" + apitokenname + ":" + apitoken
// Example: "PBSAPIToken=root@pam!pbs-exporter:beef-1337-cafe-beef-cafe-1337"
```

--------------------------------

### Verify Container Image Provenance with Cosign and CUE Policy

Source: https://github.com/natrontech/pbs-exporter/blob/main/SECURITY.md

Verify container image provenance using Cosign and a CUE policy file. This ensures specific requirements, like the correct build workflow and source repository, are met. Ensure to use `--new-bundle-format=false` if the new bundle format is not yet supported for SLSA provenance.

```bash
# download policy.cue
curl -L -O https://raw.githubusercontent.com/natrontech/pbs-exporter/main/policy.cue

# verify the image with cosign (at the moment use `--new-bundle-format=false` as the new format is not yet supported for SLSA provenance)
cosign verify-attestation \
  --type slsaprovenance \
  --new-bundle-format=false \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v[0-9]+.[0-9]+.[0-9]+$' \
  --policy policy.cue \
  $IMAGE | jq -r '.payload' | base64 -d | jq
```

--------------------------------

### Static Prometheus Configuration (Single PBS)

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/08-quick-start.md

Use this configuration for a single PBS Exporter instance. It defines a job named 'pbs' and scrapes metrics from 'localhost:10019', relabeling the address to 'instance'.

```yaml
scrape_configs:
  - job_name: pbs
    static_configs:
      - targets: ['localhost:10019']
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance
```

--------------------------------

### NewExporter Constructor

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/01-exporter-class.md

Creates and returns a new Exporter instance configured with PBS credentials.

```APIDOC
## NewExporter Constructor

### Description
Creates and returns a new Exporter instance configured with PBS credentials.

### Signature
```go
func NewExporter(endpoint string, username string, apitoken string, apitokenname string) *Exporter
```

### Parameters
#### Path Parameters
* **endpoint** (string) - Required - Base URL of the Proxmox Backup Server (e.g., `http://localhost:8007`)
* **username** (string) - Required - PBS username (e.g., `root@pam`)
* **apitoken** (string) - Required - API token for authentication
* **apitokenname** (string) - Required - Name of the API token (e.g., `pbs-exporter`)

### Returns
* **Exporter** - A pointer to the initialized Exporter

### Example
```go
exporter := NewExporter(
	"http://10.10.10.10:8007",
	"root@pam",
	"beef-1337-cafe-beef-cafe-1337",
	"pbs-exporter",
)
prometheus.Register(exporter)
```
```

--------------------------------

### systemd Service Environment File

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/04-configuration.md

Create this file to configure environment variables for the PBS Exporter when running as a systemd service. Ensure the systemd unit file points to this environment file.

```bash
PBS_ENDPOINT=http://localhost:8007
PBS_API_TOKEN=beef-1337-cafe-beef-cafe-1337
PBS_API_TOKEN_NAME=pbs-exporter
PBS_LOGLEVEL=info
```

--------------------------------

### Host Uptime Metric

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/03-metrics-reference.md

Represents the system uptime in seconds since the last boot. This metric is a gauge and has no labels.

```go
pbs_host_uptime (gauge)
System uptime since last boot.
```

```text
# HELP pbs_host_uptime The uptime of the host.
# TYPE pbs_host_uptime gauge
pbs_host_uptime 2592000
```

--------------------------------

### Backup Monitoring Queries

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/08-quick-start.md

Track the age of the latest backups, identify VMs with unverified backups, and count backups per VM.

```promql
# Latest backup age
time() - pbs_snapshot_vm_last_timestamp
```

```promql
# VMs with unverified backups
pbs_snapshot_vm_last_verify == 0
```

```promql
# Backup count per VM
pbs_snapshot_vm_count
```

--------------------------------

### Collect Node Subscription Status Metrics

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/01-exporter-class.md

Collects PBS subscription status metrics, including subscription information, status (active, expired, etc.), and the due date as a Unix timestamp.

```go
func (e *Exporter) getNodeSubscriptionMetrics(ch chan<- prometheus.Metric) error
```

--------------------------------

### Collect Method

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/01-exporter-class.md

Gathers metrics from the PBS API and sends them to a channel. Reports 'pbs_up' metric as 0 on error and 1 on success.

```go
func (e *Exporter) Collect(ch chan<- prometheus.Metric)
```

--------------------------------

### Verify Release Artifacts with SLSA Verifier

Source: https://github.com/natrontech/pbs-exporter/blob/main/SECURITY.md

Verifies the integrity and authenticity of release artifacts (binaries, SBOMs) using the downloaded provenance file and the slsa-verifier tool. Ensure the artifact and provenance file are downloaded before running.

```bash
# example for the "pbs-exporter-darwin-amd64.tar.gz" artifact
export ARTIFACT=pbs-exporter_${VERSION}_darwin_amd64.tar.gz

# download the artifact
curl -L -O https://github.com/natrontech/pbs-exporter/releases/download/$VERSION/$ARTIFACT

# download the provenance file
curl -L -O https://github.com/natrontech/pbs-exporter/releases/download/$VERSION/multiple.intoto.jsonl

# verify the artifact
slsa-verifier verify-artifact \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/natrontech/pbs-exporter \
  --source-tag $VERSION \
  $ARTIFACT
```

--------------------------------

### Collect Node System Metrics

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/01-exporter-class.md

Collects host system metrics from the node status endpoint, including CPU usage, memory, swap, disk space, uptime, I/O wait, and load averages.

```go
func (e *Exporter) getNodeMetrics(ch chan<- prometheus.Metric) error
```

--------------------------------

### Verify Image with SLSA Verifier (Legacy)

Source: https://github.com/natrontech/pbs-exporter/blob/main/SECURITY.md

Use the slsa-verifier tool to verify the image provenance for legacy releases. Specify the source URI, provenance repository, and versioned tag.

```bash
slsa-verifier verify-image \
  --source-uri github.com/natrontech/pbs-exporter \
  --provenance-repository ghcr.io/natrontech/signatures \
  --source-versioned-tag $VERSION \
  $IMAGE
```

--------------------------------

### Registering Metrics Handler

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/07-http-server.md

Registers the metrics handler for a configurable path using http.HandleFunc(). The path can be set at startup but changing it afterwards has no effect.

```go
http.HandleFunc(*metricsPath, metricsHandler)
```

--------------------------------

### PBS Exporter with Debug Logging

Source: https://github.com/natrontech/pbs-exporter/blob/main/_autodocs/04-configuration.md

Enable debug logging and set a custom timeout for the exporter. Ensure the API token is provided.

```bash
./pbs-exporter \
  -pbs.loglevel=debug \
  -pbs.timeout=30s \
  -pbs.api.token=beef-1337-cafe-beef-cafe-1337
```

--------------------------------

### Run GolangCI-Lint Manually

Source: https://github.com/natrontech/pbs-exporter/blob/main/CONTRIBUTING.md

Execute golangci-lint to check code against conventions. This tool is used in CI and pre-commit hooks, but can also be run manually.

```bash
golangci-lint run
```