Skip to content

Latest commit

 

History

History
180 lines (130 loc) · 9.44 KB

rest-endpoints.adoc

File metadata and controls

180 lines (130 loc) · 9.44 KB
Raw

REST endpoints

This section describes the REST-API, that monitoring agents would use to retrieve the collected metrics. (Java-) methods mentioned refer to the respective Objects in the Java API. See also app-programming-model.adoc

Note
 While vendors are required to provide a /metrics endpoint, as described in this section, it is permissible for implementations to be configurable to run without the endpoint in cases where the metrics capability is not wanted or a different monitoring backend is in use that does not require the endpoint.

Prometheus / OpenMetrics formats

The REST API must respond to GET requests with data formatted according to the Prometheus text-based exposition format, version 0.0.4 (hereafter Prometheus format). For details of how to format metrics data in this format, see Prometheus format.

Implementations may additionally provide the ability to respond to GET requests with data formatted according to the OpenMetrics exposition format, version 1.0 (hereafter OpenMetrics format). For details on how to format metrics data in this format, see OpenMetrics format.

This section provides the details of how to map from the Gauge, Counter, Timer and Histogram types defined in this specification into appropriate fields in the Prometheus format.

Details of how to format metric names, including conventions, special character mapping and placement of the unit (if provided) in the name, are as described by the Prometheus format and OpenMetrics format documentation.

Quantile values, as used in Histogram and Timer output, should represent recent values (typically from the last 5-10 minutes). If no data is available from that timeframe, the value must be set to NaN.

Gauge

Example Gauge with unit celsius in Prometheus format.
# HELP current_temperature_celsius The current temperature. (1)
# TYPE current_temperature_celsius gauge (2)
current_temperature_celsius{_scope="application",server="front_office"} 36.2 (3)

  1. The description of the gauge, from the getDescription() method of the Metadata associated to the gauge, must be provided in the HELP line

  2. The type of the metric, in this case gauge, must be shown in the TYPE line

  3. The value specified must be the value of the gauge’s getValue() method. Tags, if provided, are included in brackets separated by commas.

Counter

Example Counter with unit events in Prometheus format.
# HELP messages_processed_events_total Number of messages handled (1)
# TYPE messages_processed_events_total counter (2)
messages_processed_events_total{_scope="application"} 1.0 (3)

  1. The description of the counter must be provided in the HELP line

  2. The type of the metric, in this case counter, must be shown in the TYPE line

  3. The value specified must be the value of the counter’s getCount() method. Tags, if provided, are included in brackets separated by commas. By convention, _total should be added to the end of the counter name.

Histogram

Example Histogram with unit meters in Prometheus format.
# HELP distance_to_hole_meters_max Distance of golf ball to hole (1)
# TYPE distance_to_hole_meters_max gauge (2)
distance_to_hole_meters_max{_scope="golf_stats"} 12.722726616315509 (3)
# HELP distance_to_hole_meters Distance of golf ball to hole (1)
# TYPE distance_to_hole_meters summary (2)
distance_to_hole_meters{_scope="golf_stats",quantile="0.5"} 2.8748779296875 (3)
distance_to_hole_meters{_scope="golf_stats",quantile="0.75"} 4.4998779296875 (3)
distance_to_hole_meters{_scope="golf_stats",quantile="0.95"} 7.9998779296875 (3)
distance_to_hole_meters{_scope="golf_stats",quantile="0.98"} 9.4998779296875 (3)
distance_to_hole_meters{_scope="golf_stats",quantile="0.99"} 11.9998779296875 (3)
distance_to_hole_meters{_scope="golf_stats",quantile="0.999"} 12.9998779296875 (3)
distance_to_hole_meters_count{_scope="golf_stats"} 487.0 (3)
distance_to_hole_meters_sum{_scope="golf_stats"} 1569.3785694223322 (3)

Histogram output is comprised of a maximum section and a summary section.

  1. The description of the histogram must be provided on the HELP lines for the maximum and summary

  2. The type of the metrics, in this case gauge (for the maximum) and summary for the summary. The summary type is comprised of the count, sum and multiple quantile values.

  3. The value of each metric included in the output is described in the table below. Tags, if provided, are included in brackets separated by commas. Percentile metrics include a quantile label that is merged with the metric’s tags.

