Horreum

Uploading results into Horreum

Horreum accepts any valid JSON as the input. To get maximum out of Horreum, though, it is recommended to categorize the input using JSON schema.

Getting the token

New data can be uploaded into Horreum only by authorized users. We recommend setting up a separate user account for the load-driver (e.g. Hyperfoil) or CI toolchain that will upload the data as part of your benchmark pipeline. This role should be a composition of the owner team role (e.g. engineers-team) and uploader role.

KEYCLOAK_URL=http://localhost:8180 # Default URL when using docker-compose
HORREUM_USER=user
HORREUM_PASSWORD=secret
TOKEN=$(curl -s -X POST $KEYCLOAK_URL/auth/realms/horreum/protocol/openid-connect/token \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username='$HORREUM_USER'&password='$HORREUM_PASSWORD'&grant_type=password&client_id=horreum-ui' \
    | jq -r .access_token)

Using offline token

Access token has very limited timespan; when you want to perform the upload from CI script and don’t want to store the password inside you can keep an offline token. This token cannot be used directly as an access token; instead you can store it and use it to obtain a regular short-lived access token:

OFFLINE_TOKEN=$(curl -s -X POST $KEYCLOAK_URL/auth/realms/horreum/protocol/openid-connect/token \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'username='$HORREUM_USER'&password='$HORREUM_PASSWORD'&grant_type=password&client_id=horreum-ui&scope=offline_access' \
    | jq -r .refresh_token)
TOKEN=$(curl -s -X POST $KEYCLOAK_URL/auth/realms/horreum/protocol/openid-connect/token \
    -H 'content-type: application/x-www-form-urlencoded' \
    -d 'grant_type=refresh_token&client_id=horreum-ui&refresh_token='$OFFLINE_TOKEN' \
    |  jq -r .access_token)

Note that the offline token also expires eventually, by default after 30 days.

Uploading the data

There are several mandatory parameters for the upload:

Optionally you can also set schema with URI of the JSON schema, overriding (or providing) the $schema key in the data. If the schema is found the JSON is validated against the schema; otherwise it is simply admitted. You don’t need to define the schema in Horreum ahead.

The upload itself can look like:

HORREUM_URL=http://localhost:8080
TEST='$.info.benchmark'
START='2020-05-01T10:15:30.00Z'
STOP='2020-05-01T10:40:26.00Z'
OWNER='engineers-team'
ACCESS='PUBLIC'
curl $HORREUM_URL'/api/run/data?test='$TEST'&start='$START'&stop='$STOP'&owner='$OWNER'&access='$ACCESS \
    -s -X POST -H 'content-type: application/json' \
    -H 'Authorization: Bearer '$TOKEN \
    -d @/path/to/data.json