Dataframes endpoint

POST
/v2/dataframes

Add dataframes into the storage backend

Add dataframes into the storage backend.

Name

In

Type

Description

dataframes

body

list

List of dataframes to add.

Request Example

In the body:

{
    "dataframes": [
        {
            "period": {
                "begin": "20190723T122810Z",
                "end": "20190723T132810Z"
            },
            "usage": {
                "metric_one": [
                    {
                        "vol": {
                            "unit": "GiB",
                            "qty": 1.2
                        },
                        "rating": {
                            "price": 0.04
                        },
                        "groupby": {
                            "group_one": "one",
                            "group_two": "two"
                        },
                        "metadata": {
                            "attr_one": "one",
                            "attr_two": "two"
                        }
                    }
                ],
                "metric_two": [
                    {
                        "vol": {
                            "unit": "MB",
                            "qty": 200.4
                        },
                        "rating": {
                            "price": 0.06
                        },
                        "groupby": {
                            "group_one": "one",
                            "group_two": "two"
                        },
                        "metadata": {
                            "attr_one": "one",
                            "attr_two": "two"
                        }
                    }
                ]
            }
        },
        {
            "period": {
                "begin": "20190823T122810Z",
                "end": "20190823T132810Z"
            },
            "usage": {
                "metric_one": [
                    {
                        "vol": {
                            "unit": "GiB",
                            "qty": 2.4
                        },
                        "rating": {
                            "price": 0.08
                        },
                        "groupby": {
                            "group_one": "one",
                            "group_two": "two"
                        },
                        "metadata": {
                            "attr_one": "one",
                            "attr_two": "two"
                        }
                    }
                ],
                "metric_two": [
                    {
                        "vol": {
                            "unit": "MB",
                            "qty": 400.8
                        },
                        "rating": {
                            "price": 0.12
                        },
                        "groupby": {
                            "group_one": "one",
                            "group_two": "two"
                        },
                        "metadata": {
                            "attr_one": "one",
                            "attr_two": "two"
                        }
                    }
                ]
            }
        }
    ]
}

Status codes

Success

Code

Reason
204 - No Content

Request was successful even though no content is to be returned.

Error

Code

Reason
400 - Bad Request

Invalid request.
401 - Unauthorized

Unauthenticated user.
403 - Forbidden

Forbidden operation for the authentified user.
405 - Method Not Allowed

The method is not allowed for the requested URL.

Response

No content is to be returned.

GET
/v2/dataframes

Get dataframes from the storage backend

Get dataframes from the storage backend.

Name

In

Type

Description

limit (Optional)

query

int

For pagination. The maximum number of results to return.

offset (Optional)

query

int

For pagination. The index of the first element that should be returned.

begin (Optional)

query

iso8601 timestamp

Begin of the period for which the dataframes are required.

end (Optional)

query

iso8601 timestamp

End of the period for which the dataframes are required.

filters (Optional)

query

dict

Optional filters.

Status codes

Success

Code

Reason
200 - OK

Request was successful.

Error

Code

Reason
400 - Bad Request

Invalid request.
401 - Unauthorized

Unauthenticated user.
403 - Forbidden

Forbidden operation for the authentified user.
405 - Method Not Allowed

The method is not allowed for the requested URL.

Response

Name

In

Type

Description

total

body

int

Total of datapoints matching the query parameters.

dataframes

body

list

List of dataframes matching the query parameters.

Response Example

{
    "total": 3,
    "dataframes": [
        {
            "usage": {
                "metric_one": [
                    {
                        "vol": {
                            "unit": "GiB",
                            "qty": 1.2
                        },
                        "rating": {
                            "price": 0.04
                        },
                        "groupby": {
                            "group_one": "one",
                            "group_two": "two"
                        },
                        "metadata": {
                            "attr_one": "one",
                            "attr_two": "two"
                        }
                    }
                ],
                "metric_two": [
                    {
                        "vol": {
                            "unit": "GiB",
                            "qty": 1.2
                        },
                        "rating": {
                            "price": 0.04
                        },
                        "groupby": {
                            "group_one": "one",
                            "group_two": "two"
                        },
                        "metadata": {
                            "attr_one": "one",
                            "attr_two": "two"
                        }
                    }
                ]
            },
            "period": {
                "begin": "2019-07-23T12:28:10+00:00",
                "end": "2019-07-23T13:28:10+00:00"
            }
        },
        {
            "usage": {
                "volume.size": [
                    {
                        "vol": {
                            "unit": "GiB",
                            "qty": 1.9
                        },
                        "rating": {
                            "price": 3.8
                        },
                        "groupby": {
                            "project_id": "8ace6f139a1742548e09f1e446bc9737",
                            "user_id": "b28fd3f448c34c17bf70e32886900eed",
                            "id": "be966c6d-78a0-42cf-bab9-e833ed996dee"
                        },
                        "metadata": {
                            "volume_type": ""
                        }
                    }
                ]
            },
            "period": {
                "begin": "2019-08-01T01:00:00+00:00",
                "end": "2019-08-01T02:00:00+00:00"
            }
        }
    ]
}

