Describe metrics for Infinispan (#985)

Closes #984

Signed-off-by: Pedro Ruivo <[email protected]>
Signed-off-by: Alexander Schwartz <[email protected]>
Co-authored-by: Alexander Schwartz <[email protected]>

antora/antora-playbook-author.yml

@@ -57,3 +57,4 @@ asciidoc:
     github-files: https://github.com/keycloak/keycloak-benchmark/blob/main
     project_name: Keycloak
     ispn: Infinispan
+    jdgserver_name: Infinispan

antora/antora-playbook.yml

@@ -57,3 +57,4 @@ asciidoc:
     github-files: https://github.com/keycloak/keycloak-benchmark/blob/main
     project_name: Keycloak
     ispn: Infinispan
+    jdgserver_name: Infinispan

doc/kubernetes/modules/ROOT/nav.adoc

@@ -15,8 +15,12 @@ include::partial$subnav-openshift.adoc[]
 * xref:running/index.adoc[]
 ** xref:running/infinispan-deployment.adoc[]
 ** xref:running/timeout_tunning.adoc[]
-** xref:running/jvm/jvm_metrics.adoc[]
 ** xref:running/jvm/jvm_options.adoc[]
+** Metrics
+*** xref:running/metrics/jvm_metrics.adoc[]
+*** xref:running/metrics/keycloak_cluster.adoc[]
+*** xref:running/metrics/keycloak_with_external_infinispan.adoc[]
+*** xref:running/metrics/external_infinispan.adoc[]
 * xref:customizing-deployment.adoc[]
 * xref:storage-configurations.adoc[]
 ** xref:storage/postgres.adoc[]

doc/kubernetes/modules/ROOT/pages/running/index.adoc

@@ -17,11 +17,16 @@ These guides will eventually be published Keycloak's main web page.
 
 * xref:running/infinispan-deployment.adoc[]
 * xref:running/timeout_tunning.adoc[]
-* xref:running/jvm/jvm_metrics.adoc[]
-* xref:running/jvm/jvm_options.adoc[]
 
 [#jvm-tuning]
 == JVM tuning guides
 
-* xref:running/jvm/jvm_metrics.adoc[]
 * xref:running/jvm/jvm_options.adoc[]
+
+[#monitoring-deployments]
+== Monitoring deployments
+
+* xref:running/metrics/jvm_metrics.adoc[]
+* xref:running/metrics/keycloak_cluster.adoc[]
+* xref:running/metrics/keycloak_with_external_infinispan.adoc[]
+* xref:running/metrics/external_infinispan.adoc[]

doc/kubernetes/modules/ROOT/pages/running/metrics/external_infinispan.adoc

@@ -0,0 +1,21 @@
+= External {jdgserver_name} deployment
+:description: This document contains details of the external {jdgserver_name} metrics that can be used to monitor your deployment's performance
+:jgrp_application: {jdgserver_name}
+:clustered_caches: true
+:cross_site: true
+
+{description}
+
+include::partial$/running/metrics/ispn_enable_metrics.adoc[leveloffset=+1]
+
+== Clustering and Network
+
+This section describes metrics that are useful for monitoring the communication between {jdgserver_name} nodes to identify possible network issues.
+
+include::partial$/running/metrics/jgrp_metrics.adoc[leveloffset=+1]
+
+== {jdgserver_name} Caches
+
+The metrics in this section help monitoring the {jdgserver_name} caches health and the cluster replication.
+
+include::partial$/running/metrics/ispn_metrics.adoc[leveloffset=+1]

doc/kubernetes/modules/ROOT/pages/running/jvm/jvm_metrics.adoc → doc/kubernetes/modules/ROOT/pages/running/metrics/jvm_metrics.adoc

@@ -3,6 +3,8 @@
 
 {description}
 
+include::partial$/running/metrics/kc_enable_metrics.adoc[leveloffset=+1]
+
 == JVM info
 
 jvm_info_total:: This provides important information about the JVM such as version, runtime and vendor.

doc/kubernetes/modules/ROOT/pages/running/metrics/keycloak_cluster.adoc

@@ -0,0 +1,27 @@
+= {project_name} cluster deployment
+:description: This document contains details of the metrics to monitor your {project_name} deployment's performance.
+:jgrp_application: {project_name}
+:clustered_caches: true
+
+{description}
+
+The deployment described in this document is for single-site deployments.
+In this architecture, {project_name} nodes leverage {ispn} embedded clustered caches to form a cluster.
+
+If an external {jdgserver_name} is used, check xref:./keycloak_with_external_infinispan.adoc[] guide.
+
+include::partial$/running/metrics/kc_enable_metrics.adoc[leveloffset=+1]
+include::partial$/running/metrics/kc_http_metrics.adoc[leveloffset=+1]
+
+== Clustering and Network
+
+Deploying multiple {project_name} nodes allows the load to be distributed amongst them, but this requires communication between the nodes.
+This section describes metrics that are useful for monitoring the communication between {project_name} in order to identify possible faults.
+
+include::partial$/running/metrics/jgrp_metrics.adoc[leveloffset=+1]
+
+== {ispn} Caches
+
+{project_name} caches data in embedded {ispn} caches. The metrics in this section help to monitor the caching health and the cluster replication.
+
+include::partial$/running/metrics/ispn_metrics.adoc[leveloffset=+1]

doc/kubernetes/modules/ROOT/pages/running/metrics/keycloak_with_external_infinispan.adoc

@@ -0,0 +1,28 @@
+= {project_name} with external {jdgserver_name} deployment
+:description: This document contains details of the {project_name} metrics that can be used to monitor your deployment's performance.
+
+{description}
+
+The deployment described in this document is for multi-site deployments.
+In this architecture, {project_name} nodes use an external {jdgserver_name} to store the cached data.
+
+If your deployment does not use an external {jdgserver_name}, check xref:./keycloak_cluster.adoc[] guide.
+
+include::partial$/running/metrics/kc_enable_metrics.adoc[leveloffset=+1]
+include::partial$/running/metrics/kc_http_metrics.adoc[leveloffset=+1]
+
+== {ispn} Caches
+
+IMPORTANT: Metrics available since {project_name} 27 or newer.
+
+{project_name} caches data in embedded {ispn} caches. The metrics in this section help monitor the caching health.
+
+include::partial$/running/metrics/ispn_metrics.adoc[leveloffset=+1]
+
+== Hot Rod client metrics
+
+IMPORTANT: Metrics available since {project_name} 27 or newer.
+
+{project_name} uses the {ispn} Hot Rod client to connection to an external {jdgserver_name} deployment.
+
+include::partial$/running/metrics/kc_hot_rod_client_metrics.adoc[leveloffset=+1]

doc/kubernetes/modules/ROOT/partials/running/infinispan-attributes.adoc

@@ -22,7 +22,6 @@
 :operator-docs: https://infinispan.org/docs/infinispan-operator/main/operator.html
 :xsite-docs: https://infinispan.org/docs/stable/titles/xsite/xsite.html
 :ocp: OpenShift
-:ispn: Infinispan
 :ispn-operator: Infinispan Operator
 :kc: Keycloak
 :site-a: Site-A

doc/kubernetes/modules/ROOT/partials/running/metrics/histogram_note.adoc

@@ -0,0 +1,2 @@
+NOTE: When histogram is enabled, the percentile buckets are available.
+Those are useful to create heat maps but, collecting and exposing the percentile buckets may have a negative impact on the deployment performance.

doc/kubernetes/modules/ROOT/partials/running/metrics/ispn_enable_metrics.adoc

@@ -0,0 +1,54 @@
+= Enabled {jdgserver_name} server metrics
+
+{jdgserver_name} exposes metrics in the endpoint `/metrics`.
+By default, they are enabled.
+We recommend enabling the attribute `name-as-tags` as it makes the metrics name independent on the cache name.
+
+To configure metrics in the {jdgserver_name} server, just enabled as shown in the XML below.
+
+.infinispan.xml
+[source,xml]
+----
+<infinispan>
+    <cache-container statistics="true">
+        <metrics gauges="true" histograms="false" name-as-tags="true" />
+    </cache-container>
+</infinispan>
+----
+
+Using the {jdgserver_name} Operator in Kubernetes, metrics can be enabled by using a `ConfigMap` with a custom configuration.
+It is shown below an example.
+
+.ConfigMap
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cluster-config
+data:
+  infinispan-config.yaml: >
+    infinispan:
+      cacheContainer:
+        metrics:
+          gauges: true
+          namesAsTags: true
+          histograms: false
+----
+
+.infinispan.yaml CR
+[source,yaml]
+----
+apiVersion: infinispan.org/v1
+kind: Infinispan
+metadata:
+  name: infinispan
+  annotations:
+    infinispan.org/monitoring: 'true' # <1>
+spec:
+  configMapName: "cluster-config" #<2>
+----
+<1> Enables monitoring for the deployment
+<2> Sets the `ConfigMap` name with the custom configuration.
+
+Additional information can be found https://infinispan.org/docs/stable/titles/server/server.html#configuring-metrics_statistics-jmx[here] and https://infinispan.org/docs/infinispan-operator/main/operator.html#monitoring-services[here].