Coupled Statistics

Use coupled statistics for quantities that are related and therefore must be updated jointly.

As a very simple example, suppose you have three statistics: sum, part_1, and part_2. They must always preserve the relationship that sum = part_1 + part_2. If you update part_1 without updating sum at the same time, then the equation becomes untrue. Therefore, the statistics are said to be coupled.

The mechanism for updating coupled statistics jointly is to create local copies of global coupled statistics in the routines that modifiy them. When each local copy is updated appropriately, do a global update using INKStatsCoupledUpdate. To specify which statistics are related to one another, establish a coupled statistic category and make sure that each coupled statistic belongs to the appropriate category. When it is time to do the global update, specify the category to be updated.

	Note
	The local statistic copy must have a duplicate set of statistics as that of the master copy. Local statistics must also be added to the local statistic category in the same order as their master copy counterparts were originally added.

Below are the steps you need to follow, along with a code example taken from the redirect-1.c sample plugin.

To add coupled statistics:

Declare the global category for your coupled statistics as a global INKCoupledStat variable in your plugin.
Declare your coupled statistics as global INKStat variables in your plugin.
In INKPluginInit, create a new global coupled category using INKStatCoupledGlobalCategoryCreate.
In INKPluginInit, create new global coupled statistics using INKStatCoupledGlobalAdd.

When you create a new statistic, you need to give it an “external” name that the Traffic Server command line interface (Traffic Line) uses to access the statistic.
In any routine wherein you want to modify (increment, decrement, or other modification) your coupled statistics, declare local copies of the coupled category and coupled statistics.
Create local copies using INKStatCoupledLocalCopyCreate and INKStatCoupledLocalAdd.
Modify the local copies of your statistics. Then call INKStatsCoupledUpdate to update the global copies jointly.
When you are finished, you must destroy all of the local copies in the category via INKStatCoupledLocalCopyDestroy.

Example Using the redirect-1.c Sample Plugin

static INKCoupledStat request_outcomes;

static INKStat requests_all;
static INKStat requests_redirects;
static INKStat requests_unchanged;

request_outcomes = INKStatCoupledGlobalCategoryCreate ("request_outcomes"); 

requests_all = INKStatCoupledGlobalAdd (request_outcomes, "requests.all", INKSTAT_TYPE_FLOAT);
requests_redirects = INKStatCoupledGlobalAdd (request_outcomes, "requests.redirects",
    INKSTAT_TYPE_INT64);
requests_unchanged = INKStatCoupledGlobalAdd (request_outcomes, "requests.unchanged", 
    INKSTAT_TYPE_INT64);

INKCoupledStat local_request_outcomes;
INKStat local_requests_all;
INKStat local_requests_redirects;
INKStat local_requests_unchanged;

local_request_outcomes = INKStatCoupledLocalCopyCreate("local_request_outcomes", 
    request_outcomes); 
local_requests_all = INKStatCoupledLocalAdd(local_request_outcomes, "requests.all.local", 
    INKSTAT_TYPE_FLOAT);
local_requests_redirects = INKStatCoupledLocalAdd(local_request_outcomes, 
    "requests.redirects.local", INKSTAT_TYPE_INT64);
local_requests_unchanged = INKStatCoupledLocalAdd(local_request_outcomes, 
    "requests.unchanged.local", INKSTAT_TYPE_INT64);

INKStatFloatAddTo( local_requests_all, 1.0 ) ; 
...
INKStatIncrement (local_requests_unchanged); 
INKStatsCoupledUpdate(local_request_outcomes); 

INKStatCoupledLocalCopyDestroy(local_request_outcomes);

Traffic Server Software Developers Kit