Calculates percentiles over a given collection of numbers.
Parameter | Type | Required | Default Value | Description |
---|---|---|---|---|
accuracy | double | optional[a] | 0.01 | Provided as a relative error threshold. Can be between >0 and <1: values closer to 1 means lower accuracy, values closer to 0 means higher accuracy. |
as | string | optional[a] | Prefix of output fields. | |
field [b] | string | required | Specifies the field for which to calculate percentiles. The field must contain numbers. | |
percentiles | Array of numbers | optional[a] | [50, 75, 99] | Specifies which percentiles to calculate. |
[a] Optional parameters use their default value unless explicitly set. |
Hide omitted argument names for this function
Omitted Argument NamesThe argument name for
field
can be omitted; the following forms of this function are equivalent:logscalepercentile("field")
and:
logscalepercentile(field="field")
These examples show basic structure only.
A percentile is a comparison value between a particular value and the values of the rest of a group. This enables the identification of scores that a particular score surpassed. For example, with a value of 75 ranked in the 85th percentile, it means that the score 75 is higher than 85% of the values of the entire group. This can be used to determine threshold and limits for triggering events or scoring probabilities and threats.
For example, given the values 12, 25, 50 and 99, the 50th percentile would be 25.79. That is, a value above 25.79 would be higher than 50% of the values.
The function returns one event with a field for each of the percentiles
specified in the percentiles
parameter. Fields are named like by prepending
_ to the values specified in the
percentiles
parameter. For
example the event could contain the fields
_50,
_75 and
_99.
The following conditions apply when using this function:
The function only works on non-negative input values.
The
accuracy
argument specifies the accuracy of the percentile relative to the number estimated and is intended as a relative error tolerance (lower values implies a better accuracy). Some examples:An
accuracy
of0.001
means that the percentiles are accurate to 0.1% of the actual value.For example, with an original value of 1000 the value would be betwen 999 and 1001 (
1000-1000/1000
and (1000+1000/1000
)).An
accuracy
of0.01
means accuracy to 1/100 of the original value.For example, with an original value of 1000 the value between 990 and 1010 ((
1000-1000/100
and (1000+1000/100
)).With an original value of 500 the value would be between 495 and 505 ((
500-500/100
and500+500/100
)).
Any query that does not explicitly set the
accuracy
parameter may see a change in the reported percentile. Specifically, thepercentile()
function may deviate by up to one 100th of the true percentile, meaning that if a given percentile has a true value of1000
, the function may report a percentile in the range of[990; 1010]
.
Important
Higher accuracy
implies
a high memory usage. Be careful to choose the accuracy for the kind of
precision they need from the expected output value. Lower percentiles
are discarded if the memory usage becomes too high. If your percentiles
seems off, try reducing the accuracy.
percentile()
Examples
Calculate the 50th,75th,99th and 99.9th percentiles for events with the field responsetime:
percentile(field=responsetime, percentiles=[50, 75, 99, 99.9])
In a timechart, calculate percentiles for both of the fields r1 and r2.
timechart(function=[percentile(field=r1,as=r1),percentile(field=r2,as=r2)])
To calculate the median for a given value, use
percentile()
with
percentiles
set to
50
:
percentile(field=allocBytes,percentiles=[50],as=median)
This creates the field median_50 with the 50th percentile value.