SearchVarnish Enterprise
The stat vmod provides access to Varnish counters via backends, to expose them through HTTP and
cache, compress and manipulate the responses as any cached content.
Please note the prometheus output of this vmod is still subject to change. It is expected that the API of this vmod will not be changed.
Here’s a VCL example to expose prometheus metrics, only showing uptime and hit counters:
import stat;
import acl;
backend default none;
acl allowed_scraper {
"10.0.0.10"/32;
}
sub vcl_recv {
if (req.url == "/metrics") {
if (client.ip ~ allowed_scraper ) {
return(pass);
} else {
return(synth(403));
}
}
...
}
sub vcl_backend_fetch {
if (bereq.url == "/metrics") {
set bereq.backend = stat.backend_prometheus("MAIN.uptime, *.g_bytes");
}
}
With it, metrics can be pulled from the usual /metrics path:
$ curl http://localhost:6081/metrics -v
# HELP varnish_uptime Child process uptime
# TYPE varnish_uptime counter
varnish_uptime{host="varnish1",section="MAIN"} 0
# HELP varnish_s0_g_bytes Bytes outstanding
# TYPE varnish_s0_g_bytes gauge
varnish_s0_g_bytes{host="varnish1",section="SMA"} 2941248
# HELP varnish_Transient_g_bytes Bytes outstanding
# TYPE varnish_Transient_g_bytes gauge
varnish_Transient_g_bytes{host="varnish1",section="SMA"} 2244
In the file, /etc/prometheus/prometheus.yml, the prometheus scraper configuration
will contain these lines:
...
scrape_configs:
- job_name: varnish-edge-node
metrics_path: /metrics
scheme: http
static_configs:
- targets: ["varnish1:6081"]
...
Metrics can be pulled from the prometheus endpoint, as shown here:
$ curl http://your_prometheus_host:9090/metrics -v
# HELP varnish_uptime Child process uptime
# TYPE varnish_uptime counter
varnish_uptime{host="varnish1",section="MAIN"} 0
...
Some restrictions is in place so that information is only accessible to
select metric scraper node. Notice that, in the example, another vmod is used altogether
to allow 1 IP address to request /metrics.
Some functions accept a filters argument, which is a comma-separated
STRING to include or exclude certain counters. Each element is interpreted
like a varnishstat -f argument, meaning words starting with ^ will exclude
matching counters.
BACKEND backend_json(STRING filters = 0)
Produce a JSON object containing the format version (1) as well a counters
object listing all the objects as varnishstat -j does.
Can only be called from a backend context (such as sub vcl_backend_fetch).
{
"version": 1,
"counters": {
"MGT.uptime": {
"description": "Management process uptime",
"flag": "c",
"format": "d",
"value": 0
},
"MGT.child_start": {
"description": "Child process started",
"flag": "c",
"format": "i",
"value": 1
},
...
Arguments:
filters accepts type STRING with a default value of 0 optional
Type: Function
Returns: Backend
STRING string_json(STRING filter)
Returns a JSON collection of counters based on the provided filter(s).
Arguments:
filter accepts type STRINGType: Function
Returns: String
BACKEND backend_prometheus(STRING filters = 0, BOOL hostnames = 1, INT resolution = 64)
Output a prometheus-compatible list of counters. Can only be called from
a backend context (such as sub vcl_backend_fetch). The hostnames parameter denotes
whether to include the hostname of the device in the prometheus output.
The resolution parameter allows you to specify a maximum output resolution in
bits for bitmap counters. Accepts integer from 1 to 64. The default is 64 which
denotes the full bitmap resolution.
$ curl http://localhost:6081/metrics -v
# HELP varnish_main_uptime Child process uptime (MAIN.uptime)
# TYPE varnish_main_uptime counter
varnish_main_uptime{host="varnish1"} 0
# HELP varnish_sma_g_bytes Bytes outstanding (SMA.s2.g_bytes)
# TYPE varnish_sma_g_bytes gauge
varnish_sma_g_bytes{id="s2",host="varnish1"} 2941248
# HELP varnish_sma_g_bytes Bytes outstanding (SMA.Transient.g_bytes)
# TYPE varnish_sma_g_bytes gauge
varnish_sma_g_bytes{id="Transient",host="varnish1"} 2244
Arguments:
filters accepts type STRING with a default value of 0 optional
hostnames accepts type BOOL with a default value of 1 optional
resolution accepts type INT with a default value of 64 optional
Type: Function
Returns: Backend
INT get_value(STRING name)
Returns the integer value of a given counter. A value of -1 signifies an error or a failure to find a match. If a value exceeds the integer maximum limit it will be clamped to the integer max limit.
Arguments:
name accepts type STRINGType: Function
Returns: Int
VOID add_filter(ENUM {vcl, accounting} filter)
Filter backend_prometheus output based on label filters. Multiple filters
can be used by calling add_filter again. Can only be called from a backend context.
vcl Filter counters based on current VCL name.
accounting Filter counters based on current accounting namespace.
Arguments:
filter is an ENUM that accepts values of vcl, and accountingType: Function
Returns: None
VOID remove_filters()
Removes filters applied with add_filter(). Can only be called from a backend context.
Arguments: None
Type: Function
Returns: None
The stat VMOD is available in Varnish Enterprise version 6.0.8r2 and later.