Time regions: Add option for cron syntax to support complex schedules

[leeoniya]

context: https://raintank-corp.slack.com/archives/C03KVDHTWAH/p1737909843220739

users sometimes want to define time regions that are not one daily time range repeated for a specific day or every day.

the existing config is rather limited, and requires many separate annotation "queries" just to create a "weekdays only" schedule since we don't offer multi-day selection.

before:

one option was to implement a multi-day selector, but why stop there? 😈

this PR opens up many possibilities by adding support for cron syntax, which allows for quite complex schedules to be defined concisely. allowing for things like "weekdays 9-5" to be defined as a single annotation. the implementation uses Hexagon/croner, a tiny, zero-dependency cron parsing and eval lib.

time-regions-cron.json

{
  "annotations": {
    "list": [
      {
        "builtIn": 1,
        "datasource": {
          "type": "grafana",
          "uid": "-- Grafana --"
        },
        "enable": true,
        "hide": true,
        "iconColor": "rgba(0, 211, 255, 1)",
        "name": "Annotations & Alerts",
        "type": "dashboard"
      },
      {
        "datasource": {
          "type": "datasource",
          "uid": "grafana"
        },
        "enable": true,
        "iconColor": "blue",
        "name": "Weekdays 9a-5p",
        "target": {
          "lines": 10,
          "queryType": "timeRegions",
          "refId": "Anno",
          "scenarioId": "annotations",
          "timeRegion": {
            "cronExpr": "0 9 * * 1-5",
            "duration": "8h",
            "mode": "cron",
            "timezone": "browser"
          }
        }
      }
    ]
  },
  "editable": true,
  "fiscalYearStartMonth": 0,
  "graphTooltip": 0,
  "id": 440,
  "links": [],
  "panels": [
    {
      "datasource": {
        "name": "gdev-testdata",
        "type": "grafana-testdata-datasource",
        "uid": "PD8C576611E62080A"
      },
      "fieldConfig": {
        "defaults": {
          "color": {
            "mode": "palette-classic"
          },
          "custom": {
            "axisBorderShow": false,
            "axisCenteredZero": false,
            "axisColorMode": "text",
            "axisLabel": "",
            "axisPlacement": "auto",
            "barAlignment": 0,
            "barWidthFactor": 0.6,
            "drawStyle": "line",
            "fillOpacity": 0,
            "gradientMode": "none",
            "hideFrom": {
              "legend": false,
              "tooltip": false,
              "viz": false
            },
            "insertNulls": false,
            "lineInterpolation": "linear",
            "lineWidth": 1,
            "pointSize": 5,
            "scaleDistribution": {
              "type": "linear"
            },
            "showPoints": "auto",
            "spanNulls": false,
            "stacking": {
              "group": "A",
              "mode": "none"
            },
            "thresholdsStyle": {
              "mode": "off"
            }
          },
          "mappings": [],
          "thresholds": {
            "mode": "absolute",
            "steps": [
              {
                "color": "green",
                "value": null
              },
              {
                "color": "red",
                "value": 80
              }
            ]
          }
        },
        "overrides": []
      },
      "gridPos": {
        "h": 19,
        "w": 24,
        "x": 0,
        "y": 0
      },
      "id": 1,
      "options": {
        "legend": {
          "calcs": [],
          "displayMode": "list",
          "placement": "bottom",
          "showLegend": true
        },
        "tooltip": {
          "hideZeros": false,
          "mode": "single",
          "sort": "none"
        }
      },
      "targets": [
        {
          "datasource": {
            "type": "grafana-testdata-datasource",
            "uid": "PD8C576611E62080A"
          },
          "refId": "A",
          "scenarioId": "random_walk",
          "seriesCount": 1
        }
      ],
      "title": "Panel Title",
      "type": "timeseries"
    }
  ],
  "schemaVersion": 40,
  "tags": [],
  "templating": {
    "list": []
  },
  "time": {
    "from": "2025-01-26T21:38:49.202Z",
    "to": "2025-02-12T00:35:08.422Z"
  },
  "timepicker": {},
  "timezone": "browser",
  "title": "time-regions-cron",
  "uid": "ceb7ty0pux340b",
  "version": 7,
  "weekStart": ""
}

This turned into a rather large rewrite of 7 year old, unmaintained legacy code. Because of this, a lot was removed, replaced, and refactored.

Previously:

• Regions that only specified dayOfWeek (without time) resulted in a duration of 23:59:59 (1s short of 24h)
• Regions were first generated in UTC, then shifted using a combination of region timezone and dashboard timezone
• Regions that did not start within the current dashboard time range (but still overlapped it) were not accounted for
• Configurations with only "to" or "toDayOfWeek" were valid

Many of the existing tests relied on the quirks above, so they had to be removed and replaced.

Now:

• We convert all time region definitions to a cron expression and duration at runtime
• Duration for regions only defined in "day of week" are now exact multiples of 24h
• All regions are now computed directly using the time zone defined in the region config (or browser), removing the need for additional shifting and reliance on the viewer's time zone
• All regions that intersect the current time range are accounted for
• Region configs that lack both "from" and "fromDayOfWeek" are invalid

