Overview

Media Type

The API uses JSON to communicate with clients.

You should add the following accept header to your requests:

Accept: application/json

When you send JSON data with a POST or PUT request, you must add the following content type header:

Content-Type: application/json

JSON format

The server does not include null or empty entity properties in JSON representations.

// Metric with data
{
  "id": "paris01.web001.example.com.cpu.usage",
  "data": [
    {"timestamp": 10101010101, "value": 25.73}
  ]
}

// Metric without data
{
  "id": "paris01.web001.example.com.cpu.usage"
}

Tenant Header

Hawkular Metrics is a multi-tenant time-series data store. Your requests to tenant-dependent resources must include a tenant header:

Hawkular-Tenant: my-tenant

Timestamps

The API understands all timestamps as milliseconds since January 1, 1970, 00:00:00 UTC.

Response codes

Resources in the API follow response codes conventions, listed below.

Table 1. Response codes conventions
Response code Meaning

200 Ok

The operation completed successfully.

201 Created

A POST or PUT operation to create an entity completed successfully. The reponse should contain a Location header.

204 No Content

The operation completed successfully but result entity is null (object) or empty (array). Empty arrays are not sent in the response body.

400 Bad Request

The operation could not be processed. It could be due to:

  • Missing or malformed request entity

  • Missing header/query parameter

  • Malformed path/header/query parameter

  • Invalid parameters (breaking business rules)

404 Not Found

Resource denoted by the URI does not exist.

405 Method Not Allowed

Resource denoted by the URI does not support the operation type.

406 Not Acceptable

Cannot reply in a format accepted by the client (specified in Accept request header).

409 Conflict

A POST or PUT operation could not be performed because it conflicts with an existing entity.

415 Unsupported Media Type

Invalid request entity format. For example, text/plain whereas application/json is expected.

500 Internal Server Error

Resource operation failed unexpectedly.

503 Service Unavailable

The server failed to initialize or the storage backend is not ready yet.

Error responses

Error responses may include an ApiError entity in the body.

Sample error entity
{"errorMsg":"Tenant is not specified. Use 'Hawkular-Tenant' header."}

Time ranges

Many resource operations need a time range restriction to be processed.

Such operations accept two timestamp query parameters:

  • start: the beginning of the time range, inclusive

  • end: the end of the time range, exclusive

Either or both of them can be omitted. start defaults to now minus 8 eight hours. end defaults to now.

end must be strictly bigger than start otherwise the resource operation returns a 400 Bad Request response.

Sample operations with time range query parameters
# Implicit time range
/hawkular/metrics/gauges/paris01.web001.example.com.cpu.usage/data

# Implicit time range
/hawkular/metrics/gauges/paris01.web001.example.com.cpu.usage/data?start=10101010

# Explicit time range
/hawkular/metrics/gauges/paris01.web001.example.com.cpu.usage/data?start=10101010&end=20202020

# Implicit time range
/hawkular/metrics/gauges/paris01.web001.example.com.cpu.usage/data?end=20202020

Bucket parameters

The API offers the ability to retrieve statistics on gauges, counter and availability metrics. To compute these statistics, Hawkular Metrics slices a given time range into buckets.

The size of buckets is configurable. This allows to send a query to get, for example, monthly statistics over a year of data, or hourly statistics over a week of data.

Bucket size is configured with either the buckets or the bucketDuration query parameter, exclusively:

  • buckets indicates the desired number of buckets over the specified timerange

  • bucketDuration forces bucket size to the specified amount of time

bucketDuration is a duration-formatted string.

If both parameters are specified, the resource operation returns a 400 Bad Request response.

Sample operations with bucket query parameters
# Desired number of buckets
/hawkular/metrics/gauges/paris01.web001.example.com.cpu.usage/data?start=10101010&end=20202020&buckets=10

# Desired bucket size
/hawkular/metrics/gauges/paris01.web001.example.com.cpu.usage/data?start=10101010&end=20202020&bucketDuration=1mn

Custom string formats

Some path or query parameters in the Metrics REST API use custom string formats.

Tags list

The parameter represents a list of tags, comma separated. A tag has the form name:value. Name and values cannot contain commas or colons.

Throughout this document, this string format is identified as tag-list.

