
:guide-id: configuration-metrics
:guide-title: Gaining insights with metrics
:guide-summary: Collect metrics to gain insights about state and activities of a running instance of {project_name}.
:guide-priority: 999
:guide-tile-visible: true
:version: 26.2.2

include::../attributes.adoc[]

[[configuration-metrics]]
= Gaining insights with metrics

ifeval::["" == "true"]
WARNING: This {section} is describing a feature which is currently in preview.
ifeval::["" == ""]
Please provide your feedback while we’re continuing to work on this.
endif::[]
ifeval::["" != ""]
Please provide your feedback by link:[joining this discussion] while we’re continuing to work on this.
endif::[]
endif::[]


{project_name} has built in support for metrics. This {section} describes how to enable and configure server metrics.

== Enabling Metrics

It is possible to enable metrics using the build time option `metrics-enabled`:

[source,bash]
----
bin/kc.[sh|bat] start --metrics-enabled=true
----

== Querying Metrics

{project_name} exposes metrics at the following endpoint on the management interface at:

* `/metrics`

For more information about the management interface, see link:{links_server_management-interface_url}[{links_server_management-interface_name}].
The response from the endpoint uses a `application/openmetrics-text` content type and it is based on the Prometheus (OpenMetrics) text format. The snippet below
is an example of a response:

[source]
----
# HELP base_gc_total Displays the total number of collections that have occurred. This attribute lists -1 if the collection count is undefined for this collector.
# TYPE base_gc_total counter
base_gc_total{name="G1 Young Generation",} 14.0
# HELP jvm_memory_usage_after_gc_percent The percentage of long-lived heap pool used after the last GC event, in the range [0..1]
# TYPE jvm_memory_usage_after_gc_percent gauge
jvm_memory_usage_after_gc_percent{area="heap",pool="long-lived",} 0.0
# HELP jvm_threads_peak_threads The peak live thread count since the Java virtual machine started or peak was reset
# TYPE jvm_threads_peak_threads gauge
jvm_threads_peak_threads 113.0
# HELP agroal_active_count Number of active connections. These connections are in use and not available to be acquired.
# TYPE agroal_active_count gauge
agroal_active_count{datasource="default",} 0.0
# HELP base_memory_maxHeap_bytes Displays the maximum amount of memory, in bytes, that can be used for memory management.
# TYPE base_memory_maxHeap_bytes gauge
base_memory_maxHeap_bytes 1.6781410304E10
# HELP process_start_time_seconds Start time of the process since unix epoch.
# TYPE process_start_time_seconds gauge
process_start_time_seconds 1.675188449054E9
# HELP system_load_average_1m The sum of the number of runnable entities queued to available processors and the number of runnable entities running on the available processors averaged over a period of time
# TYPE system_load_average_1m gauge
system_load_average_1m 4.005859375

...
----

== Next steps

Read the {sections} link:{links_observability_keycloak-service-level-indicators_url}[{links_observability_keycloak-service-level-indicators_name}] and link:{links_observability_metrics-for-troubleshooting_url}[{links_observability_metrics-for-troubleshooting_name}] to see how to use the metrics.


== Relevant options

[cols="12a,4",role="options"]
|===
| |Value

|
[.options-key]#``cache-metrics-histograms-enabled``# 

[.options-description]#Enable histograms for metrics for the embedded caches.#

[role="options-extended"]
--


*CLI:* `--cache-metrics-histograms-enabled` +
*Env:* `KC_CACHE_METRICS_HISTOGRAMS_ENABLED`
--

Available only when metrics are enabled


|
`+true+`, `+false+` (default)

|
[.options-key]#``http-metrics-histograms-enabled``# 

[.options-description]#Enables a histogram with default buckets for the duration of HTTP server requests.#

[role="options-extended"]
--


*CLI:* `--http-metrics-histograms-enabled` +
*Env:* `KC_HTTP_METRICS_HISTOGRAMS_ENABLED`
--

Available only when metrics are enabled


|
`+true+`, `+false+` (default)

|
[.options-key]#``http-metrics-slos``# 

[.options-description]#Service level objectives for HTTP server requests.#

[role="options-extended"]
--
[.options-description-extended]#Use this instead of the default histogram, or use it in combination to add additional buckets. Specify a list of comma-separated values defined in milliseconds. Example with buckets from 5ms to 10s: 5,10,25,50,250,500,1000,2500,5000,10000#

*CLI:* `--http-metrics-slos` +
*Env:* `KC_HTTP_METRICS_SLOS`
--

Available only when metrics are enabled


|

|
[.options-key]#``metrics-enabled``# [.none]#icon:tools[role=options-build]#

[.options-description]#If the server should expose metrics.#

[role="options-extended"]
--
[.options-description-extended]#If enabled, metrics are available at the `/metrics` endpoint.#

*CLI:* `--metrics-enabled` +
*Env:* `KC_METRICS_ENABLED`
--



|
`+true+`, `+false+` (default)


|===
