![[17.0.0.3 and later]](../ng_v17003plus.gif)
MicroProfile metrics REST API
The mpMetrics-1.0 and mpMetrics-1.1 features provide a REST API to display metrics for administrators to access.
Formats
- 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.
REST endpoints
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. |
Connecting to data stores and monitoring tools
Administrators can connect their application metrics to other tools and stacks that can analyze and monitor the metric information.
By default, the /metrics endpoint returns data in a format that is compatible with Prometheus. To connect your Liberty server to Prometheus, configure Prometheus to use the https://host:https_port/metrics endpoint.
The JSON format can be used by other metrics collection tools that understand JSON. For example, the collectd curl_json plug-in can be configured to interpret the JSON format from MicroProfile metrics. collectd can then forward the information to various different tools, such as Graphite.
Prometheus format details
The Prometheus text format is based on the 0.0.4 exposition format that is described in Prometheus documentation. Where available, metadata is provided for each metric. The # Help line contains the description of the metric. Any tags present in the metadata are provided as Prometheus labels. The metric's unit is appended at the end of the metric name for gauges and histograms.
# TYPE application:cost_dollars gauge
# HELP application:cost_dollars The running cost of the server in dollars.
application:cost_dollars 80
# TYPE application:visitors counter
# HELP application:visitors The number of unique visitors
application:visitors 80
# 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
# 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
# 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
JSON format details - GET
The JSON format returns data that is formatted in a tree. Each metric is referenced by the name and either the value for gauges and counters or a map for meters, histograms, and timers.
{
"application": {
"hitCount": 45
},
"base": {
"thread.count" : 33,
"thread.max.count" : 47
},
"vendor": {...}
}
{
"hitCount": 45
}
{
"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). |
{
"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. |
{
"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. |
JSON format details - OPTIONS
{
"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"
}
}