Scope state endpoint

GET
/v2/scope

Get the status of several scopes

Returns the status of several scopes.

Name

In

Type

Description

collector (Optional)

query

string

Filter on collector.

fetcher (Optional)

query

string

Filter on fetcher.

limit (Optional)

query

int

For pagination. The maximum number of results to return.

offset (Optional)

query

int

For pagination. The index of the first element that should be returned.

scope_id (Optional)

query

string

Filter on scope.

scope_key (Optional)

query

string

Filter on scope_key.

Status codes

Success

Code

Reason
200 - OK

Request was successful.

Error

Code

Reason
400 - Bad Request

Invalid request.
403 - Forbidden

Forbidden operation for the authentified user.
404 - Not Found

Not found
405 - Method Not Allowed

The method is not allowed for the requested URL.

Response

Name

In

Type

Description

collector

body

string

Collector for the given scope

fetcher

body

string

Fetcher for the given scope

state

body

iso8601 timestamp

State of the scope. This variable represents the last processed timestamp for the storage state element. It is DEPRECATED, and it will be removed in upcoming releases. The alternative is last_processed_timestamp.

last_processed_timestamp

body

iso8601 timestamp

It represents the last processed timestamp for the storage state element.

scope_id

body

string

Scope

scope_key

body

string

Scope key for the given scope

Response Example

{
    "results": [
        {
            "collector": "gnocchi",
            "fetcher": "keystone",
            "scope_id": "7a7e5183264644a7a79530eb56e59941",
            "scope_key": "project_id",
            "last_processed_timestamp": "2019-05-09 10:00:00"
        },
        {
            "collector": "gnocchi",
            "fetcher": "keystone",
            "scope_id": "9084fadcbd46481788e0ad7405dcbf12",
            "scope_key": "project_id",
            "last_processed_timestamp": "2019-05-08 03:00:00"
        },
        {
            "collector": "gnocchi",
            "fetcher": "keystone",
            "scope_id": "1f41d183fca5490ebda5c63fbaca026a",
            "scope_key": "project_id",
            "last_processed_timestamp": "2019-05-06 22:00:00"
        }
    ]
}
PUT
/v2/scope

Reset the status of several scopes

Reset the status of several scopes.

Name

In

Type

Description

state

body

iso8601 timestamp

State of the scope. This variable represents the last processed timestamp for the storage state element. It is DEPRECATED, and it will be removed in upcoming releases. The alternative is last_processed_timestamp.

last_processed_timestamp

body

iso8601 timestamp

It represents the last processed timestamp for the storage state element.

collector (Optional)

body

string

Filter on collector.

fetcher (Optional)

body

string

Filter on fetcher.

scope_id (Optional)

body

string

Filter on scope.

scope_key (Optional)

body

string

Filter on scope_key.

all_scopes (Optional)

body

bool

Confirmation whether all scopes must be reset

Status codes

Success

Code

Reason
202 - Accepted

Request has been accepted for asynchronous processing.

Error

Code

Reason
400 - Bad Request

Invalid request.
403 - Forbidden

Forbidden operation for the authentified user.
404 - Not Found

Not found
405 - Method Not Allowed

The method is not allowed for the requested URL.

Summary endpoint

GET
/v2/summary

Get a rating summary

Get a rating summary for one or several tenants.

Name

In

Type

Description

limit (Optional)

query

int

For pagination. The maximum number of results to return.

offset (Optional)

query

int

For pagination. The index of the first element that should be returned.

begin (Optional)

query

iso8601 timestamp

Begin of the period for which the summary is required.

end (Optional)

query

iso8601 timestamp

End of the period for which the summary is required.

groupby (Optional)

query

list of strings

