elasticsearch-croneval

Evaluate a cron expression and display the next 10 trigger times (default behavior)

$ elasticsearch-croneval "[cron_expression]"

$ elasticsearch-croneval "[cron_expression]" [[-c|--count]] [integer]

$ elasticsearch-croneval "[invalid_cron_expression]" [[-d|--detail]]

$ elasticsearch-croneval "[cron_expression]" [[-s|--silent]]

$ elasticsearch-croneval "[cron_expression]" [[-v|--verbose]]

elasticsearch-croneval <cron_expression> [--timezone <timezone_id>] [--count <number>]
or
elasticsearch-croneval <cron_expression> [-t <timezone_id>] [-n <number>]

<cron_expression>
    The cron string to be evaluated. This must be the first argument and should follow the Elasticsearch cron expression format.

--timezone <timezone_id>, -t <timezone_id>
    Specifies the timezone for evaluating the cron expression. This should be a valid Java TimeZone ID (e.g., 'America/Los_Angeles', 'Europe/Berlin', 'UTC'). If omitted, the server's default timezone is used.

--count <number>, -n <number>
    Defines the number of future execution times to display. If omitted, the command typically defaults to showing a small number of upcoming times (e.g., 10).

The elasticsearch-croneval command is a utility provided with Elasticsearch, primarily used to evaluate and validate cron expressions that are understood by Elasticsearch's Watcher feature and other scheduling components. It allows users to test and debug their cron strings without needing to deploy or activate a Watcher, providing a list of upcoming execution times based on the given expression. This is invaluable for ensuring that scheduled tasks, such as alerting or data transformations, will run precisely when intended. The command helps in confirming the syntax and behavior of cron expressions, especially when dealing with specific timezones or complex schedules. It's a key tool for developers and administrators working with time-based automation within the Elasticsearch ecosystem.

The elasticsearch-croneval command requires a Java Runtime Environment (JRE) to be installed and configured, as it is a Java-based utility. It must be run from the Elasticsearch installation's bin/ directory or have the necessary environment variables set to locate its dependencies. The command evaluates expressions based on the current system time, which might differ from the time on remote Elasticsearch nodes if not explicitly aligned or compensated for with the --timezone option.

Elasticsearch's cron expression format is similar to the standard Unix cron but with some key differences and extensions, particularly for specifying seconds, years, and different kinds of wildcards. It typically consists of 6 or 7 fields:
seconds minutes hours day_of_month month day_of_week [year]
Supported special characters include: * (all values), ? (no specific value for day of month/week), - (range), , (list), / (increment), L (last), W (weekday nearest day), # (nth day of week). For precise details, refer to the official Elasticsearch Watcher documentation on cron schedules.

The elasticsearch-croneval utility was introduced as part of the X-Pack extension for Elasticsearch, specifically to support and debug the cron-based scheduling capabilities of the Watcher feature. Watcher, which allows users to create alerts and automate tasks based on data in Elasticsearch, heavily relies on cron expressions for its scheduling. Over time, as X-Pack features became more integrated into the core Elasticsearch distributions, elasticsearch-croneval transitioned to being a standard utility bundled with Elasticsearch, accessible in the bin/ directory for convenient command-line validation of cron schedules.

cron(8), crontab(5), date(1), at(1)