vicarian 0.3.0

Vicarian is a reverse proxy server with ACME support
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

# Vicarian Metrics

Vicarian has built-in support for exporting Prometheus-compatible metrics. This documentation explains how to configure, scrape, and visualize these metrics.

## Configuration

Metrics are enabled by adding a backend with the `module://metrics` URL. This allows you to serve metrics on a specific path (e.g., `/metrics`) and optionally protect them with an `auth_key`.

### Example Configuration

```corn
{
    vhosts = [
        {
            hostname = "example.com"
            // ... TLS configuration ...

            backends = [
                {
                    context = "/metrics"
                    url = "module://metrics"
                    // Optional: require "Authorization: Bearer secret_key"
                    auth_key = "secret_key"
                }
            ]
        }
    ]
}
```

## Scraping with Prometheus

Once enabled, metrics can be scraped by Prometheus. As metrics are served over
HTTPS ensure you configure the scheme and target correctly:

```yaml
scrape_configs:
  - job_name: 'vicarian'
    scheme: https
    static_configs:
      - targets: ['example.com:443']
```

## Visualizing with Grafana

The number of metrics is small but provides essential health and status information.

### ACME Renewal Monitoring

One particularly useful metric is `vicarian_acme_next_renewal_timestamp_secs`, which provides the Unix timestamp for the next ACME/Let's Encrypt renewal.

To visualize the time remaining until renewal in Grafana:

1. Create a new panel.
2. Use the following Prometheus query:
   ```promql
   vicarian_acme_next_renewal_timestamp_secs - time()
   ```
3. Set the panel type to **Bar Gauge**.
4. Set the **Unit** to `Duration (s)` or similar.

![Bar gauge showing multiple host countdowns](docs/grafana-acme-bars.png)

## Available Metrics

The following metrics are currently exported:

- `vicarian_http_requests_total`: Total number of HTTP requests received.
- `vicarian_tls_requests_total`: Total number of TLS requests received.
- `vicarian_http_redirects_total`: Total number of HTTP to HTTPS redirects.
- `vicarian_metrics_scrape_total`: Total number of times the metrics endpoint has been scraped.
- `vicarian_acme_http01_endpoint_total`: Total number of ACME HTTP-01 challenge requests received.
- `vicarian_acme_http01_notfound_total`: Total number of ACME HTTP-01 challenge requests that were not found.
- `vicarian_acme_next_renewal_timestamp_secs`: Unix timestamp of the next expected ACME certificate renewal.
- `vicarian_auth_valid_total`: Total number of requests with a valid authorization header.
- `vicarian_auth_invalid_total`: Total number of requests with an invalid or missing authorization header (for backends where it's required).