Reformatting the JVM metrics, adding database metrics

Signed-off-by: Alexander Schwartz <aschwart@redhat.com>

doc/kubernetes/modules/ROOT/nav.adoc

@@ -19,6 +19,7 @@ include::partial$subnav-openshift.adoc[]
 ** Metrics
 *** xref:running/metrics/keycloak_service_level_indicators.adoc[]
 *** xref:running/metrics/jvm_metrics.adoc[]
+*** xref:running/metrics/database_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/index.adoc

@@ -28,6 +28,7 @@ These guides will eventually be published Keycloak's main web page.
 
 * xref:running/metrics/keycloak_service_level_indicators.adoc[]
 * xref:running/metrics/jvm_metrics.adoc[]
+* xref:running/metrics/database_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/database_metrics.adoc

@@ -0,0 +1,35 @@
+= {project_name} Database Metrics
+:description: This documentation covers the information about Keycloak's connection to the database {project_name}.
+
+{description}
+
+include::partial$/running/metrics/kc_enable_metrics.adoc[leveloffset=+1]
+
+== Database connection pool
+
+Configure {project_name} to use a fixed size database connection pool.
+See https://www.keycloak.org/high-availability/concepts-database-connections[Concepts for database connection pools] for more information.
+
+[TIP]
+====
+If there is a high count of threads waiting for a database connection, increasing the database connection pool size is not always the best option. It might overload the database which would then become the bottleneck. Consider the following options instead:
+
+* Reduce the number of HTTP worker threads using the option `http-pool-max-threads` to make it match the available database connections, and thereby reduce contention and resource usage in {project_name} and increase throughput.
+* Check which database statements are executed on the database. If you see, for example, a lot of information about clients and groups being fetched, and the `users` and `realms` cache are full, this might indicate that it is time to increase the sizes of those caches and see if this reduces your database load.
+====
+
+|===
+|Metric |Description
+
+m| agroal_available_count
+| Idle database connections.
+
+m| agroal_active_count
+| Database connections used in ongoing transactions.
+
+m| agroal_awaiting_count
+| Threads waiting for a database connection to become available.
+
+|===
+
+Additional information on the {project_name} `metrics` endpoint can be found https://www.keycloak.org/server/configuration-metrics[here].

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

@@ -7,19 +7,45 @@ 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.
+|===
+|Metric |Description
+
+| jvm_info_total
+| Information about the JVM such as version, runtime and vendor.
+
+|===
 
 == Heap Memory Usage
-jvm_memory_committed_bytes:: This measures the amount of memory that the JVM has committed for use, reflecting the portion of the allocated memory that is guaranteed to be available for the JVM to use.
-jvm_memory_used_bytes:: This measures the amount of memory currently used by the JVM, indicating the actual memory consumption by the application and JVM internals.
+
+|===
+|Metric |Description
+
+m| jvm_memory_committed_bytes
+| The amount of memory that the JVM has committed for use, reflecting the portion of the allocated memory that is guaranteed to be available for the JVM to use.
+
+m| jvm_memory_used_bytes
+| The amount of memory currently used by the JVM, indicating the actual memory consumption by the application and JVM internals.
+
+|===
 
 == Garbage Collection Metrics
-jvm_gc_pause_seconds_max:: It represents the maximum duration, in seconds, of garbage collection pauses experienced by the JVM due to a particular cause, which helps you quickly differentiate between types of GC (minor, major) pauses.
 
-jvm_gc_pause_seconds_sum:: It represents the total cumulative time spent in garbage collection pauses, indicating the impact of GC pauses on application performance in the JVM.
+|===
+|Metric |Description
+
+m| jvm_gc_pause_seconds_max
+
+| The maximum duration, in seconds, of garbage collection pauses experienced by the JVM due to a particular cause, which helps you quickly differentiate between types of GC (minor, major) pauses.
+
+m| jvm_gc_pause_seconds_sum
+| The total cumulative time spent in garbage collection pauses, indicating the impact of GC pauses on application performance in the JVM.
+
+m| jvm_gc_pause_seconds_count
+| Counts the total number of garbage collection pause events, helping to assess the frequency of GC pauses in the JVM.
 
-jvm_gc_pause_seconds_count:: This metric counts the total number of garbage collection pause events, helping to assess the frequency of GC pauses in the JVM.
+m| jvm_gc_overhead_percent
+| The percentage of CPU time spent on garbage collection, indicating the impact of GC on application performance in the JVM. It refers to the proportion of the total CPU processing time that is dedicated to executing garbage collection (GC) operations, as opposed to running application code or performing other tasks. This metric helps determine how much overhead GC introduces, affecting the overall performance of the {project_name}'s JVM.
 
-jvm_gc_overhead_percent:: The percentage of CPU time spent on garbage collection, indicating the impact of GC on application performance in the JVM. It refers to the proportion of the total CPU processing time that is dedicated to executing garbage collection (GC) operations, as opposed to running application code or performing other tasks. This metric helps determine how much overhead GC introduces, affecting the overall performance of the {project_name}'s JVM.
+|===
 
 Additional information on the {project_name} `metrics` endpoint can be found https://www.keycloak.org/server/configuration-metrics[here].