Custom Execution Status

Valohai has a list of default status for executions (created, queued, started, completed, error, stopping, stopping (hard), and stopped). In some cases you might want to set a custom status to a running execution, e.g. “Finished loading data” or “Running the last epoch”.

Set a custom status

You can set a custom status in your code by either using valohai-utils or an API call. The status will be visible in the execution details view and you can also access it via an API call if you want to pass it to for example some other service.

Setting the status with valohai-utils

The Python helper tool valohai-utils has a command that allows you to set the status. Remember to add it to your requirements.txt or pip install it at the beginning of your execution!

import valohai

valohai.set_status_detail("I'm working on it...")

Set status within a job

If you don’t want to use valohai-utils, it is possible to set the status with an API call. Below is a Python example that uses the requests package. If you are using some other language and would need help, contact the Valohai support.

import json
import requests

with open('/valohai/config/api.json', 'r') as json_file:
    data = json.load(json_file)

    headers = data["set_status_detail"]["headers"]

    r = requests.post(data["set_status_detail"]["url"], headers=headers, json={"status_detail": "I'm working on it..."})
    print(r.status_code)

Retrieve Status with REST API

You can see the status that you have set under the Details page for your execution. In addition, you can access it with the ExecutionRetrieve API endpoint from your local machine or from some external service, for example. This can be done even while the execution is still running.

Note that you will need an API token for this. Make sure to keep the token secret and to not include it in your version control as it can be used to access your Valohai account.

import requests
import json
import os

# Authenticate yourself with the token
auth_token = os.environ['VH_API_TOKEN']
headers = {'Authorization': 'Token %s' % auth_token}

# Send a GET request to the endpoint
url = 'https://app.valohai.com/api/v0/executions/{execution_id}/'
resp = requests.get(url, headers=headers)

# Print the status detail
print(resp.json()["status_detail"])

Rich custom status data

The custom status field also supports certain types of rich content that is rendered in the UI. These rich content blocks are represented as lines of JSON within the status field (so be careful to serialize your JSON to be a single line!). You can compose any number of rich content fields in a single status update. Plain text lines will be rendered as text blocks.

Initially, the types of rich content supported are text, gauge, and sparkline.

Text

The text type is a simple text block that can be used to display a message, optionally colorized.

Any CSS color is usable, along with special color names bad, good, and warn that respond to the UI’s color theme.

{"type": "text", "text": "I'm working on it...", "color": "green"}

Gauge

The gauge type is a progress bar that can be used to display a percentage value.

{"type": "gauge", "value": 0.5}

You can optionally set the minimum and maximum value of your value range, to avoid having to calculate the percentage yourself, as well as label your gauge.

{"type": "gauge", "value": 37, "min": 0, "max": 100, "label": "Progress"}

As with text, you can also colorize the gauge.

{"type": "gauge", "value": 0.7, "color": "good", "label": "Eval quality"}

Sparkline

Sparklines are teensy tiny little line chartsies that can be used to display a series of values over time.

{"type": "sparkline", "values": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}

By default, the range of the sparkline is determined by the minimum and maximum values in the series. If you want to be explicit about the range, you can set min and/or max explicitly; not setting one implies automatic range.

{"type": "sparkline", "values": [0, 1, 2, 3, 4, 5], "min": 0, "max": 10}

And as you can imagine, as with text and gauge, you can also colorize the sparkline.

{"type": "sparkline", "values": [0, 0, 0, 5, 10], "color": "good"}