Integrations

• 1: Collector API
• 2: Slack
• 3: ElasticSearch
• 4: Jenkins
• 5: Postgres
• 6: Grafana

1 - Collector API

If you have a lot of data already stored in a Collector instance, you can query it and analyze the data for regressions in Horreum.

Configuration

To configure a test to use the Collector API backend, you need to be a team administrator. With the correct permissions, you can:

1. Generate a new API key for the Collector API backend: Please see the collector docs on how to Create a new API token
2. Navigate to Administration -> Datastores configuration page, e.g. http://localhost:8080/admin#datastores
3. Select the Team from the Team dropdown that you wish to configure
4. Click New Datastore

3. Configure the Collector API Datastore:

1. Select `Collector API` from the `Datastore Type` dropdown
2. Provide a `Name` for the Datastore
3. Enter the `URL` for the Collector instance
4. Enter the `API Key` for the Collector instance, generated in step 1
5. Click `Save`

Test Configuration

To configure a test to use the Collector API backend, you can:

1. Navigate to a test configuration page, e.g. http://localhost:8080/test/10
2. Select the Collector API backend defined in the Datastores configuration from the Datastore dropdown

3. Click Save

2 - Slack

Horreum can be configured to post messages to a Slack channel through the slack-channel-message action. Actions can be triggered on various Horreum lifecycle events: see Configure Actions for details.

Configuration

Before you can configure a Slack action, either globally or for a specific test, you’ll need to create and install a “Slack application” as a bot allowed to post messages to a specific Slack channel.

1. Create a Slack App. You can do this through the Slack development CLI, or by clicking “Create New App” on the web interface at Slack Apps:

2. Open the “OAuth & Permissions” tab and scroll down to the “Scopes” header. Add your scopes by clicking on the “Add an OAuth Scope” button. The Horreum Slack Action requires the channels:join and chat:write scopes:

3. Once you’ve created the app, you’ll need to install it in your Slack workspace. Depending on the workspace, you may need to request approval from a workspace administrator:

4. Once installation is complete, Slack will give you a “BotUser OAuth Token”; a long string that should start with “xoxb-”. This token identifies and authenticates your app (in this case, the Horreum server) to Slack, and you’ll need to provide this value to Horreum as the token secret when configuring an Action.

5. Now you need to give your app permission to post to your chosen Slack channel by using your token to “join” the channel. In the Slack UI (either the web UI or in the Slack app), you can right-click on the channel and choose “View channel details”. At the bottom of the sheet that opens you should see an alphanumeric string labeled “Channel ID”, with a “copy to clipboard” icon following the value.

Navigate to the online conversations.join Test API and enter the OAuth bot token and the Channel ID in the input boxes, and click “Test method”. You should get a success API response, and you (and Horreum) can now use your OAuth token to post bot messages to the designated Slack channel ID.

Configuring a Horreum Slack Action

Using either the API or the UI, you can create a Slack Action globally or for a specific Test. You will supply both the Slack channel ID and the Slack App bot token you created earlier, along with specifying the particular event and formatted template you want to post.

TBD

3 - ElasticSearch

If you have a lot of data already stored in an Elasticsearch instance, you can query it and analyze the data for regressions in Horreum.

Configuration

To configure a test to use the elasticsearch backend, you need to be a team administrator. With the correct permissions, you can:

1. Generate a new API key for the elasticsearch backend: Please see the elasticsearch docs on how to generate an API key on the Management page
2. Navigate to Administration -> Datastores configuration page, e.g. http://localhost:8080/admin#datastores
3. Select the Team from the Team dropdown that you wish to configure
4. Click New Datastore

3. Configure the Elasticsearch Datastore:

1. Select Elasticsearch from the Datastore Type dropdown
2. Provide a Name for the Datastore
3. Enter the URL for the Elasticsearch instance
4. Enter the API Key for the Elasticsearch instance, generated in step 1
5. Click Save

Test Configuration

To configure a test to use the elasticsearch backend, you can:

1. Navigate to a test configuration page, e.g. http://localhost:8080/test/10
2. Select the Elasticsearch backend defined in the Datastores configuration from the Datastore dropdown

3. Click Save

4 - Jenkins

Details of the Jenkins Plugin can be found on the Horreum Plugin Github Repository

5 - Postgres

By default, the datasource is configured to use the postgres database backend.

Data submitted to the Horreum API will be stored in a Postgres database, alongside all the metadata required to query and retrieve the data.

Query results from other datasources will be cached in the same postgres database.

Configuration

To configure a test to use the postgres backend, you can:

1. Navigate to a test configuration page, e.g. http://localhost:8080/test/10
2. Select the Postgres - Default backend from the Datastore dropdown

3. Click Save

Migrating Data from Other Backends

If you wish to migrate data from one backend store to the postgres backend, you can configure a Test to retrieve the data from the old backend and submit it to the Horreum API.

Once the data has been cached, you can then use the postgres backend as the Test backend and any new data pushed to Horreum will be analyzed alongside the migrated data.

6 - Grafana

Grafana is a popular tool for visualizing time series data. Horreum can be configured as a datasource in Grafana to allow you to view the data processed by Horreum.

Prerequisites:

1. Horreum is running, and you are logged in

2. You have access to a running Grafana instance. If you do not have an environment available, please follow the official documentation for your platform.

Configure Horruem as a Datasource

1. Install the JSON Datasource plugin for Grafana

2. Add new Datasource

2.1 Click “Add new data source” button

2.2 Configure Horreum as a Datasource

Configure the datasource as follows:

• Name: Horreum
• URL: https://<horreum_host>/api/changes
• Access: Server (Default)
• Forward OAuth Identity: checked

Click “Save & Test” button

If successful, you should see the following message:

Querying Horreum data

Now that you have Horreum configured as a datasource, you can query the data in Horreum from Grafana.

1.1 Create a new Dashboard

2.2 Add Horreum as Datasource

2.3 Provide a name for the new Panel

2.4 Define query

Horreum provides an API that Grafana can natively query.

In order for Grafana to query Horreum, you must provide a Metric payload that defines the query.

The Metric is a String that consists of the Variable ID and Fingerprint seperated by a semi-colon ;.

e.g. Metric : 23219;{"buildType":"SNAPSHOT"}

2.5 Save panel

2.5 View Dashboard