#
# Copyright Shohei Tanaka(@xcir)  (c) 2018.
# https://github.com/xcir/libvmod-xcounter/
#

$Module xcounter 3 Xcounter VMOD
$ABI vrt

DESCRIPTION
===========

vmod_xcounter enables custom counter in Varnish.

For example, count to the number of requests per domain.

vcl sample:
::

  import xcounter;

  sub vcl_init {
    new example_net = xcounter.vsc();
  }

  sub vcl_recv {
    if(req.http.host ~ "^example\.net$"){
      example_net.incr(1);
    }
  }

varnishstat output
::

  $ sudo varnishstat -1 -f "XCNT*"
  XCNT.reload_20181118_042545_24957.example_net.val            1          .   xcounter

ATTENTION
===========

The counter is linked to the VCL.

Add new entry per new(reload) VCL.

$Event event_function

$Function DURATION  elapsed(PRIV_VCL)

Description
	Get elapsed time.
Example
	if(xcnt.elapsed() > 1s){...}

$Object vsc(PRIV_VCL, ENUM {bitmap, bytes, duration, integer} format=integer, ENUM {bitmap, counter, gauge} type=counter, ENUM {info, debug, diag} level=info, STRING oneliner="xcounter", BOOL hidecold=1, BOOL hidevclname=0, STRING groupname="")

Description
	Create a counter.
	
	Counter name format
	::

		XCNT.boot.group.object.val
		("XCNT.%s.%s%s.val", vclname, groupname, objectname)

	``format``
	Counter format.

	``type``
	Counter type.

	``level``
	Counter level.

	``oneliner``
	Counter description.

	``hidecold``
	Hide counter, if state of vcl becomes cold.

	``hidevclname``
	Do not include vclname(boot,reload... etc) in counter name, if set to true.
	
	``groupname``
	Add group name.

Example
	new xcnt = xcounter.vsc();

$Method VOID .incr(INT d, BOOL threadsafe=1)

Description
	Increment vlaue.

	Negative values are ignored

Example
	xcnt.incr(1);

$Method VOID .decr(INT d, BOOL threadsafe=1)

Description
	Decrement value.

	Negative values are ignored.

Example
	xcnt.decr(1);

$Method VOID .set(INT)

Description
	Set value.

Example
	xcnt.set(1024);

$Method INT  .get()

Description
	Get current value.
Example
	if(xcnt.get() > 1024){...}