jort

• Track, profile, and notify at custom blocks in your coding scripts.
• Time new and existing shell commands with a convenient command line tool.
• Save and view details of finished jobs with a local database.

Installation

pip install jort

Script Timing

Use the Tracker to create named blocks throughout your code. Blocks need start and stop calls, and multiple iterations are combined to summarize how long it takes to complete each leg. The report function prints the results from all blocks. If stop is not supplied a block name, the tracker will close and calculate elapsed time from the last open block (i.e. last in, first out).

import jort
from time import sleep

tr = jort.Tracker()

tr.start('my_script')
sleep(1)
for _ in range(10):
    tr.start('sleep_1s')
    sleep(1)
    tr.stop('sleep_1s')
tr.stop('my_script')
    
tr.report()

The printed report appears as:

my_script | 11.0 s ± 0.0 s per iteration, n = 1
sleep_1s | 1.0 s ± 0.0 s per iteration, n = 10

Alternatively, you can use single line checkpoints with tr.checkpoint(), which create timing blocks that close at the start of the next checkpoint. Note that you must use another tr.stop() call to end the final checkpoint block.

Function Decorators

jort supports timing functions with decorators, via Tracker.track. As in the first example:

@tr.track
def my_script():
    sleep(1)
    for _ in range(10):
        sleep_1s()

Notifications

Notifications are handled by callbacks to timing functions. As of now, there are three main callbacks:

jort.PrintReport()
jort.EmailNotification()
jort.TextNotification()

To use notifications, add callbacks to tracking functions:

# linear script
tr.stop('my_script', callbacks=[jort.PrintReport(), jort.TextNotification()])

# function decorator
@tr.track(callbacks=[jort.EmailNotification()])
def my_script():
    [...]

For SMS text and e-mail notifications, you can enter credentials with the command jort config.

SMS handling is done through Twilio, which offers a free trial tier. As of now, jort handles notifications locally, so you need to add your own credentials for each service.

The existing command-execution interfaces are also the notification interfaces:

import jort

payload = jort.track_new(
    "pytest -q",
    send_email=True,
    send_text=True,
)

From any project directory, the equivalent command-line interface is:

jort track --email --text 'pytest -q'

The two notification options are independent; use either one or both. See the public interface reference before adding a new command-running API.

For agent-friendly automation, use JSON output and a detached worker:

jort track --detach --email --json 'python benchmark.py'
jort status JOB_ID --json
jort logs JOB_ID

jort track exits nonzero when the tracked command exits nonzero. Use jort doctor to validate local storage and notification configuration, and jort notify test --email to send a real email test.

Use --timeout SECONDS for a bounded job, --strict-notifications to make delivery failures produce exit code 2, and --argv -- when exact argument preservation matters.

For repeated measurements, use the built-in benchmark summary:

jort benchmark --repeat 5 --warmup 2 --json 'python benchmark.py'
# Compare against successful runs saved under another session.
jort benchmark --baseline-session main --json 'python benchmark.py'

Saving to Database

jort allows you to save details of finished jobs to a local database. To save all blocks to database, use the to_db keyword. You can also optionally group jobs under a common "session" by specifying the session_name keyword:

tr = jort.Tracker(to_db=True, session_name="my_session")

If you do not want every block to be saved, you can specify manually:

tr.stop('my_script', to_db=True)

@tr.track(to_db=True)
def my_script():
    [...]

Command Line Timing

To track a new command, you can run:

jort track your_command

If the target command uses its own options, place quotes around the full command.

jort track "your_command -a -b -c"

To send notifications on completion via e-mail or text, add the -e or -t flags, respectively. For a full list of options, use the -h flag.

To save job details to database, add the -d flag. You can specify the session name with -s, and have jort skip jobs that both are already saved in the database under the same session and have completed successfully via the -u option.

You can also track an existing process using its integer process ID:

jort track PID

Similarly, add the -e or -t flags for either e-mail or SMS notification on completion, and -d and -s flags for saving info to database.

Job lifecycle commands

jort inspect --json lists persisted jobs. jort status JOB_ID --json returns the stable job payload, including exit code, working directory, git revision, metrics, and notification results. jort cancel JOB_ID requests termination.

Captured output is stored under the local Jort data directory. Use --max-output-bytes to bound an attachment and jort logs JOB_ID to retrieve it.