Execution

This page describes what happens during the execution of a Scrippy script, and the files it uses.

Execution steps

Step Phase What happens On failure
1 import scrippy_core Main configuration files read and merged Python stack trace, exit status 1
2 import scrippy_core Header parsed: Script information, @args declarations CRITICAL message, exit status 1
3 import scrippy_core Command line options parsed and checked Usage error, exit status 2
4 import scrippy_core Informational options handled (--help, --version, --source-code, --hist, --log) The script exits after displaying the information
5 import scrippy_core --no-stdout and --debug applied, secret options registered
6 Entering the context @conf declarations parsed, configuration file loaded and checked, [log] level applied, secret configuration values registered CRITICAL message, exit status 1
7 Entering the context @user and @group checked CRITICAL message, exit status 1
8 Entering the context Execution registered, waiting for a slot according to @max_instance CRITICAL message, exit status 1
9 Entering the context Log file opened, execution recorded in the history (unless --no-log-file) CRITICAL message, exit status 1
10 Entering the context Workspace created (unless disabled) CRITICAL message, exit status 1
11 Within the context Your code See Leaving the context
12 Leaving the context Workspace deleted, end of execution recorded in the history, execution unregistered, error handled

Consequences:

  • Until step 9, nothing is written to the log file nor to the history: The errors of steps 1 to 8 are only displayed on the terminal.
  • A configuration, access control or concurrency error stops the script before any code of the main() function is run.
  • An execution killed with SIGKILL (or SIGTERM, which is not handled) does not go through step 12: Its history record keeps an empty end date, its workspace is not deleted. Its registration is automatically cleaned by the next executions. Ctrl+C (SIGINT) is handled as an error (KeyboardInterrupt).

Files

For a script named disk_watch.py:

File Created Deleted
<confdir>/disk_watch.conf By you Never
<logdir>/disk_watch/disk_watch_<session>.log At step 9 Never (see below)
<histdir>/disk_watch.db At the first execution Never, old records being purged at each execution
<tmpdir>/disk_watch_<session>/ At step 10 At step 12
<tmpdir>/disk_watch.pids At the first execution Never
<tmpdir>/disk_watch.pids.lock At the first execution Never

<session> is the session identifier of the execution: <timestamp>_<pid>, i.e: 1791446705.884451_27893.

The logdir, histdir and tmpdir directories are created when needed. The other directories must exist.

Note: Scrippy never deletes log files. Purge the logdir directory with a tool such as logrotate, or a scheduled command such as find <logdir> -name '*.log' -mtime +30 -delete.

History database

The history is a SQLite3 database containing a single executions table:

Column Type Content
session TEXT The session identifier
start REAL The start date (Unix timestamp)
end REAL The end date (Unix timestamp), NULL while running or if killed
duration TEXT The human readable duration (i.e: 1 min 12 sec)
origin TEXT The user who initiated the execution (SUDO_USER if set, the current user otherwise)
exec TEXT The user who ran the script
code INTEGER The exit status
params TEXT The command line options and arguments, secret values redacted
exit_code TEXT The name of the error, 0 if none

The database can be queried with any SQLite3 client, i.e. to feed a dashboard:

sqlite3 ~/.local/share/scrippy/hist/disk_watch.db \
  "select datetime(start, 'unixepoch'), code from executions order by start desc limit 5"