MeasureCalculateRawPercentiles Function

Action

Enables the collection of quantile data for the measure identified by sName and nClass. Collected quantile data is shown in the overview report.

This function can be used before a measure is created and/or used, and must be located in the TInit transaction.

Due to memory limitations, Silk Performer does not collect absolute measurements. Instead, a limited set of categories is created and Silk Performer counts how often a certain category is hit. The size of a category is 1 millisecond for small measurements, for bigger measurements the upper boundary of the categories increases. To calculate the upper boundaries, the following formula is used (B stands for boundary):

B(n) = B(n-1) x (1+uGranularity)

This is the whole formula:

B(1) = 1ms
B(n) = max(B(n-1) + 1ms, B(n-1) x (1+uGranularity))

For example: If the granularity is 1 percent and the upper boundary of a certain category is 1000 milliseconds, the next category will range from 1000 to 1010 milliseconds.

The maximum error of a measurement of 1000 milliseconds is 1 percent or 10 milliseconds.

Include file

Kernel.bdh

Syntax

MeasureCalculateRawPercentiles( in sName        : string allownull,
                                in nClass       : number,
                                in bDisable     : boolean optional,
                                in uGranularity : number optional ): boolean;

Return value

true if successful
false otherwise

Parameter	Description
sName	Measure name that identifies the measure. When this parameter is set to NULL or "", quantile data collection is enabled for all measures of the provided measure type.
nClass	Specifies the type of measure to retrieve. To retrieve the value of a custom time measure, pass the MEASURE_TIMER_RESPONSETIME parameter to the function. To retrieve the value of a custom counter, pass the MEASURE_COUNTER_CUSTOMCOUNTER parameter to the function. To retrieve the value of an average counter, pass the MEASURE_COUNTER_AVERAGE parameter to the function. In any other case, pass any of the following parameters to the function, depending on the type of information you are interested in. MEASURE_PAGE_PAGETIME (for protocol-level load testing) MEASURE_PAGE_ACTIONTIME (for browser-driven load testing) MEASURE_PAGE_PAGEBYTES MEASURE_PAGE_EMBEDDEDBYTES MEASURE_PAGE_DOCDOWNLOAD MEASURE_PAGE_SERVERBUSY MEASURE_IIOP_ROUNDTRIP MEASURE_IIOP_SERVERBUSY MEASURE_SQL_SQLPARSE MEASURE_SQL_SQLEXEC MEASURE_SQL_SQLEXECDIRECT MEASURE_TRANS_TRANSOK MEASURE_TRANS_TRANSERR MEASURE_TRANS_TRANSCA MEASURE_FORM_BYTESSENT MEASURE_FORM_BYTESRECEIVED MEASURE_FORM_HITSOK MEASURE_FORM_HITSERR MEASURE_FORM_ROUNDTRIP MEASURE_FORM_SERVERBUSY MEASURE_TUXEDO_BYTESSENT MEASURE_TUXEDO_BYTESRECEIVED MEASURE_TUXEDO_RESPONSETIME
bDisable	Optional: Specifies whether percentiles calculation should be disabled or enabled (default is `FALSE`).
uGranularity	Optional: Precision of the quantile measurement in per mil. Can be one of the following values: OPT_PERCENTILES_GRANULARITY_1_PER_MIL OPT_PERCENTILES_GRANULARITY_3_PER_MIL OPT_PERCENTILES_GRANULARITY_5_PER_MIL OPT_PERCENTILES_GRANULARITY_10_PER_MIL OPT_PERCENTILES_GRANULARITY_30_PER_MIL OPT_PERCENTILES_GRANULARITY_50_PER_MIL Lower granularity enables a more precise percentile calculation, but consumes more memory on each agent computer. The default setting of OPT_PERCENTILES_GRANULARITY_10_PER_MIL (1 percent) consumes up to 8kb memory per measure and virtual user container executable. Important: With lower granularity settings, memory consumption grows exponentially.

Example

benchmark MeasureBenchmarkName
use "kernel.bdh" 

dclrand
  r2 : RndUniF(5.0..55.0);

dcluser
  user
    User1
  transactions
    TInit        : begin;
    TMain        : 1;

dcltrans
  transaction TInit
  begin
    // enable quantile data for a custom measure
    MeasureCalculateRawPercentiles("measure1", MEASURE_COUNTER_CUSTOMCOUNTER, 
    false, OPT_PERCENTILES_GRANULARITY_1_PER_MIL);
  end TInit;

  transaction TMain
  var
    i      : number;
    f, fV  : float;
  begin
    // get 500 random numbers in the range of 5.0 to 55.0
    for i := 1 to 500 do
      MeasureSetFloat("measure1", MEASURE_COUNTER_CUSTOMCOUNTER , r2);
    end;

    // show percentile estimation for 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100%
    f:= 0.1;
    while f < 1.01 do
      MeasureGetPercentile("measure1", MEASURE_COUNTER_CUSTOMCOUNTER, f, fV);
      Print(string(f) + " = " + string(fV));
      f := f + 0.1;
    end;
  end TMain;