Tags List format example
/hawkular/metrics/metrics?tags=host:web001.example.com,dc:paris01,type:system

Duration

The parameter represents an amount of time. Duration is formed of a length and a unit.

Length is a long integer (int64).

Allowed units are the following:

  • ms for milliseconds

  • s for seconds

  • mn for minutes

  • h for hours

  • d for days

Throughout this document, this string format is identified as duration.

Duration format example
/hawkular/metrics/gauges/paris01.web001.example.com.cpu.usage/data?bucketDuration=1h

Base Path

/hawkular/metrics/

REST APIs

Availability

Endpoint POST /availability

Note
Create availability metric.
Same notes as creating gauge metric apply.

Body

Required Description Data Type

Yes

-

Metric

Response

Status codes

Status Code Reason Response Model

201

Metric created successfully

-

400

Missing or invalid payload

ApiError

409

Availability metric with given id already exists

ApiError

500

Metric creation failed due to an unexpected error

ApiError

Endpoint POST /availability/data

Note
Add metric data for multiple availability metrics in a single call.

Body

Required Description Data Type

Yes

List of availability metrics

array of Availability

Response

Status codes

Status Code Reason Response Model

200

Adding data succeeded.

-

400

Missing or invalid payload

ApiError

500

Unexpected error happened while storing the data

ApiError

Endpoint GET /availability/{id}

Note
Retrieve single metric definition.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Metric’s definition was successfully retrieved.

Metric

204

Query was successful, but no metrics definition is set.

-

500

Unexpected error occurred while fetching metric’s definition.

ApiError

Endpoint GET /availability/{id}/data

Note
Retrieve availability data.
When buckets or bucketDuration query parameter is used, the time range between start and end will be divided in buckets of equal duration, and availability statistics will be computed for each bucket.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Query parameters

Parameter Required Description Type Format Allowable Values

start

No

Defaults to now - 8 hours

integer

int64

-

end

No

Defaults to now

integer

int64

-

buckets

No

Total number of buckets

integer

int32

-

bucketDuration

No

Bucket duration

string

duration

-

distinct

No

Set to true to return only distinct, contiguous values

boolean

-

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched availability data.

array of AvailabilityDataPoint

204

No availability data was found.

-

400

buckets or bucketDuration parameter is invalid, or both are used.

ApiError

500

Unexpected error occurred while fetching availability data.

ApiError

Endpoint POST /availability/{id}/data

Note
Add data for a single availability metric.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Body

Required Description Data Type

Yes

List of availability datapoints

array of AvailabilityDataPoint

Response

Status codes

Status Code Reason Response Model

200

Adding data succeeded.

-

400

Missing or invalid payload

ApiError

500

Unexpected error happened while storing the data

ApiError

Endpoint GET /availability/{id}/tags

Note
Retrieve tags associated with the metric definition.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Metric’s tags were successfully retrieved.

object

204

Query was successful, but no metrics were found.

-

500

Unexpected error occurred while fetching metric’s tags.

ApiError

Endpoint PUT /availability/{id}/tags

Note
Update tags associated with the metric definition.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Body

Required Description Data Type

Yes

-

object

Response

Status codes

Status Code Reason Response Model

200

Metric’s tags were successfully updated.

-

500

Unexpected error occurred while updating metric’s tags.

ApiError

Endpoint DELETE /availability/{id}/tags/{tags}

Note
Delete tags associated with the metric definition.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

tags

Yes

Tag list

string

tag-list

-

Response

Status codes

Status Code Reason Response Model

200

Metric’s tags were successfully deleted.

-

400

Invalid tags

ApiError

500

Unexpected error occurred while trying to delete metric’s tags.

ApiError

Counter

Endpoint POST /counters

Note
Create counter metric.
This operation also causes the rate to be calculated and persisted periodically after raw count data is persisted. Clients are not required to explicitly create a metric before storing data. Doing so however allows clients to prevent naming collisions and to specify tags and data retention.

Body

Required Description Data Type

Yes

-

Metric

Response

Status codes

Status Code Reason Response Model

201

Metric created successfully

-

400

Missing or invalid payload

ApiError

409

Counter metric with given id already exists

ApiError

500

Metric creation failed due to an unexpected error

ApiError

