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
  • MEASURE_PAGE_ACTIONTIME
  • 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;