MicroProfile metrics REST API

The metrics endpoint provides two output formats. The format that is used for each response is dependent on the HTTP accept header of the corresponding request.

Prometheus text format

A representation of the metrics that is compatible with the Prometheus monitoring tool. This format is returned for requests with a text/plain accept header.

JSON format

A JSON representation of the metrics. This format is returned for requests with an application/json accept header.

The following table illustrates the different endpoints that can be accessed to provide metrics.

Endpoints	Request type	Supported formats	Description
/metrics	GET	JSON, Prometheus	Returns all registered metrics.
/metrics/<scope>	GET	JSON, Prometheus	Returns metrics that are registered for the respective scope.
/metrics/<scope>/<metric name>	GET	JSON, Prometheus	Returns the metrics that match the metric name for the respective scope.
/metrics	OPTIONS	JSON	Returns all registered metrics metadata.
/metrics/<scope>	OPTIONS	JSON	Returns metrics metadata registered for the respective scope.
/metrics/<scope>/<metric name>	OPTIONS	JSON	Returns metrics metadata that matches the metric name for the respective scope.

A gauge is represented by a single value. The following example shows how a gauge named cost with units in dollars would be displayed:

# TYPE application:cost_dollars gauge
# HELP application:cost_dollars The running cost of the server in dollars.
application:cost_dollars 80

The following example illustrates the generated text format for a counter. The output only includes one value for a counter.

# TYPE application:visitors counter
# HELP application:visitors The number of unique visitors
application:visitors 80

A meter is composed of multiple values. The following example shows how a meter named requests would be displayed.

# TYPE application:requests_count counter 
# HELP application:requests_count Tracks the number of requests to the server 
application:requests_count 29382
# TYPE application:requests_rate_per_second gauge 
application:requests_rate_per_second 12.223
# TYPE application:requests_one_min_rate_per_second gauge 
application:requests_one_min_rate_per_second 12.563
# TYPE application:requests_five_min_rate_per_second gauge 
application:requests_five_min_rate_per_second 12.364
# TYPE application:requests_fifteen_min_rate_per_second gauge 
application:requests_fifteen_min_rate_per_second 12.126

A histogram is composed of multiple values. The following example shows how a histogram named file_sizes, with units set in bytes would be displayed.

# TYPE application:file_sizes_mean_bytes gauge
application:file_sizes_mean_bytes 4738.231
# TYPE application:file_sizes_max_bytes gauge
application:file_sizes_max_bytes 31716
# TYPE application:file_sizes_min_bytes gauge
application:file_sizes_min_bytes 180
# TYPE application:file_sizes_stddev_bytes gauge
application:file_sizes_stddev_bytes 1054.7343037063602
# TYPE application:file_sizes_bytes summary
# HELP application:file_sizes_bytes Users file size
application:file_sizes_bytes_count 2037
application:file_sizes_bytes{quantile="0.5"} 4201
application:file_sizes_bytes{quantile="0.75"} 6175
application:file_sizes_bytes{quantile="0.95"} 13560
application:file_sizes_bytes{quantile="0.98"} 29643
application:file_sizes_bytes{quantile="0.99"} 31716
application:file_sizes_bytes{quantile="0.999"} 31716

The Timer metric is composed of multiple values. The following shows how a timer named response_time would be displayed.

# TYPE application:response_time_rate_per_second gauge 
application:response_time_rate_per_second  0.004292520715985437
# TYPE application:response_time_one_min_rate_per_second gauge 
application:response_time_one_min_rate_per_second  2.794076465421066E-14
# TYPE application:response_time_five_min_rate_per_second  gauge 
application:response_time_five_min_rate_per_second  4.800392614619373E-4
# TYPE application:response_time_fifteen_min_rate_per_second  gauge 
application:response_time_fifteen_min_rate_per_second  0.01063191047532505
# TYPE application:response_time_mean_seconds gauge 
application:response_time_mean_seconds 0.000415041
# TYPE application:response_time_max_seconds gauge 
application:response_time_max_seconds 0.0005608694
# TYPE application:response_time_min_seconds gauge 
application:response_time_min_seconds 0.000169916
# TYPE application:response_time_stddev_seconds gauge 
application:response_time_stddev_seconds 0.000652907
# TYPE application:response_time_seconds summary 
# HELP application:response_time_seconds Server response time for /index.html
application:response_time_seconds_count 80
application:response_time_seconds{quantile="0.5"} 0.0002933240
application:response_time_seconds{quantile="0.75"} 0.000344914
application:response_time_seconds{quantile="0.95"} 0.000543647
application:response_time_seconds{quantile="0.98"} 0.002706543
application:response_time_seconds{quantile="0.99"} 0.005608694
application:response_time_seconds{quantile="0.999"} 0.005608694

