See www.zabbix.com for the official Zabbix site.

Docs/specs/ZBXNEXT-2128

From Zabbix.org
Jump to: navigation, search

Execution of item at a specific time

ZBXNEXT-2128

Status: v1.2

Owner: Alexei, Sasha

Summary

Currently Zabbix does not support scheduling for items. It would be nice to support at least daily, hourly and weekly retrieval of values at specific times, say, every hour daily at hh:00 minutes.

Specification

Scheduling interval consists of a list of time unit filters:

 md<filter>wd<filter>h<filter>m<filter>s<filter>

Each filter definition is optional, but at least one filter must be defined.

The characters before filter defines its time units:

 md - month days
 wd - week days
 h - hours
 m - minutes
 s - seconds

The filter is defined as [<from>[-<to>]][/<step>][,<filter>] where <from> and <to> defines the range of matching values (included). If the <to> definition is omitted then the filter defaults to <from>-<from> range. If also the <from> definition is omitted then the filter matches all possible values for its time unit.

<step> skips of the number's value through the range. By default <step> has value 1, meaning all values of the defined range are matched.

A filter must have either range or the <step> value defined.

The <from> and <to> values are limited by the their time unit range:

Time unit <from> <to>
Month days 1-31 1-31
Week days 1-7 1-7
Hours 0-23 0-23
Minutes 0-59 0-59
Seconds 0-59 0-59

The <from> value must be less or equal to <to> value.

The <step> value must be greater or equal to 1 and less or equal to <to>-<from>.

Single digit month days, hours, minutes and seconds values can be prefixed with 0. For example md01-31 and h/02 are valid intervals, but md01-031 and wd01-07 is not.

Undefined filters for time units larger than the smallest defined unit match the full range of the respective time unit. However, undefined filters for smaller time units match only the value 0. Note that month day and week day units have the same priority.

For example:

Defined Expanded
h9-18 md1-31wd1-7h9-18m0s0
wd1m30 md1-31wd1h0-23m30s0

Scheduling interval definition in EBNF notation:

SchedulingInterval ::= MonthDayFilter? WeekDaysFilter? HourFilter? MinuteFilter? SecondFilter?
MonthDayFilter ::= 'md' Filter
WeekDaysFilter ::= 'wd' Filter
HourFilter ::= 'h' Filter
MinuteFilter ::= 'm' Filter
SecondFilter ::= 's' Filter
Filter ::= (From ('-' To ('/' Step)?)? | ('/' Step))  (',' Filter)*
From ::= [0-9+]
To ::= [0-9+]
Step ::= [0-9+]

Examples:

 m0-59 - every minute
 h9-17/2 - execute every 2 hours starting with 9:00 (9:00, 11:00 ...)
 m0,30 or m/30 - execute hourly at hh:00 and hh:30
 m0,5,10,15,20,25,30,35,40,45,50,55 or m/5 - every five minutes
 wd1-5h9 - every Monday till Friday at 9:00
 wd1-5h9-18 - every Monday till Friday at 9:00,10:00,...,18:00
 h9,10,11 or h9-11 - every day at 9:00, 10:00 and 11:00
 md1h9m30 - every 1st day of each month at 9:30
 md1wd1h9m30 - every 1st day of each month at 9:30 if it is Monday
 h9m/30 - execute at 9:00, 9:30
 h9m0-59/30 - execute at 9:00, 9:30
 h9,10m/30 - execute at 9:00, 9:30, 10:00, 10:30
 h9-10m30 - execute at 9:30, 10:30
 h9m10-40/30 - execute at 9:10, 9:40
 h9,10m10-40/30 - execute at 9:10, 9:40, 10:10, 10:40
 h9-10m10-40/30 - execute at 9:10, 9:40, 10:10, 10:40
 h9m10-40 - execute at 9:10, 9:11, 9:12, ... 9:40
 h9m10-40/1 - execute at 9:10, 9:11, 9:12, ... 9:40
 h9-12,15 - execute at 9:00, 10:00, 11:00, 12:00, 15:00
 h9-12,15m0 - execute at 9:00, 10:00, 11:00, 12:00, 15:00
 h9-12,15m0s0 - execute at 9:00, 10:00, 11:00, 12:00, 15:00
 h9-12s30 - execute at 9:00:30, 10:00:30, 11:00:30, 12:00:30
 h9m/30;h10 - execute at 9:00, 9:30, 10:00


The intervals can be joined using ';' delimiter: wd1-5h9;md1h9m30

In case if new scheduling intersects with interval-based one, both will be executed. For example: if interval is set to 60 seconds and there is a schedule defined as 'h9', then the item will be executed every minute in addition to execution exactly at 9:00 daily.

In case if a time is matched my serveral intervals it is executed only once.For example, "wd1h9;h9" will be executed only once on Monday at 9am.

Front-end changes

  • New validation for flexible intervals. The front-end will complain if size of items.delay_flex exceeds 255 characters.
  • Configuration->Items
    • Delay=0 must be allowed with scheduling intervals as well as it is currently with flexible
    • New field after 'New flexible interval', similar table to existing 'Flexible intervals'
 Schedule
   Execute at       Action
   wd1-5h/4         Remove
  • New field after 'Schedules':
 New schedule Execute at [wd1-5h9-18]   [Add]

When button 'Add' is pressed, the new schedule is validated and added to the list of schedules. If it is not valid, 'Incorrect schedule "<string>"' will be displayed.

Flexible intervals and schedule times are stored in items.delay_flex delimited by ';'.

Server

  • Zabbix server poller processes should process new format of flexible intervals

API changes

  • New validation for flexible intervals. The API will complain if size of items.delay_flex exceeds 255 characters.

Translation strings

  • Schedules
  • New schedule
  • Execute at
  • Incorrect schedule %s

Documentation

  • What's new
  • Zabbix Manual
    • Item configuration including screenshots
    • Training materials

Other decisions

  • support of flexible intervals for active checks is out of scope and will be handled under ZBXNEXT-693
  • existing format for flexible delays will be preserved

To be decided

  • Should be supported by LLD rules and item prototypes (yes, should be no difference from flexible checks)
  • To make the item configuration form more organized, I suggest moving delay, flexible intervals and schedules to a separate tab, like "Scheduling" or something
  • Use cron format? (no)
  • Adding spaces (no, possible space constraints)
  • Is it just me, or is it better when numbers precede letters (instead of "wd1 h2 m10" - "1wd 2h 10m")? I mean, thats how we read it: "on Monday at 2 hours and 10 minutes" (while single time units separated by spaces looks better if the numbers precede letters, with added ',' and '/' it does not look much better)
  • Supporting shortened names instead of weekday numbers (instead of "wd1-5 h1" just "Mon-Fri h1") (No, localization problems and we already have 1-5 format in flexible checks. We can add support for shortened names later (also in flexible intervals) if required.)
  • DST handling


ChangeLog

  • v1.1 - added filter value range table, added better default filter value explanation, corrected filter step description.
  • v1.2 - limited <step> maximum value to the range value, single digit values (except week days) can be prefixed with 0