Endpoint POST /counters/data

Note
Add data points for multiple counters.

Body

Required Description Data Type

Yes

List of metrics

array of Counter

Response

Status codes

Status Code Reason Response Model

200

Adding data points succeeded.

-

400

Missing or invalid payload

ApiError

500

Unexpected error happened while storing the data points

ApiError

Endpoint GET /counters/{id}

Note
Retrieve a counter definition.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Metric’s definition was successfully retrieved.

Metric

204

Query was successful, but no metrics definition is set.

-

500

Unexpected error occurred while fetching metric’s definition.

ApiError

Endpoint GET /counters/{id}/data

Note
Retrieve counter data points.
When buckets or bucketDuration query parameter is used, the time range between start and end will be divided in buckets of equal duration, and metric statistics will be computed for each bucket.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Query parameters

Parameter Required Description Type Format Allowable Values

start

No

Defaults to now - 8 hours

integer

int64

-

end

No

Defaults to now

integer

int64

-

buckets

No

Total number of buckets

integer

int32

-

bucketDuration

No

Bucket duration

string

duration

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched metric data.

array of CounterDataPoint

204

No metric data was found.

-

400

buckets or bucketDuration parameter is invalid, or both are used.

ApiError

500

Unexpected error occurred while fetching metric data.

ApiError

Endpoint POST /counters/{id}/data

Note
Add data for a single counter.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Body

Required Description Data Type

Yes

List of data points containing timestamp and value

array of CounterDataPoint

Response

Status codes

Status Code Reason Response Model

200

Adding data succeeded.

-

400

Missing or invalid payload

ApiError

500

Unexpected error happened while storing the data

ApiError

Endpoint GET /counters/{id}/rate

Note
Retrieve counter rate data points.
When buckets or bucketDuration query parameter is used, the time range between start and end will be divided in buckets of equal duration, and metric statistics will be computed for each bucket.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Query parameters

Parameter Required Description Type Format Allowable Values

start

No

Defaults to now - 8 hours

integer

int64

-

end

No

Defaults to now

integer

int64

-

buckets

No

Total number of buckets

integer

int32

-

bucketDuration

No

Bucket duration

string

duration

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched metric data.

array of GaugeDataPoint

204

No metric data was found.

-

400

buckets or bucketDuration parameter is invalid, or both are used.

ApiError

500

Unexpected error occurred while fetching metric data.

ApiError

Endpoint GET /counters/{id}/tags

Note
Retrieve tags associated with the metric definition.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Metric’s tags were successfully retrieved.

object

204

Query was successful, but no metrics were found.

-

500

Unexpected error occurred while fetching metric’s tags.

ApiError

Endpoint PUT /counters/{id}/tags

Note
Update tags associated with the metric definition.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Body

Required Description Data Type

Yes

-

object

Response

Status codes

Status Code Reason Response Model

200

Metric’s tags were successfully updated.

-

500

Unexpected error occurred while updating metric’s tags.

ApiError

Endpoint DELETE /counters/{id}/tags/{tags}

Note
Delete tags associated with the metric definition.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

tags

Yes

Tag list

string

tag-list

-

Response

Status codes

Status Code Reason Response Model

200

Metric’s tags were successfully deleted.

-

400

Invalid tags

ApiError

500

Unexpected error occurred while trying to delete metric’s tags.

ApiError

Gauge

Endpoint POST /gauges

Note
Create gauge metric.
Clients are not required to explicitly create a metric before storing data. Doing so however allows clients to prevent naming collisions and to specify tags and data retention.

Body

Required Description Data Type

Yes

-

Metric

Response

Status codes

Status Code Reason Response Model

201

Metric created successfully

-

400

Missing or invalid payload

ApiError

409

Gauge metric with given id already exists

ApiError

500

Metric creation failed due to an unexpected error

ApiError

Endpoint GET /gauges/data

Note
Find stats for multiple metrics.
Fetches data points from one or more metrics that are determined using either a tags filter or a list of metric names. The time range between start and end is divided into buckets of equal size (i.e., duration) using either the buckets or bucketDuration parameter. Functions are applied to the data points in each bucket to produce statistics or aggregated metrics.

Query parameters

Parameter Required Description Type Format Allowable Values