Table 1. Prometheus format mapping for a Histogram metric
Suffix{label} TYPE Value (Histogram method) Units

<units>_max

Gauge

getSnapshot().getMax()

<units>

<units>{quantile="0.5"}

Summary

getSnapshot().getValue(0.5)

<units>

<units>{quantile="0.75"}

Summary

getSnapshot().getValue(0.75)

<units>

<units>{quantile="0.95"}

Summary

getSnapshot().getValue(0.95)

<units>

<units>{quantile="0.98"}

Summary

getSnapshot().getValue(0.98)

<units>

<units>{quantile="0.99"}

Summary

getSnapshot().getValue(0.99)

<units>

<units>{quantile="0.999"}

Summary

getSnapshot().getValue(0.999)

<units>

<units>_count

Summary

getCount()

<units>

<units>_sum

Summary

getSum()

<units>

Timer

Example Timer in Prometheus format. Timers use seconds as the unit.
# HELP myClass_myMethod_seconds duration of myMethod (1)
# TYPE myClass_myMethod_seconds summary (2)
myClass_myMethod_seconds{_scope="vendor",quantile="0.5"} 0.0524288 (3)
myClass_myMethod_seconds{_scope="vendor",quantile="0.75"} 0.0524288 (3)
myClass_myMethod_seconds{_scope="vendor",quantile="0.95"} 0.054525952 (3)
myClass_myMethod_seconds{_scope="vendor",quantile="0.98"} 0.054525952 (3)
myClass_myMethod_seconds{_scope="vendor",quantile="0.99"} 0.054525952 (3)
myClass_myMethod_seconds{_scope="vendor",quantile="0.999"} 0.054525952 (3)
myClass_myMethod_seconds_count{_scope="vendor"} 100.0 (3)
myClass_myMethod_seconds_sum{_scope="vendor"} 5.310349419 (3)
# HELP myClass_myMethod_seconds_max duration of myMethod (1)
# TYPE myClass_myMethod_seconds_max gauge (2)
myClass_myMethod_seconds_max{_scope="vendor"} 0.05507899 (3)

Timer output is comprised of a maximum section and a summary section.

  1. The description of the timer must be provided on the HELP lines for the maximum and summary

  2. The type of the metrics, in this case gauge (for the maximum) and summary for the summary. The summary type is comprised of the count, sum and multiple quantile values.

  3. The value of each metric included in the output is described in the table below. Tags, if provided, are included in brackets separated by commas. Percentile metrics include a quantile label that is merged with the metric’s tags.

Table 2. Prometheus format mapping for a Timer metric
Suffix{label} TYPE Value (Timer method) Units

max_seconds

Gauge

getSnapshot().getMax()

SECONDS1

seconds{quantile="0.5"}

Summary

getSnapshot().getValue(0.5)

SECONDS1

seconds{quantile="0.75"}

Summary

getSnapshot().getValue(0.75)

SECONDS1

seconds{quantile="0.95"}

Summary

getSnapshot().getValue(0.95)

SECONDS1

seconds{quantile="0.98"}

Summary

getSnapshot().getValue(0.98)

SECONDS1

seconds{quantile="0.99"}

Summary

getSnapshot().getValue(0.99)

SECONDS1

seconds{quantile="0.999"}

Summary

getSnapshot().getValue(0.999)

SECONDS1

seconds_count

Summary

getCount()

SECONDS1

seconds_sum

Summary

getElapsedTime()

SECONDS1

1 The implementation is expected to convert the result returned by the Timer into seconds

Security

It must be possible to secure the endpoints via the usual means. The definition of 'usual means' is in this version of the specification implementation specific.

In case of a secured endpoint, accessing /metrics without valid credentials must return a 401 Unauthorized header.

A server SHOULD implement TLS encryption by default.

It is allowed to ignore security for trusted origins (e.g. localhost)