[id='configuring-metrics_{context}']
= Configuring {brandname} metrics

{brandname} generates metrics that are compatible with any monitoring system.

* Gauges provide values such as the average number of nanoseconds for write operations or JVM uptime.
* Histograms provide details about operation execution times such as read,
write, and remove times.

By default, {brandname} generates gauges when you enable statistics but you can also configure it to generate histograms.

[NOTE]
====
{brandname} metrics are provided at the `vendor` scope.
Metrics related to the JVM are provided in the `base` scope.
====

ifdef::embedded_caches[]
.Prerequisites

* You must add Micrometer Core and Micrometer Registry Prometheus JARs to your classpath to export {brandname} metrics for embedded caches.
endif::embedded_caches[]

.Procedure

. Open your {brandname} configuration for editing.
. Add the `metrics` element or object to the cache container.
. Enable or disable gauges with the `gauges` attribute or field.
. Enable or disable histograms with the `histograms` attribute or field.
. Enable or disable the export of metrics in legacy format using the `legacy` attribute or field.
. Save and close your client configuration.

[discrete]
== Metrics configuration

.XML
[source,xml,options="nowrap",subs=attributes+,role="primary"]
----
include::xml/metrics_cache_container.xml[]
----

.JSON
[source,json,options="nowrap",subs=attributes+,role="secondary"]
----
include::json/metrics_cache_container.json[]
----

.YAML
[source,yaml,options="nowrap",subs=attributes+,role="secondary"]
----
include::yaml/metrics_cache_container.yaml[]
----

ifdef::embedded_caches[]
.GlobalConfigurationBuilder
[source,java,options="nowrap",subs=attributes+,role="secondary"]
----
include::code_examples/MetricsGlobalConfigurationBuilder.java[]
----
endif::embedded_caches[]

[discrete]
=== Legacy format
For backwards compatibility, metrics are currently exported in a legacy format by default. The setting `legacy` should be set to 
`false` to export metrics in the new format.

.XML
[source,xml,options="nowrap",subs=attributes+,role="primary"]
----
include::xml/metrics_cache_container_legacy.xml[]
----

.JSON
[source,json,options="nowrap",subs=attributes+,role="secondary"]
----
include::json/metrics_cache_container_legacy.json[]
----

.YAML
[source,yaml,options="nowrap",subs=attributes+,role="secondary"]
----
include::yaml/metrics_cache_container_legacy.yaml[]
----

ifdef::remote_caches[]
.Verification

{brandname} Server exposes statistics through the `metrics` endpoint that you can collect with monitoring tools such as Prometheus.
To verify that statistics are exported to the `metrics` endpoint, you can do the following:

.Prometheus format
[source,options="nowrap",subs=attributes+,role="primary"]
----
curl -v http://localhost:11222/metrics \
--digest -u username:password
----

.OpenMetrics format
[source,options="nowrap",subs=attributes+,role="secondary"]
----
curl -v http://localhost:11222/metrics \
--digest -u username:password \
-H "Accept: application/openmetrics-text"
----

[NOTE]
====
{brandname} no longer provides metrics in MicroProfile JSON format.
====
endif::remote_caches[]

[role="_additional-resources"]
.Additional resources
* link:{metrics_docs}[{brandname} Metrics]
* link:https://micrometer.io/docs/registry/prometheus[Micrometer Prometheus]
