Run

EVL Run command runs EVL task(s), i.e. <job>, <workflow>, or any Bash <script>.

Run

run EVL task(s) from EVL workflow (i.e. from an ‘ews/*.ews’ file)

evl run

is intended for standalone usage, i.e. to be invoked from command line

Type of the task is recognized by a file suffix:

*.evl

suppose an EVL job, either full path or relative to project directory or relative to project’s ‘job/’ subfolder

*.ewf

suppose an EVL workflow, either full path or relative to project directory or relative to project’s ‘workflow/’ subfolder

*.sh

suppose a Bash script, either full path or relative to project directory or relative to project’s ‘job/’ subfolder

If more than one task is provided, then run them in serial one after another, i.e. run the following one after previous successfully finished.

Failures and retries:

Once one EVL task fails, then whole ‘Run’ or ‘evl run’ command fails (unless ‘$EVL_RUN_FAIL’ environment variable is set to 0, or option ‘--ignore-fail’ is specified, but use with care).

In case of EVL task failure, ‘Run’ or ‘evl run’ command tries to restart it automatically ‘$EVL_RUN_RETRY’ times. If <retries> is specified, then such value has precedence over ‘$EVL_RUN_RETRY’.

By option ‘--run-on-fail’ a task to be run can be specified in case of a failure.

Maximal run time:

When the run time of given EVL task exceed ‘$EVL_RUN_TIME’, then such task is killed and ‘Run’ or ‘evl run’ command fails. If <time> is specified, then such value has precedence over ‘$EVL_RUN_TIME’. Each retry measure run time from the beginning.

<time> can be specified in seconds, minutes, hours or days, so suffix ‘s’, ‘m’, ‘h’ or ‘d’ need to be specified to the number. If no unit is specified, seconds are assumed.

Synopsis

Run
  ( [<time>[smhd]] [<retries>r] ( <job> | <workflow> | <script> ) )...
  [ --target k8s|local|ssh ]
  [ --ignore-fail ]
  [ --run-on-fail=<task> ]
  [-c|--check-prev-run]
  [-D|--define=<definition>]...
  [-o|--odate=<yyyymmdd>]
  [-p|--project=<project_dir>]
  [-r|--restart]

evl run
  ( [<time>[smhd]] [<retries>r] ( <job> | <workflow> | <script> ) )...
  [ --target k8s|local|ssh ]
  [ --ignore-fail ]
  [ --run-on-fail=<task> ]
  [-c|--check-prev-run]
  [-D|--define=<definition>]...
  [-o|--odate=<yyyymmdd>]
  [-p|--project=<project_dir>]
  [-r|--restart]
  [-s|--progress]
  [-v|--verbose]
  [ --monitor-db=<monitor_db_uri> ]
  [ --parent-run-id=<parent_run_id> ]

evl run
  ( --help | --usage | --version )

Options

-c, --check-prev-run

check if given task(s) already finished for given Order Date and fail with exit code 2 if yes

-D, --define=<definition>

the <definition> is evaluated right before running a task, but after evaluating settings from ‘evl’ or ‘ewf’ file, e.g. ‘-DSOME_PATH=/some/path’ will do ‘eval SOME_PATH=/some/path’, and overwrites then variable SOME_PATH possibly defined in ‘evl’ or ‘ewf’ file. Multiple ‘--define’ options can be used.

--ignore-fail

by default once some task to be run fails, the whole workflow fails (after other ‘Run’ commands finish and reach first ‘Wait’). This option ignores this and allows other tasks specified by given ‘Run’ command to finish. Also the whole workflow continues.

--monitor-db=<monitor_db_uri>

specify Postgres DB to be used for monitoring

-o, --odate=<yyyymmdd>

run evl job with specified Order Date, environment variable ‘$EVL_ODATE’ is ignored

-s, --progress

for an EVL job it shows the number of records passed each component, for an EVL workflow it shows the states of each component, and for running shell scripts it does nothin. The output is refreshed every ‘$EVL_PROGRESS_REFRESH_SEC’ seconds. By default it is 2 seconds.

-p, --project=<project_dir>

specify project folder if not the current working one

--parent-run-id

for monitoring purpose in case of non-local targets, specifies under which workflow are EVL tasks invoked

-r, --restart

do not continue given workflow(s), but restart them from the beginning

--run-on-fail=<task>

when some EVL task fails, run this <task>. When used together with ‘--ignore-fail’, then this ‘run-on-fail <task>’ is fired immediately after the task fails and then continue with others. If also some other task fails, then this ‘run-on-fail <task>’ is fired again.

--target=( k8s | local | ssh )

run tasks on particular target, possible values are:

k8s

run on Kubernetes cluster which is defined by ‘$EVL_RUN_K8S_*’ variables

local

run on local machine. This is the default value.

ssh

run on a remote machine connected over ssh defined by ‘$EVL_RUN_SSH_*’ variables

Standard options:

--help

print this help and exit

--usage

print short usage information and exit

-v, --verbose

print to stderr info/debug messages of the component

--version

print version and exit

Environment Variables

The list of variables which controls EVL Workflow ‘Run’ or ‘evl run’ command behaviour. With their default values. These variables can be set for example in user’s ‘~/.evlrc’ file or in the project’s ‘project.sh’.

Control failures:

EVL_RUN_FAIL=1 ¶

whether or not to fail given ‘Run’ command once an EVL task fails, so when zero is set, the ‘Run’ command continue regardless task failures

EVL_RUN_FAIL_MAIL=1 ¶

whether or not to send an e-mail when the task fails

EVL_RUN_FAIL_MAIL_SUBJECT='$EVL_PROJECT FAILED' ¶

subject of such e-mail, where variables are resolved by ‘envsubst’ utility in time of failure

EVL_RUN_FAIL_MAIL_MESSAGE ¶

message of such e-mail, by default it is:

Project:     $EVL_PROJECT
Workflow:    $EVL_WORKFLOW
Task:        $EVL_TASK
Order Date:  $EVL_ODATE
Sent to:     $EVL_MAIL_TO
Task log:    $EVL_TASK_LOG
Tail of log: $(tail $EVL_TASK_LOG)

where commands ‘$(...)’ are resolved and also all variables are substituted (by ‘envsubst’ utility).

EVL_RUN_FAIL_SNMP=0 ¶

whether or not to send SNMP trap when the task fails.

EVL_RUN_FAIL_SNMP_MESSAGE='$EVL_PROJECT FAILED' ¶

SNMP message to be send.

Control retries:

EVL_RUN_RETRY=0 ¶

the number of times it retries to run the task again. Zero means no retry and fail ‘Run’ command once the given task fails.

EVL_RUN_RETRY_INTERVAL=5m ¶

the amount of time between retries. It can be specified in seconds, minutes, hours or days, so suffix ‘s’, ‘m’, ‘h’ or ‘d’ need to be specified to the number. If no unit is specified, seconds are assumed.

Control waiting:

EVL_RUN_TIME=24h ¶

maximal run time, so if the task invoked by ‘Run’ command is not finished after this amount of time, it is killed. The time is counted since the task is really running, not since the invocation (i.e. waiting time is not included). It can be specified in seconds, minutes, hours or days, so suffix ‘s’, ‘m’, ‘h’ or ‘d’ need to be specified to the number. If no unit is specified, seconds are assumed.

EVL_RUN_WAIT_FOR_LOCK=1 ¶

whether or not to wait for a lock file, i.e. if somebody is running the same task at the moment.

EVL_RUN_WAIT_FOR_LOCK_INTERVAL=5m ¶

the time interval between each check. It can be specified in seconds, minutes, hours or days, so suffix ‘s’, ‘m’, ‘h’ or ‘d’ need to be specified to the number. If no unit is specified, seconds are assumed.

EVL_RUN_WAIT_FOR_LOCK_TIME=10h ¶

maximal amount of time to wait for a lock file. It can be specified in seconds, minutes, hours or days, so suffix ‘s’, ‘m’, ‘h’ or ‘d’ need to be specified to the number. If no unit is specified, seconds are assumed.

EVL_RUN_WAIT_FOR_PREV_ODATE=0 ¶

whether or not to automatically wait for previous Order Date of given task. Setting to 1 might be useful when you must run daily processing strictly in right order.

EVL_RUN_WAIT_FOR_PREV_ODATE_INTERVAL=5m ¶

the time interval between each check. It can be specified in seconds, minutes, hours or days, so suffix ‘s’, ‘m’, ‘h’ or ‘d’ need to be specified to the number. If no unit is specified, seconds are assumed.

EVL_RUN_WAIT_FOR_PREV_ODATE_TIME=10h ¶

maximal amount of time to wait for previous Order Date. It can be specified in seconds, minutes, hours or days, so suffix ‘s’, ‘m’, ‘h’ or ‘d’ need to be specified to the number. If no unit is specified, seconds are assumed.

Warning control:

EVL_RUN_WARN_MAIL=0 ¶

whether or not to send an email when there is warning

EVL_RUN_WARN_MAIL_SUBJECT='$EVL_PROJECT WARNING' ¶

subject of such e-mail, where variables are resolved by ‘envsubst’ utility in time of failure

EVL_RUN_WARN_MAIL_MESSAGE ¶

message of such e-mail, by default it is:

Project:     $EVL_PROJECT
Workflow:    $EVL_WORKFLOW
Task:        $EVL_TASK
Order Date:  $EVL_ODATE
Sent to:     $EVL_MAIL_TO
Task log:    $EVL_TASK_LOG
Tail of log: $(tail $EVL_TASK_LOG)

where commands ‘$(...)’ are resolved and also all variables are substituted (by ‘envsubst’ utility).

EVL_RUN_WARN_SNMP=0 ¶

whether or not to send SNMP trap when there is a warning

EVL_RUN_WARN_SNMP_MESSAGE='$EVL_PROJECT WARNING' ¶

SNMP message to be send in such case

Kubernetes control:

EVL_RUN_K8S_CONTAINER_IMAGE="evl-tool:latest" ¶

an image to run the task on

EVL_RUN_K8S_CONTAINER_LIMIT_CPU="8000m" ¶

maximum CPUs available for the task, decimal number is allowed, or "millicpu" can be used. E.g. "0.5" and "500m" are the same and means half of the CPU.

EVL_RUN_K8S_CONTAINER_LIMIT_MEMORY="4Gi" ¶

maximum memory for the task, it can be in Bytes, or with usual suffixes like "Gi", "Mi", "Ki" or "G", "M", "K"

EVL_RUN_K8S_CONTAINER_LIMIT_STORAGE="40Gi" ¶

maximum ephemeral storage for the task, it can be in Bytes, or with usual suffixes like "Gi", "Mi", "Ki" or "G", "M", "K"

EVL_RUN_K8S_CONTAINER_REQUEST_CPU="2000m" ¶

minimum requested CPUs for the task, decimal number is allowed, or "millicpu" can be used. E.g. "2.2" and "2200m" are the same.

EVL_RUN_K8S_CONTAINER_REQUEST_MEMORY="1Gi" ¶

minimum requested memory for the task, it can be in Bytes, or with usual suffixes like "Gi", "Mi", "Ki" or "G", "M", "K"

EVL_RUN_K8S_CONTAINER_REQUEST_STORAGE="20Gi" ¶

minimum ephemeral storage for the task, it can be in Bytes, or with usual suffixes like "Gi", "Mi", "Ki" or "G", "M", "K"

EVL_RUN_K8S_NAMESPACE="default" ¶

Kubernetes namespace under which tasks suppose to run

EVL_RUN_K8S_PERSISTENT_BUCKET ¶

mandatory variable with persistent (AWS S3) bucket, where: 1. the EVL license is stored. i.e. ‘s3://<some_bucket>/evl_license_key’ 2. logs are collected in ‘evl-log’ directory, i.e. ‘s3://<some_bucket>/evl-log’ 3. EVL projects whose tasks to be run, e.g. ‘s3://<some_bucket>/<some_project>’, (it copies the tasks’ definitions from this location). The value must be only a bucket name, without ‘s3://’.

EVL_RUN_K8S_SERVICE_ACCOUNT_NAME="default" ¶

Kubernetes Service Account Name

EVL_RUN_K8S_SHM_LIMIT="1Gi" ¶

Shared Memory Size Limit of the Kubernetes Pod. (Shared memory is used by shared lookups.)

EVL_RUN_K8S_RETRY=0 ¶

the ‘backoffLimit’ parameter in Kubernetes job definition. This variable defines how many times to restart a Kubernetes job, this number of retires is on the Kubernetes level, so it is different from the variable ‘EVL_RUN_RETRY’, which is on the current machine level.

EVL_RUN_K8S_TTL_AFTER_FINISHED=10 ¶

set spec.ttlSecondsAfterFinished in Kubernetes Job definition, non-zero value is good to obtain logs from finished (i.e. Compleded or Failed) tasks. (TTL means ’Time to Live’.)

SSH control:

TBA

Examples

Commandline invocation:

1. To restart a workflow from the beginning:

   evl run --restart workflow/load_invoices.ewf
   

2. Following command runs an EVL job with yesterday ODATE showing progress

   evl run job/aggreg_invoices.evl –odate=yesterday –progress –project=/full/path/to/project

   or when current directory is a project one:

   evl run job/aggreg_invoices.evl --odate=yesterday --progress
   

Within EWS file usage:

1. To run an EVL job in an EVL Workflow (i.e. within an ‘ews’ file), and try once more when job fails:

   Run 1r aggreg_invoices.evl
   

2. Following invocation means to run common_job.sh (fail if not finished within 2 hours) and then run ‘job/stage.invoices.evl’, fail if (each run) does not finish within 4 hours, and try to restart two times when fail:

   Run 2h    job/common_job.sh  --project=/full/path/to/other/project \
       4h 2r job/stage.invoices.evl