Documentation OVH

Use Prometheus

Get an overview on how to use Prometheus for Metrics

Last updated 23th August, 2019

Objective

Prometheus is another open-source monitoring system that takes its root as a clone of Borgmon from Google. In this guide, you will learn how to use Prometheus protocol with Metrics.

Requirements

  • a valid OVH Metrics account.

Instructions

Compatibility

API Method Supported
/api/v1/query GET
/api/v1/query_range GET
/api/v1/series GET
/api/v1/label/<label_name>>/values GET
/api/v1/targets GET
/api/v1/alertmanagers GET
/api/v1/status/* GET
/api/v1/admin/* GET
/metrics/job/<some_job> POST

How to Push data

Prometheus is using the pull-based approach to gather metrics. We developed an open-source tool called Beamium in order to scrape metrics in Prometheus format. Please see the dedicated guide to use Beamium.

In case you need to push, we also support the PushGateway with the following URL:

https://metrics:[WRITE_TOKEN]@prometheus.[region].metrics.ovh.net

How to query data with PromQL

PromQL is a Query Language for Prometheus. It offers basic query capabilities, like OpenTSDB, plus a way to use operators between two series. All query documentation is available here

For example to retrieve your data, you can simply execute the following HTTP request using cURL.

$ curl 'https://u:READ_TOKEN@prometheus.REGION.metrics.ovh.net/api/v1/query_range?query=SERIES_NAME\{LABEL0_KEY="LABEL0_VALUE",LABEL1_KEY="LABEL1_VALUE"\}&start=1533127072.115&end=1533127472.115&step=2m'

where:

  • READ_TOKEN is your read token available on your OVH Metrics account
  • SERIES_NAME is the series name to retrieve. It can be for example os.cpu
  • LABEL0_KEY and LABEL1_KEY are specific labels that the series must have with
  • LABEL0_KEY values is LABEL0_VALUE and LABEL1_KEY value is LABEL1_VALUE.

PromQL valid operators

Binary operators

A few binary arithmetic operators exists in PromQL and can be used on the Metrics platform:

Operator Name Supported
+ addition
- subtraction
* multiplication
/ division
% modulo
^ power/exponentiation
== equal
!= not-equal
> greater-than
< less-than
>= greater-or-equal
<= less-or-equal
and intersection
or union
unless complement

Modulo (%) and exponentiation (^) are not yet supported accross several metrics. They both can still be applied between metrics and scalar value.

For all operators, the same precedance applies than in promQL.

Vector matching

PromQL has it's own method to manage how to match left and right entry of an operator. The valid vector matching on the Metrics platform are:

Operator Params Supported
ignoring <label list>
on <label list>
group_left <label list>
group_right <label list>

Only one keyword between on and ignoring can be applied to an operator. The same applies to group_left or group_right

Aggregation operators

The valid aggregation operators on the Metrics platform are:

Aggregation pperator Details Supported
sum calculate sum over dimensions
min select minimum over dimensions
max select maximum over dimensions
stddev calculate the average over dimensions
stdvar calculate population standard deviation over dimensions
count count number of elements in the vector
count_values count number of elements with the same value
bottomk smallest k elements by sample value
topk largest k elements by sample value
quantile calculate φ-quantile (0 ≤ φ ≤ 1) over dimensions

The aggregation operator count_values expects a label string key for each new metrics created (per different values).

Aggregation operators clauses

PromQL has it's own method to manage how to match left and right entry of an operator. The valid vector matching on the Metrics platform are:

Operator Params Supported
without <label list>
by <label list>

Only one keyword between without and by can be applied to an aggregation operator.

Supported PromQL functions

The valid promQL functions on the Metrics platform are:

Function Params Supported
abs instant-vector
absent instant-vector
ceil instant-vector
changes range-vector
clamp_max instant-vector, scalar
clamp_min instant-vector, scalar
count_scalar instant-vector
day_of_month instant-vector
day_of_week instant-vector
days_in_month instant-vector
delta range-vector
deriv range-vector
drop_common_labels instant-vector
exp instant-vector
floor instant-vector
histogram_quantile float, instant-vector
holt_winters range-vector, scalar, scalar
hour instant-vector
idelta range-vector
increase range-vector
irate range-vector
label_join instant-vector, string, string, string, string, ...
label_replace instant-vector, string, string, string, string)
ln instant-vector
log2 instant-vector
log10 instant-vector
minute instant-vector
month instant-vector
predict_linear range-vector, scalar
rate range-vector
resets range-vector
round instant-vector, (optional) scalar
scalar instant-vector
sort instant-vector
sort_desc instant-vector
sqrt instant-vector
time
timestamp instant-vector
vector scalar
year instant-vector
avg_over_time range-vector
min_over_time range-vector
max_over_time range-vector
sum_over_time range-vector
count_over_time range-vector
quantile_over_time range-vector
stddev_over_time range-vector
stdvar_over_time range-vector

PromQL examples queries

Here, you will find two valid queries examples.

For example this request will add 2 os.cpu series from host 1 and host 2 (we just replace the + character per it's URL encoded value %2B).

$ curl 'https://u:READ_TOKEN@prometheus.REGION.metrics.ovh.net/api/v1/query_range?query=os.cpu\{host="1",cpu="1"\}%2Bos.cpu\{host="2",cpu="2"\}&start=1533127072.115&end=1533127472.115&step=2m'

Our second example here will compute the rate of the os.cpu metric for the host 1 and all cpu.

$ curl 'https://u:READ_TOKEN@prometheus.REGION.metrics.ovh.net/api/v1/query_range?query=sum(rate(os.cpu\{host="1"\}\[1m\]))&start=1533127072.115&end=1533127472.115&step=2m'

To select a Time-series stored in Metrics with unvalid Prometheus character as "-" you can also use the PromQL {__name__="http-requests-total"} syntax as Time series matcher expression. Matchers other than = (!=, =~, !~) may also be used.

Go further


Cette documentation vous a-t-elle été utile ?

Génial ! Ravi d'avoir pu vous aider.

Images, contenu, structure... N'hésitez pas à nous dire pourquoi afin de la faire évoluer ensemble !

Merci beaucoup pour votre aide ! Vos retours seront étudiés au plus vite par nos équipes..


Ces guides pourraient également vous intéresser...