Runner

The Runner service is central to putting AWTS to work. Essentially it runs Jobs, which are defined by a Job Spec to configure the Execution Engine. Runner runs trading algorithms, as well as any custom data/processing/analytics tasks.

Jobs revolve around the Frame concept and can be used for anything from setting a price alert, to casting charts to a dashboard - to actually running your trading strategies!

Interacting with the Runner

Runner can be wholly driven via API, but it is typical to use the CLI tool. The CLI runner command has subcommands for interacting with Runner, use --help for docs/info on each.

Create a job

Create a new job with create, in the form shown below. The spec file is mandatory.

The --start flag tells Runner to begin running the job immediately.

The --upsert flag tells runner to update the job with the specified Spec file if the job already exists.

The --ref=job1 specifies a reference for this job of our choosing, to make it easier to refer to it in later commands.

This command will create the job (and optionally start it) and return immediately. You can inspect its status and outputs with the other commands outlined below, but to start and immediately stream log outputs add --tail to the create command.

> awts runner create spec.yml --start --ref=job1 --upsert

List jobs

Use the ls command to list all jobs:

> awts runner ls
┌──────────────────────────────────────┬──────┬──────┬─────────┐
│ ID                                   │ REF  │ NAME │ STATUS  │
├──────────────────────────────────────┼──────┼──────┼─────────┤
│ 5bcf25eb-d5f1-491a-8eec-ea912112d860 │ job1 │      │ running │
└──────────────────────────────────────┴──────┴──────┴─────────┘

Note; job logs are events relevant to the job that is running, which can be administrative (started/stopped) or relevant to the task at hand (e.g. price crossed threshold, trade opened). This is separate and different to technical logs from the runner app itself, see Operations for details on these technical outputs.

Administering a job

Manually start/stop a job like this:

> awts runner start myjob
Ok
> awts runner stop myjob
Ok

Logs

Jobs generate timestamped log entries as events occur - including when the job starts/stops, when errors occur, and if any interesting/important things happen. You can view the logs like this:

> awts runner logs myjob
2023-11-07T13:04:27Z   myjob    STARTED

To stream logs continuously, add --tail.

The logs output also supports --timezone to show timestamps in a different timezone (your local device's configured timezone is default), and --format to set output format to CSV, TSV, HTML or Markdown. Streaming logs will automatically end when the job finishes, or hit Ctrl+C to stop streaming.

Casting to a dashboard

Any job can be cast to a chart widget on a Dash instance to visualize its data in real time. Use this to keep an eye on running strategies, or to analyze backtest/replay results.

Use the CLI to tell a job to cast to a screen path:

> awts runner cast myjob /wallboard/page1/chart1
Ok

Note the command will return immediately as the cast happens asynchronously on the job runner. If you don't immediately see chart data appear, check the job logs in case the chart path was misspelt or the chart was unreachable.

To stop casting, use the same command but with - or an empty string as the path:

> awts runner cast myjob -
Ok

IDs/Refs

Every job gets an ID automatically, assigned by Runner. However you can also optionally set a ref for a job, which can be any string of your choosing.

Subsequent commands (like start, stop) can reference jobs by either ID or Ref.

Use Ref to assign more memorable (but still unique!) references ot jobs for easier scripting/automation. The example CLI commands above all use a Ref (myjob).