Back to Help

Mon.sh Quickstart Guide

Related Guides

Overview

  1. Create an account by navigating to the Dashboard. You will be asked to login. Account creation is as simple as entering your email and following the link sent to you.
  2. Install the python client with pip3 install monsh
  3. Generate an API key from the Settings page.
  4. Run mon configure and input the API key you acquired. You can alternatively provide the key when running the mon script e.g. ... | mon -k <your api key> or via an environment variable. Refer to Configuration below.
  5. Usage is as simple as piping the output of your script to the mon command. e.g. ... | mon or ... |& mon. Refer to usage below for additional options.

If you have trouble with any of this contact support@mon.sh and we will assist you.

Installation

The mon package requires python3. You can download and install the package easily using PIP.

pip3 install monsh

Configuration

Before using mon.sh you'll need to acquire an API key. Registration for mon is free to get started, and only costs money if you go over certain usage limits. Getting an API key is a simple process assuming you have installed the mon command.

  1. Sign up for an account on mon.sh if you don't have one by navigating to the Dashboard. You will be asked to login. Account creation is as simple as entering your email and using the code that is sent to you.
  2. Head to the Settings page and click the "Generate New Key" button
  3. Copy the key value of the newly generated key.
  4. Run mon configure and paste the API key when prompted.

Note

You can also pass the key to the mon command with the -k switch, see the usage examples below. This can be very useful for running this command without running the setup on every host.

If an API key is not provided the script won't cause the underlying script to fail, it will simply produce some additional errors in the output.

An alternative option is to set the environment variable MON_API_KEY to the api key, for example in docker as below.

docker run [...] -e MON_API_KEY=ABCD... [...]

Usage

Usage is as simple as piping the output of what script you're executing. For example

python3 -c "import time; [print(i) or time.sleep(1) for i in range(20)]" |& mon

This syntax is supported on unix based systems. An alternative style of invocation allowing you to wrap your command with the mon command is coming soon. You should generally use |& as opposed to | as this will also pass the stderr stream which is important for capturing exceptions and in some cases progress bars (such as TQDM for python). On Windows systems it's recommended that you use something like git bash.

Progress is synced to jobs automatically by matching log entries that indicate %'s (not necessarily looking for █ or other symbols). In addition it should be noted that because of the way many progress bars work, \r symbols are treated like newlines as well for log entries. For example below is how TQDM progress bars are logged.

2022-12-24 02:07:38.854	38%|###7 | 413/1095 [3:19:47<4:47:53, 25.33s/it]
2022-12-24 02:07:13.871	38%|###7 | 412/1095 [3:19:24<4:59:10, 26.28s/it]
2022-12-24 02:06:50.769	38%|###7 | 411/1095 [3:18:53<4:35:18, 24.15s/it]
2022-12-24 02:06:19.510	37%|###7 | 410/1095 [3:18:31<4:45:26, 25.00s/it]
2022-12-24 02:05:57.351	37%|###7 | 409/1095 [3:18:11<5:12:59, 27.37s/it]
2022-12-24 02:05:37.884	37%|###7 | 408/1095 [3:17:43<5:07:01, 26.81s/it]

An alternative style of invocation allowing you to wrap your command with the mon command is coming soon.

Options

  • -w allows you to specify the workspace. A workspace is a virtual organization structure for all jobs. If not specific everything falls into the default workspace. All event notification configuration happens at the workspace level.
  • -k allows you to specify the API key for usage. If provided this overrides the API key in the config file.
  • -l allows you to specify the log levels for the mon script itself. For example you can use mon -l DEBUG to get additional information from the mon script.