Skip to content

Commit 1d4c8d8

Browse files
lukewhitingdakrone
lukewhiting
and
dakrone
authored
(elastic#34659) - Add Timezone Configuration to Watcher (elastic#117033)
* Add timezone support to Cron objects * Add timezone support to CronnableSchedule * XContent change to support parsing and display of TimeZone fields on schedules * Case insensitive timezone parsing * Doc changes * YAML REST tests * Equals, toString and HashCode now include timezone * Additional random testing for DST transitions * Migrate Cron class to use wrapped LocalDateTime The algorithm depends on some quirks of calendar but LocalDateTime correctly ignores DST during calculations so this uses a LocalDateTime with a wrapper to emulate some of Calendar's behaviours that the Cron algorithm depends on * Additional documentation to explain discontinuity event behaviour * Remove redundant conversions from ZoneId to TimeZone following move to LocalDateTime * Add documentation warning that manual clock changes will cause unpredictable watch execution * Update docs/reference/watcher/trigger/schedule.asciidoc Co-authored-by: Lee Hinman <[email protected]> --------- Co-authored-by: Lee Hinman <[email protected]>
1 parent fbc6abe commit 1d4c8d8

File tree

20 files changed

+975
-173
lines changed

20 files changed

+975
-173
lines changed

‎docs/reference/watcher/example-watches/watching-time-series-data.asciidoc‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -62,20 +62,20 @@ contain the words "error" or "problem".
6262

6363
To set up the watch:
6464

65-
. Define the watch trigger--a daily schedule that runs at 12:00 UTC:
65+
. Define the watch trigger--a daily schedule that runs at 12:00 Australian Eastern Standard Time (UTC+10:00):
6666
+
6767
[source,js]
6868
--------------------------------------------------
6969
"trigger" : {
7070
"schedule" : {
71+
"timezone": "Australia/Brisbane",
7172
"daily" : { "at" : "12:00" }
7273
}
7374
}
7475
--------------------------------------------------
7576
+
76-
NOTE: In {watcher}, you specify times in UTC time. Don't forget to do the
77-
conversion from your local time so the schedule triggers at the time
78-
you intend.
77+
NOTE: In {watcher}, if the timezone is omitted then schedules default to UTC. `timezone` can be specified either
78+
as a +/-HH:mm offset from UTC or as a timezone name from the machines local IANA Time Zone Database.
7979

8080
. Define the watch input--a search that uses a filter to constrain the results
8181
to the past day.

‎docs/reference/watcher/trigger/schedule.asciidoc‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,42 @@
66
++++
77

88
Schedule <<trigger,triggers>> define when the watch execution should start based
9-
on date and time. All times are specified in UTC time.
9+
on date and time. All times are in UTC time unless a timezone is explicitly specified
10+
in the schedule.
1011

1112
{watcher} uses the system clock to determine the current time. To ensure schedules
1213
are triggered when expected, you should synchronize the clocks of all nodes in the
1314
cluster using a time service such as http://www.ntp.org/[NTP].
1415

16+
NOTE: {watcher} can't correct for manual adjustments to the system clock. Be aware when making
17+
such changes that watch execution may be affected with watches being skipped or repeated if the
18+
adjustment covers their target execution time. This applies to changes made via NTP as well.
19+
20+
When specifying a timezone for a watch, keep in mind the effect daylight savings time
21+
transitions may have on the schedule, especially if the watch is scheduled to run
22+
during the transition. Here's how {watcher} handles watches scheduled during discontinuities:
23+
24+
==== Gap Transitions
25+
These occur when the clock moves forward, such as when daylight savings time starts
26+
and cause certain hours or minutes to be skipped. If your watch is scheduled to run
27+
during a gap transition, the watch is executed at the same time as before the transition.
28+
29+
Example: If a watch is scheduled to run daily at 1:30AM in the `Europe/London` time zone and
30+
the clock moves forward one hour from 1:00AM (GMT+0) to 2:00AM (GMT+1), the watch is executed
31+
at 2:30AM (GMT+1) which would have been 1:30AM before the transition. Subsequent executions
32+
happen at 1:30AM (GMT+1).
33+
34+
==== Overlap Transitions
35+
These occur when the clock moves backward, such as when daylight savings time ends
36+
and cause certain hours or minutes to be repeated. If your watch is scheduled to run
37+
during an overlap transition, only the first occurrence of the time causes to the watch
38+
to execute with the second being skipped.
39+
40+
Example: If a watch is scheduled to run at 1:30 AM and the clock moves backward one hour
41+
from 2:00AM to 1:00AM, the watch is executed at 1:30AM and the second occurrence after the
42+
change is skipped.
43+
44+
=== Throttling
1545
Keep in mind that the throttle period can affect when a watch is actually executed.
1646
The default throttle period is five seconds (5000 ms). If you configure a schedule
1747
that's more frequent than the throttle period, the throttle period overrides the
@@ -20,6 +50,7 @@ and set the schedule to every 10 seconds, the watch is executed no more than
2050
once per minute. For more information about throttling, see
2151
<<actions-ack-throttle>>.
2252

53+
=== Schedule Types
2354
{watcher} provides several types of schedule triggers:
2455

2556
* <<schedule-hourly, `hourly`>>

‎docs/reference/watcher/trigger/schedule/cron.asciidoc‎

Lines changed: 33 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@
55
++++
66

77

8-
Defines a <<trigger-schedule, `schedule`>> using a <<api-cron-expressions, cron expression>>
8+
Defines a <<trigger-schedule, `schedule`>> using a <<api-cron-expressions, cron expression>>
99
that specifiues when to execute a watch.
1010

1111

12-
TIP: While cron expressions are powerful, a regularly occurring schedule
13-
is easier to configure with the other schedule types.
14-
If you must use a cron schedule, make sure you verify it with
15-
<<elasticsearch-croneval, `elasticsearch-croneval`>> .
12+
TIP: While cron expressions are powerful, a regularly occurring schedule
13+
is easier to configure with the other schedule types.
14+
If you must use a cron schedule, make sure you verify it with
15+
<<elasticsearch-croneval, `elasticsearch-croneval`>> .
1616

1717

1818
===== Configure a cron schedule with one time
@@ -60,16 +60,40 @@ minute during the weekend:
6060
--------------------------------------------------
6161
// NOTCONSOLE
6262

63+
[[configue_cron_time-zone]]
64+
==== Use a different time zone for a cron schedule
65+
By default, cron expressions are evaluated in the UTC time zone. To use a different time zone,
66+
you can specify the `timezone` parameter in the schedule. For example, the following
67+
`cron` schedule triggers at 6:00 AM and 6:00 PM during weekends in the `America/Los_Angeles` time zone:
68+
69+
70+
[source,js]
71+
--------------------------------------------------
72+
{
73+
...
74+
"trigger" : {
75+
"schedule" : {
76+
"timezone" : "America/Los_Angeles",
77+
"cron" : [
78+
"0 6,18 * * * SAT-SUN",
79+
]
80+
}
81+
}
82+
...
83+
}
84+
--------------------------------------------------
85+
// NOTCONSOLE
86+
6387
[[croneval]]
6488
===== Use croneval to validate cron expressions
6589

66-
{es} provides a <<elasticsearch-croneval, `elasticsearch-croneval`>> command line tool
67-
in the `$ES_HOME/bin` directory that you can use to check that your cron expressions
90+
{es} provides a <<elasticsearch-croneval, `elasticsearch-croneval`>> command line tool
91+
in the `$ES_HOME/bin` directory that you can use to check that your cron expressions
6892
are valid and produce the expected results.
6993

70-
To validate a cron expression, pass it in as a parameter to `elasticsearch-croneval`:
94+
To validate a cron expression, pass it in as a parameter to `elasticsearch-croneval`:
7195

7296
[source,bash]
7397
--------------------------------------------------
7498
bin/elasticsearch-croneval "0 0/1 * * * ?"
75-
--------------------------------------------------
99+
--------------------------------------------------

‎docs/reference/watcher/trigger/schedule/daily.asciidoc‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,3 +97,27 @@ or minutes as an array. For example, following `daily` schedule triggers at
9797
}
9898
--------------------------------------------------
9999
// NOTCONSOLE
100+
101+
[[specifying-time-zone-for-daily-schedule]]
102+
===== Specifying a time zone for a daily schedule
103+
By default, daily schedules are evaluated in the UTC time zone. To use a different time zone,
104+
you can specify the `timezone` parameter in the schedule. For example, the following
105+
`daily` schedule triggers at 6:00 AM and 6:00 PM in the `Pacific/Galapagos` time zone:
106+
107+
[source,js]
108+
--------------------------------------------------
109+
{
110+
"trigger" : {
111+
"schedule" : {
112+
"timezone" : "Pacific/Galapagos",
113+
"daily" : {
114+
"at" : {
115+
"hour" : [ 6, 18 ],
116+
"minute" : 0
117+
}
118+
}
119+
}
120+
}
121+
}
122+
--------------------------------------------------
123+
// NOTCONSOLE