Optional attributes to group the summary by.

filters (Optional)

query

dict

Optional filters.

custom_fields (Optional)

query

list of strings

Optional attributes to customize the summary GET API response. When using this parameter, users can create custom reports. The default behavior is to list the sum of the quantity and the sum of the price, which is projected as rate field. The default value for the custom_fields parameter is SUM(qty) AS qty, SUM(price) AS rate. One can customize this field as they wish with InfluxDB queries. The following statements "select", "from", "drop", "delete", "create", "alter", "insert", "update" are not allowed though. For instance, if one wants to retrieve the quantity field as the last value of the quantity, and not the sum (this is quite interesting when generating reports for storage values), the user can send the parameter as last(qty) AS qty, SUM(price) AS rate. To discover all possible fields that one can work with, the user can also use * as a parameter.

Currently this feature only works for Influx storage backend. It (the feature) depends on the storage backend driver to support it. If the user tries to set this configuration while using other storage backends, it will be ignored.

Status codes

Success

Code

Reason
200 - OK

Request was successful.

Error

Code

Reason
400 - Bad Request

Invalid request.
403 - Forbidden

Forbidden operation for the authentified user.
405 - Method Not Allowed

The method is not allowed for the requested URL.

Response

The response has the following format:

{
    "columns": [
        "begin",
        "end",
        "qty",
        "rate",
        "group1",
        "group2",
    ],
    "results": [
        [
            "2019-06-01T00:00:00Z",
            "2019-07-01T00:00:00Z",
            2590.421676635742,
            1295.210838317871,
            "group1",
            "group2",
        ]
    ],
    "total": 4
}

total is the total amount of found elements. columns contains the name of the columns for each element of results. The columns are the four mandatory ones (begin, end, qty, rate) along with each attribute the result is grouped by.

Note

It is also possible to group data by time, in order to obtain timeseries. In order to do this, group by time. No extra column will be added, but you’ll get one entry per collect period in the queried timeframe. See examples below.

Name

In

Type

Description

begin

body

iso8601 timestamp

Begin of the period for the item.

end

body

iso8601 timestamp

End of the period for the item.

qty

body

float

Qty for the item in the specified period.

rate

body

float

Rate for the item in the specified period.

Response Example

Grouping by time and project_id:

curl "http://cloudkitty-api:8889/v2/summary?groupby=time&groupby=project_id&limit=3"

{
  "total": 232,
  "columns": [
    "begin",
    "end",
    "qty",
    "rate",
    "project_id"
  ],
  "results": [
    [
      "2019-10-01T06:00:00+02:00",
      "2019-10-01T07:00:00+02:00",
      3.5533905029296875,
      1.7766952514648438,
      "84631866b2d84db49b29828052bdc287"
    ],
    [
      "2019-10-01T07:00:00+02:00",
      "2019-10-01T08:00:00+02:00",
      3.5533905029296875,
      1.7766952514648438,
      "84631866b2d84db49b29828052bdc287"
    ],
    [
      "2019-10-01T08:00:00+02:00",
      "2019-10-01T09:00:00+02:00",
      3.5533905029296875,
      1.7766952514648438,
      "84631866b2d84db49b29828052bdc287"
    ]
  ]
}

curl "http://cloudkitty-api:8889/v2/summary?filters=project_id%3Afe9c35372db6420089883805b37a34af&groupby=type&groupby=project_id"

{
    "columns": [
        "begin",
        "end",
        "qty",
        "rate",
        "project_id",
        "type"
    ],
    "results": [
        [
            "2019-06-01T00:00:00Z",
            "2019-07-01T00:00:00Z",
            2590.421676635742,
            1295.210838317871,
            "fe9c35372db6420089883805b37a34af",
            "image.size"
        ],
        [
            "2019-06-01T00:00:00Z",
            "2019-07-01T00:00:00Z",
            1354,
            3625,
            "fe9c35372db6420089883805b37a34af",
            "instance"
        ],
        [
            "2019-06-01T00:00:00Z",
            "2019-07-01T00:00:00Z",
            502,
            502,
            "fe9c35372db6420089883805b37a34af",
            "ip.floating"
        ],
        [
            "2019-06-01T00:00:00Z",
            "2019-07-01T00:00:00Z",
            175.9,
            351.8,
            "fe9c35372db6420089883805b37a34af",
            "volume.size"
        ]
    ],
    "total": 4
}