BonFIRE logo and link to main BonFIRE site

Table Of Contents

Previous topic

Quota and Usage

Next topic

Creating Experiments

This Page

Resource Usage API v1.0

Overview

The aim of the resource usage API is to allow experimenters to see what resources were utilized by a particular experiment, user, or group. This via an easy accessible interface that responds back in a computer-readable format. The interface returns some aggregated information about the resource usage in an XML format.

The API can only be accessed through the Portal, which takes care of authorization. Since the Resource Usage API is a RESTfull interface that only uses the GET method,

it can be invoked by either curl or via wget.

wget --http-user=USERNAME --http-password=PASSWORD https://portal.bonfire-project.eu/accounting?path=/experiments/123

For example, the above code snippet will return the resource usage of an experiment.

Aggregated Resource Usage Interface

To connect to this interface you have to contact:

wget https://portal.bonfire-project.eu/accounting?path=/...

/experiments/{experiment-id}

Retrieves the used resources for the experiment with ID {experiment-id}. It returns the following XML:

<?xml version="1.0" encoding="UTF-8"?>
<experiment id="/experiments/{id}">
  <sumCpu>{total number of CPU*seconds used in this Experiment}</sumCpu>
  <sumVcpu>{idem for VCPU*seconds}</sumVcpu>
  <sumMemory>{idem for memory (in MB)*seconds}</sumMemory>
  <sumStorage>
         {sum of all the storage sizes (in MB), both osimages and disks, used by the computes in this
         Experiment times (*) the time the compute is used or up until now if the computes
         is still being used}
  </sumStorage>
  <computes>
        <compute id="{full compute id}" inUse="true|false">
          <cpu>{number of CPU*seconds as defined for this compute}</cpu>
          <vcpu>{idem for VCPU*seconds}</vcpu>
          <memory>{idem for memory (in MB)*seconds}</memory>
          <sumStorage>{sum of all the storage sizes (in MB), both osimages and disks, used by this compute}</sumStorage>
          <createdTime>{epoch timestamp}</createdTime>
          <endTime>{epoch timestamp}</endTime>
          <storages>
                <storage id="{full storage id}">
                  <size>{size of this storage (in MB)}</size>
                </storage>
                ...
          </storages>
        </compute>
        ...
  </computes>
</experiment>

/groups/{group name}

Get the used resources for a specific group based on the experiments created by that group. It returns a collection of experiment elements:

<collection>
  <experiment id="..."> ... </experiment>
  ...
</collection>

/users/{username}

Get the used resources for a specific user based on the experiments created by that user. Updates made by other users are also taken into account. It also returns a collection of experiment elements:

<collection>
  <experiment id="..."> ... </experiment>
  ...
</collection>

Portal Interface

To facilitate access and provide a graphical visualisation, the portal exposes this interface on the pages for users, groups and experiments. Navigating to the respective detail pages, one will encounter a “Resource Usage” tab on each of them. Upon clicking this tab, one will be presented with a view such as the following:

../_images/resource_usage_experiment.png

Figure 1: Resource usage tab for experiments

Here, it is possible to render graphs based on the data provided by the resource usage API. Let’s take a look at how to use it in the next section.

Controls

The resource usage tab is split into two main areas: The graph area where the graph will be drawn and the parameter form. The form provides control over the request parameters:

../_images/resource_usage_form.png

Figure 2: Resource usage parameter form

  • The time interval requested can be determined using the “From” and “Until” fields. Dates need to be entered as ISO-8601 date strings in the UTC timezone.
  • Select which resources shall be queried with the checkboxes “Compute”, “Memory” and “Storage” under “Resources”.
  • The “Resolution” field lets one select the time delta between measurement points. Selecting a smaller time will cause more data points to be gathered, this may impact response times. It is recommended to consider the time interval selected with “From” and “Until”, when choosing a Resolution and vice versa.
  • Lastly, one can select, what kind of chart the data will be displayed in, using the “Chart Type” field. Available types currently include Line Chart, Area Chart, Bar Chart and Column Chart.

After all parameters are set to reasonable and meaningful values, click on the “Load” button to send a request for data. Depending on the size of the time interval and the resolution chosen, a little delay has to be expected. As soon as the data has been received, the selected graph will be drawn in the empty space above the form. An example chart can be seen in figure 3.

../_images/resource_usage_chart.png

Figure 3: Resource usage result chart

In the chart, one can see the amounts of used resources over time for the selected types of resources. In this example, because they are all drawn against the same axis, the usage graph of CPU’s is dwarfed by the storage and memory ones, as the orders of magnitude differ greatly for these types of resources. To get a better view of the CPU usage, one can deselect memory and storage resources. The value of a particular plot point can be revealed by hovering over it. The availability of plot points depends on the resolution requested.