We have an existing gdev dashboard with some time region queries that continues to look the same:

http://localhost:3000/d/XMjIZPmik/panel-tests-graph-time-regions?orgId=1&from=2023-03-01T06:00:00.000Z&to=2023-04-01T05:00:00.000Z&scenes&timezone=browser

in the future we can consider adding a nice UI for constructing common cron expressions, some existing examples from google / microsoft:

TODO:

• docs / enablement
• a bit of work to add timezone support (which croner already supports internally)
• internally convert old settings to cron syntax and use croner to calculate time regions, removing our custom-made thing (and its additional util fns):

  grafana/public/app/core/utils/timeRegions.ts

  Lines 20 to 138 in d16f231

  	export function calculateTimesWithin(cfg: TimeRegionConfig, tRange: TimeRange): AbsoluteTimeRange[] {
  	if (!(cfg.fromDayOfWeek || cfg.from) && !(cfg.toDayOfWeek || cfg.to)) {
  	return [];
  	}
  	// So we can mutate
  	const timeRegion = { ...cfg };
  	if (timeRegion.from && !timeRegion.to) {
  	timeRegion.to = timeRegion.from;
  	}
  	if (!timeRegion.from && timeRegion.to) {
  	timeRegion.from = timeRegion.to;
  	}
  	const hRange = {
  	from: parseTimeOfDay(timeRegion.from),
  	to: parseTimeOfDay(timeRegion.to),
  	};
  	if (!timeRegion.fromDayOfWeek && timeRegion.toDayOfWeek) {
  	timeRegion.fromDayOfWeek = timeRegion.toDayOfWeek;
  	}
  	if (!timeRegion.toDayOfWeek && timeRegion.fromDayOfWeek) {
  	timeRegion.toDayOfWeek = timeRegion.fromDayOfWeek;
  	}
  	if (timeRegion.fromDayOfWeek) {
  	hRange.from.dayOfWeek = Number(timeRegion.fromDayOfWeek);
  	}
  	if (timeRegion.toDayOfWeek) {
  	hRange.to.dayOfWeek = Number(timeRegion.toDayOfWeek);
  	}
  	if (hRange.from.dayOfWeek && hRange.from.h == null && hRange.from.m == null) {
  	hRange.from.h = 0;
  	hRange.from.m = 0;
  	hRange.from.s = 0;
  	}
  	if (hRange.to.dayOfWeek && hRange.to.h == null && hRange.to.m == null) {
  	hRange.to.h = 23;
  	hRange.to.m = 59;
  	hRange.to.s = 59;
  	}
  	if (!hRange.from || !hRange.to) {
  	return [];
  	}
  	if (hRange.from.h == null) {
  	hRange.from.h = 0;
  	}
  	if (hRange.to.h == null) {
  	hRange.to.h = 23;
  	}
  	const regions: AbsoluteTimeRange[] = [];
  	const fromStart = dateTime(tRange.from).utc();
  	fromStart.set('hour', 0);
  	fromStart.set('minute', 0);
  	fromStart.set('second', 0);
  	fromStart.set('millisecond', 0);
  	fromStart.add(hRange.from.h, 'hours');
  	fromStart.add(hRange.from.m, 'minutes');
  	fromStart.add(hRange.from.s, 'seconds');
  	while (fromStart.unix() <= tRange.to.unix()) {
  	while (hRange.from.dayOfWeek && hRange.from.dayOfWeek !== fromStart.isoWeekday()) {
  	fromStart.add(24, 'hours');
  	}
  	if (fromStart.unix() > tRange.to.unix()) {
  	break;
  	}
  	const fromEnd = dateTime(fromStart).utc();
  	if (fromEnd.hour) {
  	if (hRange.from.h <= hRange.to.h) {
  	fromEnd.add(hRange.to.h - hRange.from.h, 'hours');
  	} else if (hRange.from.h > hRange.to.h) {
  	while (fromEnd.hour() !== hRange.to.h) {
  	fromEnd.add(1, 'hours');
  	}
  	} else {
  	fromEnd.add(24 - hRange.from.h, 'hours');
  	while (fromEnd.hour() !== hRange.to.h) {
  	fromEnd.add(1, 'hours');
  	}
  	}
  	}
  	fromEnd.set('minute', hRange.to.m ?? 0);
  	fromEnd.set('second', hRange.to.s ?? 0);
  	while (hRange.to.dayOfWeek && hRange.to.dayOfWeek !== fromEnd.isoWeekday()) {
  	fromEnd.add(24, 'hours');
  	}
  	const outsideRange =
  	(fromStart.unix() < tRange.from.unix() && fromEnd.unix() < tRange.from.unix()) ||
  	(fromStart.unix() > tRange.to.unix() && fromEnd.unix() > tRange.to.unix());
  	if (!outsideRange) {
  	regions.push({ from: fromStart.valueOf(), to: fromEnd.valueOf() });
  	}
  	fromStart.add(24, 'hours');
  	}
  	return regions;
  	}

[github-actions]

Since you've added the Add to what's new label, consider drafting a What's new note for this feature.

[gelicia]

Checked with many time regions and points, reviewed the tests and they seem thorough as well. Great work on this!