-
Documentation task
-
Resolution: Fixed
-
Trivial
-
6.0 (plan)
-
Sprint 79 (Aug 2021), Sprint 80 (Sep 2021), Sprint 81 (Oct 2021)
-
1
Introduction
There are several issues with the current documentation on functions.
Signatures are confusing
Documentation list many functions signatures that include time period, e.g.:
count (/host/key,time period<:time shift>,<operator>,<pattern>)
It is confusing that in such expressions:
time period could mean not only the time period but also the count of values . What is more, some functions allow both meanings, while some accept only either the count of values or the time period. At the moment, this information is present in the Function-specific parameters column, but there is no reason to show a user a confusing term in the function signature and then translate its meaning in the table column next, when the exact term could be provided in the function straight away.
It is actually confusing that in Function-specific parameters - the description of time period and num count changes throughout the items. It must be the same (in the footnote), the only change that can be between items is if an item accepts time period, num count or both (what would be defined by the signature). So, I propose to represent if it is a time period or num count or both in the signature of the function straight away.
Function-specific parameters column are repetitive
The sentences like that in aggregate function docs:
Time shift (optional) allows to move the evaluation point back in time.
are repeated for every time and pollute the text. Such repetitions must be moved in the footnote (or somewhere else) and be referenced.
It is not clear if time shift works with num count
Updated signature would also help to explain if time shift works with num count or not (as far as I see such information is not present at the moment). Examples must mention that as well.
Confusing information on what happens when there are not enough values
Footnote does not provide a good explanation on how functions behave when there are not enough values. It needs to be updated to include such information..
Change 1
Update signatures for aggregate functions :
avg (/host/key,time period<:time shift>) => avg (/host/key,(time period|num count)<:time shift>) kurtosis (/host/key,time period<:time shift>) => kurtosis (/host/key,(time period|num count)<:time shift>)
...
and all remaninig aggreagte functions in the same way.
Change 2
Update examples for aggregate functions :
Examples for average function should be representative enough to update all examples in aggregate functions:
Update examples:
avg(/host/key,1h) → average value1 for an hour => avg(/host/key,1h) → average value1 for the last hour until now ⇒ avg(/host/key,1h:now-1d) → average value for an hour one day ago => ⇒ avg(/host/key,1h:now-1d) → average value for an hour from 25 hours ago from now until 24 hours ago from now
Add example:
⇒ avg(/host/key,#3:now-1d) → average value of the three latest values excluding values received in the last 24 hours
Change 2
Update signatures for historic functions :
Functions that accept both time period and num count
count (/host/key,time period<:time shift>,<operator>,<pattern>) => count (/host/key,(time period|num count)<:time shift>,<operator>,<pattern>) countunique (/host/key,time period<:time shift>,<operator>,<pattern>) => countunique (/host/key,(time period|num count)<:time shift>,<operator>,<pattern>) find find (/host/key,<time period<:time shift>>,<operator>,<pattern>) => find (/host/key,(time period|num count)<:time shift>>,<operator>,<pattern>) percentile (/host/key,time period<:time shift>,percentage) => percentile (/host/key,(time period|num count)<:time shift>,percentage)
Functions that accept only the time period do not need to be changed
first,fuzzytime,nodata,trendavg,trendcount,trendmax,trendmin,trendsum
Functions that accept only the num count
last (/host/key,<time period<:time shift>>) => last (/host/key,<num count<:time shift>>) logeventid (/host/key,<time period<:time shift>>,<pattern>) => logeventid (/host/key,<num count<:time shift>>,<pattern>) logseverity (/host/key,<time period<:time shift>>) => logseverity (/host/key,<num count<:time shift>>) logsource (/host/key,<time period<:time shift>>,<pattern>) => logsource (/host/key,<num count<:time shift>>,<pattern>)
Change 3
Update signatures for prediction functions :
Functions that accept both time period and num count
forecast (/host/key,time period<:time shift>,time,<fit>,<mode>) => forecast (/host/key,(time period|num count)<:time shift>,time,<fit>,<mode>) timeleft (/host/key,time period<:time shift>,threshold,<fit>) => timeleft (/host/key,(time period|num count)<:time shift>,threshold,<fit>)
Change 4
Update footnotes for aggregate functions, history functions and prediction functions :
1 The function is evaluated starting with the first received value (unless the time shift parameter is used), i.e. Zabbix will not wait for all the values within the defined evaluation period before evaluating the function.
->
The function 1.1) for time_period parameter - takes all the values between now and "now - time_period" (or if time shift is used: between "now - time_shift" and "now - time_shift -time_period") 1.2) for num_count parameter- takes NO MORE THAN num_count of values from the past starting from now 2) if there are 0 available values for the time_period or num_count specified - then trigger or calculated item that uses this function becomes unsupported
Change 5
Update Function-specific parameters column in aggregate functions, history functions and prediction functions to avoid repetitions :
time period - maximum evaluation period1 in seconds (time suffixes can be used) or in latest collected values (if preceded by a hash mark) Time shift (optional) allows to move the evaluation point back in time.
=>
time period^3
num count^4
And then put in the footnote and reference from there:
time period^3 - maximum evaluation period in seconds (time suffixes can be used) num count^4 - latest collected values (if preceded by a hash mark)
