Stat (Prometheus)

Description

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.

Examples

Simple configuration

Here’s a VCL example to expose prometheus metrics, only showing uptime and hit counters:

import stat;

sub vcl_recv {
    if (req.url == "/metrics") {
        return (pass);
    }
}

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

More advanced configuration

Here’s a VCL example to expose prometheus metrics, only showing uptime and hit counters. The client IP is matched against an ACL, the the content is gzipped to reduce network transfer and the object is cached for a second to reduce the load if there are many requests:

import stat;
acl prometheus {
    # IP address(es) of the clients to accept
    "192.168.0.1"/32;
}
sub vcl_recv {
    if (req.url == "/metrics") {
        if (client.ip !~ prometheus) {
            return(synth(403));
        }
    }
}
sub vcl_backend_fetch {
    if (bereq.url == "/metrics") {
        set bereq.backend = stat.backend_prometheus("MAIN.uptime, *.g_bytes");
    }
}
sub vcl_backend_response {
    if (bereq.url == "/metrics") {
        set beresp.do_gzip = true;
        set beresp.ttl = 1s;
        set beresp.grace = 1s;
        set beresp.http.cache-control = "max-age=1, must-revalidate";
    }
}

:

API

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_json

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

Restricted to: backend

string_json

STRING string_json(STRING filter)

Returns a JSON collection of counters based on the provided filter(s).

Arguments:

• filter accepts type STRING

Type: Function

Returns: String

Restricted to: backend

backend_prometheus

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

Restricted to: backend

get_value

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 STRING

Type: Function

Returns: Int

add_filter

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 accounting

Type: Function

Returns: None

Restricted to: backend

remove_filters

VOID remove_filters()

Removes filters applied with add_filter(). Can only be called from a backend context.

Arguments: None

Type: Function

Returns: None

Restricted to: backend

Availability

The stat VMOD is available in Varnish Enterprise version 6.0.8r2 and later.