flux-cron(1)
SYNOPSIS
DESCRIPTION
The Flux cron service offers an interface for executing commands on triggers such as a time interval or Flux events. The service is implemented as a Flux broker module which, when loaded, manages a set of cron entries and uses the built-in broker.exec service to run a command associated with the entry each time the defined trigger is reached. As with flux-exec(1), these tasks run as direct children of the flux-broker(1) and run outside of the control of any loaded job scheduling service.
The flux cron utility offers an interface to create, stop, start, query, and destroy these entries in the Flux cron service.
For a detailed description of the cron service operation and how it executes tasks, see the OPERATION and TASK EXECUTION sections below.
COMMANDS
The following sub-commands are available:
tab
Process one or more lines containing crontab expressions from file (stdin by default). Each valid crontab line will result in a new cron entry registered with the Flux cron service.
Crontab lines have five standard fields, similar to crontab(5):
minutes |
0-59 |
hours |
0-23 |
day of month |
0-23 |
month |
0-11 |
day of week |
0-6 |
Everything after the day of week is considered a command to be run.
- -o, options=LIST
Set comma separated EXTRA OPTIONS for all cron entries.
- -E, --preserve-env
Export the current environment to be used for the command being executed as part of the cron job. Normally, the broker environment is used.
- -d, --working-dir=DIR
Set the working directory for commands being executed as part of the cron job. Normally, the working directory of the broker is used.
at
Run command at specific date and time described by time.
- -o, options=LIST
Set comma separated EXTRA OPTIONS for all cron entries.
- -E, --preserve-env
Export the current environment to be used for the command being executed as part of the cron job. Normally, the broker environment is used.
- -d, --working-dir=DIR
Set the working directory for the command being executed as part of the cron job. Normally, the working directory of the broker is used.
event
Create a cron entry to execute command after every event matching topic.
- -N, --name=STRING
Set a name for this cron entry to STRING.
- -a, --after=N
Run the first task only after N matching events. Then run every event or N events with
--nth.
- -i, --min-interval=T
Set the minimum interval at which two cron jobs for this event will be run. For example, with
--min-intervalof 1s, the cron job will be at most run every 1s, even if events are generated more quickly.
- -o, --options=LIST
Set comma separated EXTRA OPTIONS for this cron entry.
- -E, --preserve-env
Export the current environment to be used for the command being executed as part of the cron job. Normally, the broker environment is used.
- -d, --working-dir=DIR
Set the working directory for the command being executed as part of the cron job. Normally, the working directory of the broker is used.
interval
Create a cron entry to execute command every interval, where interval is an arbitrary floating point duration with optional suffix s for seconds, m for minutes, h for hours and d for days.
- -n, --name=STRING
Set a name for this cron entry to STRING.
- -a, --after=TIME
The first task will run after a delay of TIME instead of interval. After the first task the entry will continue to execute every interval.
- -c, --count=N
The entry will be run a total of N times, then stopped.
- -o, --options=LIST
Set comma separated EXTRA OPTIONS for this cron entry.
- -E, --preserve-env
Export the current environment to be used for the command being executed as part of the cron job. Normally, the broker environment is used.
- -d, --working-dir=DIR
Set the working directory set for the command being executed as part of the cron job. Normally, the working directory of the broker is used.
list
Display a list of current entries registered with the cron module and their current state, last run time, etc.
stop
Stop cron entry id. The entry will remain in the cron entry list until deleted.
start
Start a stopped cron entry id.
delete
Purge cron entry id from the cron entry list.
- -k, --kill
Kill any running task associated with entry id.
dump
Dump all information for cron entry id.
- -k, --key=KEY
Print only the value for key KEY.
For a list of keys run flux cron dump ID.
sync
Query and modify the current sync-event behavior for the cron module. If a sync-event is set, the cron module will defer all task execution until an event matching the sync-event topic is received.
Without any topic supplied on command line, flux cron sync displays the current setting for sync.
If a task is deferred due to sync-event, the stats.deferred statistic is incremented.
- -e, --epsilon=TIME
Set amount of time after a sync-event that jobs are still allowed to be run. With this option, the cron module will not delay task execution if the task is normally scheduled to run within delay of the matching event.
- -d, --disable
Disable the cron sync-event.
EXTRA OPTIONS
For flux cron commands allowing --options, the following
extra options are supported:
- -o timeout=N
Set a timeout for tasks invoked for this cron entry to N seconds, where N can be a floating point number. Default is no timeout.
- -o rank=R
Set the rank on which to execute the cron command to R. Default is rank 0.
- -o task-history-count=N
Keep history for the last N tasks invoked by this cron entry. Default is 1.
- -o stop-on-failure=N
Automatically stop a cron entry if the failure count exceeds N. If N is zero (the default) then the cron entry will not be stopped on failure.
OPERATION
The Flux cron module manages the set of currently configured cron jobs as a set of common entries, each with a unique ID supplied by a global sequence number and set of common attributes, options, and statistics. Basic attributes of a cron job include an optional name, the command to execute on the entry's trigger, the current state of the cron entry (stopped or not stopped), a repeat count indicating the total number of times to execute the cron job before stopping, and the type of entry.
All cron entries also support a less common list of options, which may
be set at creation time via a comma-separated list of option=value
parameters passed to -o, --option=OPTS. These options are described
in the EXTRA OPTIONS section at the end of this document.
Currently, Flux cron supports only two types of entries. The interval entry supports executing a command once every configured duration, optionally starting after a different time period. More detailed information about the interval type can be found in the documentation for the flux cron interval command above. The event type entry supports running a command once every N events matching the configured event topic. More information about this type can be found in the documentation for flux cron event.
The Flux cron module additionally keeps a common set of statistics for each entry, regardless of type . These include the creation time, last run time, and last time the cron entry was "started", as well a count of total number of times the command was executed and a count of successful and failed runs. Currently, the stats for a cron entry may be viewed via the flux cron dump subcommand stats.* output.
When registered, cron entries are automatically started, meaning they are eligible to run the configured command when the trigger condition is met. Entries may be stopped, either by use of the flux cron stop command, or if a stop-on-failure value is set. Stopped entries are restarted using flux cron start, at which point counters used for repeat and stop-on-failure are reset.
Stopped entries are kept in the flux cron until deleted with
flux cron delete. Active cron entries may also be deleted, with
currently executing tasks optionally killed if the --kill option is
provided.
TASK EXECUTION
As related above, cron entry commands are executed via the broker.exec service, which is a low level execution service offered outside of any scheduler control, described in more detail in the flux-exec(1) man page.
Standard output and error from tasks executed by the cron service are logged and may be viewed with flux-dmesg(1). If a cron task exits with non-zero status, or fails to launch under the broker.exec service, a message is logged and the failure is added to the failure stats. On task failure, the cron job is stopped if stop-on-failure is set, and the current failure count exceeds the configured value. By default, stop-on-failure is not set.
By default, the Flux cron module keeps information for the last task executed
for each cron entry. This information can be viewed either via the
flux cron list or flux cron dump ID subcommands. Data
such as start and end time, exit status, rank, and PID for the task is
available. The number of tasks kept for each cron entry may be individually
tuned via the --task-history-count option, described in the
EXTRA OPTIONS section.
Commands are normally executed immediately on the interval or event
trigger for which they are configured. However, if the --sync-event
option is active on the cron module, tasks execution will be deferred
until the next synchronization event. See the documentation above
for flux cron sync for more information.
RESOURCES
Flux: http://flux-framework.org
Flux RFC: https://flux-framework.readthedocs.io/projects/flux-rfc