Author

Xavier Basty

Date

2012-09-24

Version

1.0

Manual section

3

Varnish Module (vmod) to get weighted random values for A/B testing, with a dynamic configuration.

import abtest;

abtest.set_rule(<key>, <rule>)
abtest.rem_rule(<key>)
abtest.clear()

abtest.load_config(<path>)
abtest.save_config(<path>)

abtest.get_rand(<key>)
abtest.get_rules()
abtest.get_duration(<key>)
abtest.get_expire(<key>)

Prototype

set_rule(STRING key, STRING rule)

Return value

VOID

Description

Set the rule associated with the specified key.

The format for the rule declaration is:

<option1>:<weight1>;<option2>:<weight2>;...;[duration];

The weights are relative to each others, so sum of all the weight is considered equals to 100%.

The duration is optional, if it is not present, it is set to 0.

Example

abtest.set_rule("^/repec/cgi-bin/authorref.cgi\?handle=", "a:80;b:20;300;");
abtest.set_rule(".*", "a:60;b:40"); // default rule

Prototype

rem_rule(STRING)

Return value

VOID

Description

Remove the rule associated with the specified key.

If the rule doesn't exist in the configuration, the function does nothing and returns without errors.

Example

abtest.rem_rule("^/repec/cgi-bin/authorref.cgi\?handle=");

Prototype

clear()

Return value

VOID

Description

Remove all the rules from the current configuration.

Example

abtest.clear();

Prototype

load_config(STRING path)

Return value

INT

Description

On successful completion, the load_config() function returns 0. Otherwise, it returns an integer value indicating the error that occured and the content of the current configuration remains unchanged.

If an active configuration is already present, it is overwritten when the file is loaded successfully.

See configuration file for information on the file format.

Example

if (abtest.load_config("abtest.cfg") != 0) {
        std.log("Could not load the configuration file!");
}

Prototype

save_config(STRING path)

Return value

INT

Description

On successful completion, the save_config() function returns 0. Otherwise, it returns an integer value indicating the error that occured.

If the current configuration is uninitialized, the function returns immediatly and does not overwrite the configuration file.

See configuration file for information on the file format.

Example

if (abtest.save_config("abtest.cfg") != 0) {
        std.log("Could not save the configuration file!");
}

Prototype

get_rand(STRING key)

Return value

STRING

Description

Returns one of the options in the specified rule, the option is chosen with the random weights declared in the rule.

If the rule is not present in the current configuration, the function returns NULL.

Example

set resp.http.Set-Cookie = "abtesting=" + abtest.get_rand(req.url);

Prototype

get_rules()

Return value

STRING

Description

Returns a list of all the rules present in the current configuration.

The format of the rule returned is the same as in the configuration file, but with the rule separated with spaces instead of new lines.

Example

set resp.http.X-AB-Rules = abtest.get_rules();

Prototype

get_duration(<key>)

Return value

DURATION

Description

Return the configured cookie duration for the specified rule.

If the duration is not set in the rule, or if the rule does not exist in the configuration, the function returns 0;

Prototype

get_expire(<key>)

Return value

STRING

Description

Return a time string computed from the current time plus the declared duration to use in the èxpire` part of the cookie.

Example

set resp.http.Set-Cookie = "abtesting=" + abtest.get_rand(req.url) + "; path=/; expires=" + abtest.get_expire(req.url);

The configuration is saved as an ASCII file with each rule on a separate line in the following format:

<rule_name_1>:<option>:<weight>;<option>:<weight>;...;[duration];
<rule_name_2>:<option>:<weight>;<option>:<weight>;...;[duration];

At least one pair option/weight must be declared for a rule to be valid.

The duration is optional, if it is not set, its value is set to 0.

The source tree is based on autotools to configure the building, and does also have the necessary bits in place to do functional unit tests using the varnishtest tool.

Usage:

./configure VARNISHSRC=DIR [VMODDIR=DIR]

VARNISHSRC is the directory of the Varnish source tree for which to compile your vmod. Both the VARNISHSRC and VARNISHSRC/include will be added to the include search paths for your module.

Optionally you can also set the vmod install directory by adding VMODDIR=DIR (defaults to the pkg-config discovered directory from your Varnish installation).

Make targets:

• make - builds the vmod
• make install - installs your vmod in VMODDIR
• make check - runs the unit tests in src/tests/*.vtc

In your VCL you could then use this vmod along the following lines:

import abtest;

sub vcl_deliver {
        set resp.http.Set-Cookie = "abtesting=" + abtest.get_rand("base");
}

The general structure is inspired from the example vmod and many others.

The weighted random function is originally from Sergiy Dzysyak

Version 0.1: Initial version.

• varnishd(1)
• vcl(7)
• https://github.com/Destination/libvmod-abtest

This document is licensed under the same license as the libvmod-abtest project. See LICENSE for details.

• Copyright (c) 2012 Destinationpunktse AB