Push metric values using a cURL command

You can push metric values to your component’s connected metric by using our REST API. We provide you with a cURL command to call the REST API within Compass. You can add this cURL command to your CI/CD tool, such as Bitbucket Pipelines or Github Actions, or run it in your terminal to call the REST API.

The process to push metric values to components involves:

• creating an API token for your Atlassian account

• copying the cURL command from Compass

• editing the cURL command to replace the variables

• running the cURL command

Step 1: Create an API token

You need an Atlassian API token to call our REST API. You create the API token from your Atlassian account, then copy and paste it to the cURL command. You can create the API token by logging in to https://id.atlassian.com/manage/api-tokens.

Learn more managing API tokens for your Atlassian account

Step 2: Copy the cURL command from Compass

You can find the cURL command to call our REST API within a component’s details page in Compass.

To copy the cURL command:

1. Go to your components details page in Compass.

2. In the Metrics section, locate the metric you want to push the values to.

3. Use one of the following options to copy the cURL command:

   • If you haven’t pushed any values yet, you’ll see the cURL command on the tile. Select Copy to clipboard () from the metric tile on the component. You can also select the command to open and view the entire command.

     

   • If you’ve already pushed values to the metric before, you’ll see the metric value on the tile. To copy the cURL command again for pushing a different value, select the more actions icon () on the metric card, then select Copy cURL command.

     

4. Paste the command to any text editor.

You will now need to edit the cURL command and replace the values of variables in the command.

Step 3: Edit the cURL command

The cURL command from Compass has the following format:

1
2
curl \
    --request POST \
    --url https://example.atlassian.net/gateway/api/compass/v1/metrics \
    --user "$USER_EMAIL:$USER_API_TOKEN" \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data "{
      \"metricSourceId\": \"ari:cloud:compass:...:metric-source/.../...\",
      \"value\": $METRIC_VALUE,
      \"timestamp\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\"
    }"

To use the cURL command, replace the following variables in the command:

• On line number 4, --user "$USER_EMAIL:$USER_API_TOKEN" \ specifies your Atlassian account email address and Atlassian API token that you created earlier. For security purposes, we recommend storing the values of $USER_EMAIL and $USER_API_TOKEN as external environment variables, instead of hardcoding them into the script.

• On line number 9, \"value\": $METRIC_VALUE, specifies the value you want to push for your component’s metric. The value is a number, for example, 123 or 4.56. In this line, replace $METRIC_VALUE with the numerical value for the metric.

• On line number 10, \"timestamp\": \"$(date -u +'%Y-%m-%dT%H:%M:%SZ')\" specifies the timestamp when the metric value was calculated. This is an optional variable. You can:

  • remove the line, in which case the timestamp is set to when Compass receives the metric value

  • leave the line as is, in which case the timestamp is set to the time and date when the cURL command runs

  • replace $(date -u +'%Y-%m-%dT%H:%M:%SZ') with a specific timestamp following the ISO-8601 standard of YYYY-MM-DDThh:mm:ssZ, where:

    • YYYY-MM-DD represents the date in year, month, and day
    • T is the delimiter between the date and the time
    • hh:mm:ss is the time in hours, minutes, and seconds
    • Z represents zero UTC offset

  • An example of the timestamp value in this line is \"timestamp\": \"2022-01-31T01:23:45Z\".

Additionally, on line number 8, \"metricSourceId\": \"ari:cloud:compass:...:metric-source/.../...\", specifies the auto-generated IDs of the component and the metric to which you are pushing the value to. Do not change the values on this line.

After editing the cURL command, run it to push values to the component's metric.

Step 4: Run the cURL command

After adding all variable values, test the cURL command by running it in Terminal on Mac or Linux, Command Prompt on Windows. On a Windows computer, you might need to download cURL and adjust the command’s syntax before running it.

If the command is successful, you’ll see the metric value on your component in Compass.