‎docs/reference/watcher/trigger/schedule/monthly.asciidoc‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,4 +74,26 @@ schedule triggers at 12:00 AM and 12:00 PM on the 10th and 20th of each month.
7474
}
7575
}
7676
--------------------------------------------------
77-
// NOTCONSOLE
77+
// NOTCONSOLE
78+
79+
==== Configuring time zones for monthly schedules
80+
By default, monthly schedules are evaluated in the UTC time zone. To use a different
81+
time zone, you can specify the `timezone` parameter in the schedule. For example,
82+
the following `monthly` schedule triggers at 6:00 AM and 6:00 PM on the 15th of each month in
83+
the `Asia/Tokyo` time zone:
84+
85+
[source,js]
86+
--------------------------------------------------
87+
{
88+
"trigger" : {
89+
"schedule" : {
90+
"timezone" : "Asia/Tokyo",
91+
"monthly" : {
92+
"on" : [ 15 ],
93+
"at" : [ 6:00, 18:00 ]
94+
}
95+
}
96+
}
97+
}
98+
--------------------------------------------------
99+
// NOTCONSOLE

‎docs/reference/watcher/trigger/schedule/weekly.asciidoc‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,4 +79,26 @@ Alternatively, you can specify days and times in an object that has `on` and
7979
}
8080
}
8181
--------------------------------------------------
82-
// NOTCONSOLE
82+
// NOTCONSOLE
83+
84+
==== Use a different time zone for a weekly schedule
85+
By default, weekly schedules are evaluated in the UTC time zone. To use a different time zone,
86+
you can specify the `timezone` parameter in the schedule. For example, the following
87+
`weekly` schedule triggers at 6:00 AM and 6:00 PM on Tuesdays and Fridays in the
88+
`America/Buenos_Aires` time zone:
89+
90+
[source,js]
91+
--------------------------------------------------
92+
{
93+
"trigger" : {
94+
"schedule" : {
95+
"timezone" : "America/Buenos_Aires",
96+
"weekly" : {
97+
"on" : [ "tuesday", "friday" ],
98+
"at" : [ "6:00", "18:00" ]
99+
}
100+
}
101+
}
102+
}
103+
--------------------------------------------------
104+
// NOTCONSOLE

‎docs/reference/watcher/trigger/schedule/yearly.asciidoc‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,3 +88,26 @@ January 20th, December 10th, and December 20th.
8888
}
8989
--------------------------------------------------
9090
// NOTCONSOLE
91+
92+
==== Configuring a yearly schedule with a different time zone
93+
By default, the `yearly` schedule is evaluated in the UTC time zone. To use a
94+
different time zone, you can specify the `timezone` parameter in the schedule.
95+
For example, the following `yearly` schedule triggers at 3:30 PM and 8:30 PM
96+
on June 4th in the `Antarctica/Troll` time zone:
97+
98+
[source,js]
99+
--------------------------------------------------
100+
{
101+
"trigger" : {
102+
"schedule" : {
103+
"timezone" : "Antarctica/Troll",
104+
"yearly" : {
105+
"in" : "june",
106+
"on" : 4,
107+
"at" : [ 15:30, 20:30 ]
108+
}
109+
}
110+
}
111+
}
112+
--------------------------------------------------
113+
// NOTCONSOLE

0 commit comments

Comments
 (0)