start

No

Defaults to now - 8 hours

integer

int64

-

end

No

Defaults to now

integer

int64

-

buckets

No

Total number of buckets

integer

int32

-

bucketDuration

No

Bucket duration

string

duration

-

tags

No

List of tags filters

string

tag-list

-

metrics

No

List of metric names

array

-

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched metric data.

array of NumericBucketPoint

204

No metric data was found.

-

400

The tags parameter is required. Either the buckets or the bucketDuration parameter is required but not both.

ApiError

500

Unexpected error occurred while fetching metric data.

ApiError

Endpoint POST /gauges/data

Note
Add data for multiple gauge metrics in a single call.

Body

Required Description Data Type

Yes

List of metrics

array of Gauge

Response

Status codes

Status Code Reason Response Model

200

Adding data succeeded.

-

400

Missing or invalid payload

ApiError

500

Unexpected error happened while storing the data

ApiError

Endpoint GET /gauges/{id}

Note
Retrieve single metric definition.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Metric’s definition was successfully retrieved.

Metric

204

Query was successful, but no metrics definition is set.

-

500

Unexpected error occurred while fetching metric’s definition.

ApiError

Endpoint GET /gauges/{id}/data

Note
Retrieve gauge data.
When buckets or bucketDuration query parameter is used, the time range between start and end will be divided in buckets of equal duration, and metric statistics will be computed for each bucket.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Query parameters

Parameter Required Description Type Format Allowable Values

start

No

Defaults to now - 8 hours

integer

int64

-

end

No

Defaults to now

integer

int64

-

buckets

No

Total number of buckets

integer

int32

-

bucketDuration

No

Bucket duration

string

duration

-

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched metric data.

array of GaugeDataPoint

204

No metric data was found.

-

400

buckets or bucketDuration parameter is invalid, or both are used.

ApiError

500

Unexpected error occurred while fetching metric data.

ApiError

Endpoint POST /gauges/{id}/data

Note
Add data for a single gauge metric.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Body

Required Description Data Type

Yes

List of datapoints containing timestamp and value

array of GaugeDataPoint

Response

Status codes

Status Code Reason Response Model

200

Adding data succeeded.

-

400

Missing or invalid payload

ApiError

500

Unexpected error happened while storing the data

ApiError

Endpoint GET /gauges/{id}/periods

Note
Find condition periods.
Retrieve periods for which the condition holds true for each consecutive data point.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Query parameters

Parameter Required Description Type Format Allowable Values

start

No

Defaults to now - 8 hours

integer

int64

-

end

No

Defaults to now

integer

int64

-

threshold

Yes

A threshold against which values are compared

number

double

-

op

Yes

A comparison operation to perform between values and the threshold.

string

-

ge, gte, lt, lte, eq, neq

Response

Status codes

Status Code Reason Response Model

200

Successfully fetched periods.

array of object

204

No data was found.

-

400

Missing or invalid query parameters

ApiError

Endpoint GET /gauges/{id}/tags

Note
Retrieve tags associated with the metric definition.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Response

Status codes

Status Code Reason Response Model

200

Metric’s tags were successfully retrieved.

object

204

Query was successful, but no metrics were found.

-

500

Unexpected error occurred while fetching metric’s tags.

ApiError

Endpoint PUT /gauges/{id}/tags

Note
Update tags associated with the metric definition.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

Body

Required Description Data Type

Yes

-

object

Response

Status codes

Status Code Reason Response Model

200

Metric’s tags were successfully updated.

-

500

Unexpected error occurred while updating metric’s tags.

ApiError

Endpoint DELETE /gauges/{id}/tags/{tags}

Note
Delete tags associated with the metric definition.

Path parameters

Parameter Required Description Type Format Allowable Values

id

Yes

-

string

-

-

tags

Yes

Tag list

string

tag-list

-

Response

Status codes

Status Code Reason Response Model

200

Metric’s tags were successfully deleted.

-

400

Invalid tags

ApiError

500

Unexpected error occurred while trying to delete metric’s tags.

ApiError

Metric

Endpoint GET /metrics

Note
Find tenant’s metric definitions.
Does not include any metric values.

Query parameters

Parameter Required Description Type Format Allowable Values

type