If /metrics is requested, then the data for the scopes is wrapped in the scope name:

{
  "application": {
    "hitCount": 45
  },
  "base": {
     "thread.count" : 33,
     "thread.max.count" : 47
  },
  "vendor": {...}
}

For gauges and counters, the value is the value of the metric. The following example illustrates the return for a call to /metrics/application.

{
  "hitCount": 45
}

The following example illustrates a JSON object for a meter:

{
  "requests": {
    "count": 29382,
    "meanRate": 12.223,
    "oneMinRate": 12.563,
    "fiveMinRate": 12.364,
    "fifteenMinRate": 12.126,
  }
}

In the example, the following keys are present:

Key	Value
count	A count of the number of events.
meanRate	The mean rate since the metric was registered (events/second).
oneMinRate	The mean rate for the last minute (events/second).
fiveMinRate	The mean rate for the last 5 minutes (events/second).
fifteenMinRate	The mean rate for the last 15 minutes (events/second).

The following example illustrates a JSON object for a histogram:

{ 
"file_sizes": {
    "count":2,
    "min":-1624,
    "max":26,
    "mean":-799.0,
    "stddev":825.0,
    "p50":26.0,
    "p75":26.0,
    "p95":26.0,
    "p98":26.0,
    "p99":26.0,
    "p999":26.0
  }
}

In the example, the following keys are present:

Key	Value
count	A count of the number of events.
min	The minimum value recorded.
max	The maximum value recorded.
mean	The average value.
stddev	The standard deviation.
p50	The value at the 50th percentile, same as the median.
p75	The value at the 75th percentile.
p95	The value at the 95th percentile.
p98	The value at the 98th percentile.
p99	The value at the 99th percentile.
p999	The value at the 999th percentile.

The following example illustrates a JSON object for a timer:

{
  "responseTime": {
    "count": 29382,
    "meanRate":12.185627192860734,
    "oneMinRate": 12.563,
    "fiveMinRate": 12.364,
    "fifteenMinRate": 12.126,
    "min":169916,
    "max":5608694,
    "mean":415041.00024926325,
    "stddev":652907.9633011606,
    "p50":293324.0,
    "p75":344914.0,
    "p95":543647.0,
    "p98":2706543.0,
    "p99":5608694.0,
    "p999":5608694.0
  }
}

Key	Value
count	A count of the number of events.
meanRate	The mean rate since the metric was registered (events/second).
oneMinRate	The mean rate for the last minute (events/second).
fiveMinRate	The mean rate for the last 5 minutes (events/second).
fifteenMinRate	The mean rate for the last fifteen minutes (events/second).
min	The minimum value recorded.
max	The maximum value recorded.
mean	The average value.
stddev	The standard deviation.
p50	The value at the 50th percentile, same as the median.
p75	The value at the 75th percentile.
p95	The value at the 95th percentile.
p98	The value at the 98th percentile.
p99	The value at the 99th percentile.
p999	The value at the 999th percentile.

Metadata is displayed by using the same tree style, with sub trees for the sub resources. The name of the metric is mapped to its metadata values. For example, if GET /metrics/applications displays the following multiple values:

{
  "fooVal": 12345,
  "barVal": 42
}

Then OPTIONS /metrics/application displays:

{
  "fooVal": {
    "unit": "milliseconds",
    "type": "gauge",
    "description": "The average duration of foo requests during last 5 minutes",
    "displayName": "Duration of foo",
    "tags": "app=webshop"
  },
  "barVal": {
    "unit": "megabytes",
    "type": "gauge",
    "tags": "component=backend,app=webshop"
  }
}