No

Queried metric type

string

-

gauge, availability, counter

tags

No

List of tags filters

string

tag-list

-

Response

Status codes

Status Code Reason Response Model

200

Successfully retrieved at least one metric definition.

array of Metric

204

No metrics found.

-

400

Invalid type parameter type.

ApiError

500

Failed to retrieve metrics due to unexpected error.

ApiError

Endpoint POST /metrics

Note
Create metric.
Clients are not required to explicitly create a metric before storing data. Doing so however allows clients to prevent naming collisions and to specify tags and data retention.

Body

Required Description Data Type

Yes

-

Metric

Response

Status codes

Status Code Reason Response Model

201

Metric created successfully

-

400

Missing or invalid payload

ApiError

409

Metric with given id already exists

ApiError

500

Metric creation failed due to an unexpected error

ApiError

Endpoint POST /metrics/data

Note
Add data for multiple metrics in a single call.

Body

Required Description Data Type

Yes

List of metrics

MixedMetricsRequest

Response

Status codes

Status Code Reason Response Model

200

Adding data succeeded.

-

400

Missing or invalid payload.

ApiError

500

Unexpected error happened while storing the data

ApiError

Tenant

Endpoint GET /tenants

Note
Returns a list of tenants.

Response

Status codes

Status Code Reason Response Model

200

Returned a list of tenants successfully.

array of Tenant

204

No tenants were found.

-

500

Unexpected error occurred while fetching tenants.

ApiError

Endpoint POST /tenants

Note
Create a new tenant.
Clients are not required to create explicitly create a tenant before starting to store metric data. It is recommended to do so however to ensure that there are no tenant id naming collisions and to provide default data retention settings.

Body

Required Description Data Type

Yes

-

Tenant

Response

Status codes

Status Code Reason Response Model

201

Tenant has been succesfully created.

-

400

Missing or invalid retention properties.

ApiError

409

Given tenant id has already been created.

ApiError

500

An unexpected error occured while trying to create a tenant.

ApiError

Data Types

ApiError

Name Required Description Type Format Allowable Values

errorMsg

Yes

Detailed error message of what happened

string

-

-

Availability

Name Required Description Type Format Allowable Values

data

No

Availability data points

array of AvailabilityDataPoint

-

-

id

Yes

Identifier of the metric

string

-

-

AvailabilityDataPoint

Name Required Description Type Format Allowable Values

timestamp

Yes

-

integer

int64

-

value

Yes

-

string

-

up, down, unknown

Counter

Name Required Description Type Format Allowable Values

data

No

Counter data points

array of CounterDataPoint

-

-

id

Yes

Identifier of the metric

string

-

-

CounterDataPoint

Name Required Description Type Format Allowable Values

timestamp

Yes

-

integer

int64

-

value

Yes

-

integer

int64

-

Gauge

Name Required Description Type Format Allowable Values

data

No

Gauge data points

array of GaugeDataPoint

-

-

id

Yes

Identifier of the metric

string

-

-

GaugeDataPoint

Name Required Description Type Format Allowable Values

timestamp

Yes

-

integer

int64

-

value

Yes

-

number

double

-

Metric

Name Required Description Type Format Allowable Values

dataRetention

No

How long, in days, a data point of this metric stays in the system after it is stored

integer

int32

-

id

Yes

Identifier of the metric

string

-

-

tags

No

Metric tags

object

-

-

tenantId

No

Identifier of the tenant

string

-

-

type

No

Metric type

string

-

gauge, availability, counter

MixedMetricsRequest

Name Required Description Type Format Allowable Values

availabilities

No

-

array of Availability

-

-

counters

No

-

array of Counter

-

-

gauges

No

-

array of Gauge

-

-

NumericBucketPoint

Name Required Description Type Format Allowable Values

avg

No

-

number

double

-

empty

No

-

boolean

-

-

end

No

-

integer

int64

-

max

No

-

number

double

-

median

No

-

number

double

-

min

No

-

number

double

-

percentile95th

No

-

number

double

-

start

No

-

integer

int64

-

Tenant

Name Required Description Type Format Allowable Values

id

Yes

Identifier of the tenant

string

-

-

retentions

No

Retention settings for metrics, expressed in days

object

-

-