From b3b30a8620dcce0b0d5caee429d07789afbad147 Mon Sep 17 00:00:00 2001 From: Alexander Schwartz Date: Fri, 4 Apr 2025 11:14:00 +0200 Subject: [PATCH] Rework observability page titles and summaries Closes #38583 Signed-off-by: Alexander Schwartz --- docs/guides/observability/configuration-metrics.adoc | 4 ++-- docs/guides/observability/event-metrics.adoc | 5 ++--- docs/guides/observability/grafana-dashboards.adoc | 5 ++--- docs/guides/observability/health.adoc | 4 ++-- .../observability/keycloak-service-level-indicators.adoc | 4 ++-- ...etrics-for-troubleshooting-clustering-and-network.adoc | 4 ++-- .../metrics-for-troubleshooting-database.adoc | 2 +- ...cs-for-troubleshooting-embedded-caches-multi-site.adoc | 2 +- .../observability/metrics-for-troubleshooting-http.adoc | 2 +- .../observability/metrics-for-troubleshooting-jvm.adoc | 2 +- .../metrics-for-troubleshooting-keycloak.adoc | 2 +- .../guides/observability/metrics-for-troubleshooting.adoc | 4 ++-- docs/guides/observability/pinned-guides | 8 ++++++++ docs/guides/observability/tracing.adoc | 6 +++--- 14 files changed, 30 insertions(+), 24 deletions(-) diff --git a/docs/guides/observability/configuration-metrics.adoc b/docs/guides/observability/configuration-metrics.adoc index c37dbdd2737..2699d9acd4e 100644 --- a/docs/guides/observability/configuration-metrics.adoc +++ b/docs/guides/observability/configuration-metrics.adoc @@ -4,8 +4,8 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Enabling {project_name} Metrics" -summary="Learn how to enable and expose metrics from the server" +title="Gaining insights with metrics" +summary="Collect metrics to gain insights about state and activities of a running instance of {project_name}." includedOptions="metrics-enabled http-metrics-* cache-metrics-*"> {project_name} has built in support for metrics. This {section} describes how to enable and configure server metrics. diff --git a/docs/guides/observability/event-metrics.adoc b/docs/guides/observability/event-metrics.adoc index d510dde0428..073449e71b0 100644 --- a/docs/guides/observability/event-metrics.adoc +++ b/docs/guides/observability/event-metrics.adoc @@ -4,11 +4,10 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Enabling {project_name} Event Metrics" -summary="Learn how to enable and use {project_name} Event Metrics" +title="Monitoring user activities with event metrics" +summary="Event metrics provide admins an aggregated view of the different user activities in a {project_name} instance." includedOptions="metrics-enabled event-metrics-user-*"> -Event metrics can provide admins an overview of the different activities in a {project_name} instance. For now, only metrics for user events are captured. For example, you can monitor the number of logins, login failures, or token refreshes performed. diff --git a/docs/guides/observability/grafana-dashboards.adoc b/docs/guides/observability/grafana-dashboards.adoc index 102273ca487..03a90ed6460 100644 --- a/docs/guides/observability/grafana-dashboards.adoc +++ b/docs/guides/observability/grafana-dashboards.adoc @@ -2,13 +2,12 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="{project_name} Grafana dashboards" -summary="Learn how to import {project_name} provided Grafana dashboards to your Grafana instance" > +title="Visualizing activities in a dashboard" +summary="Install the {project_name} Grafana dashboards to vitualize the metrics that capture the status and activities of your deployment."> {project_name} provides metrics to observe what is happening inside the deployment. To understand how metrics evolve over time, it is helpful to collect them and visualize in graphs. - This guide provides instructions on how to visualize collected {project_name} metrics in a running Grafana instance. == Prerequisites diff --git a/docs/guides/observability/health.adoc b/docs/guides/observability/health.adoc index b53b5436ce0..87dbeb4e6c8 100644 --- a/docs/guides/observability/health.adoc +++ b/docs/guides/observability/health.adoc @@ -4,8 +4,8 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Enabling {project_name} Health checks" -summary="Learn how to enable and use {project_name} health checks" +title="Tracking instance status with health checks" +summary="Check if an instance has finished its start up and is ready to serve requests by calling its health REST endpoints." includedOptions="health-enabled"> {project_name} has built in support for health checks. This {section} describes how to enable and use the {project_name} health checks. diff --git a/docs/guides/observability/keycloak-service-level-indicators.adoc b/docs/guides/observability/keycloak-service-level-indicators.adoc index 82331bdf61e..296d09fa172 100644 --- a/docs/guides/observability/keycloak-service-level-indicators.adoc +++ b/docs/guides/observability/keycloak-service-level-indicators.adoc @@ -2,8 +2,8 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="{project_name} service level indicators (SLIs)" -summary="Learn about the Service Level Indicators to monitor your {project_name} deployment's performance" +title="Monitoring performance with Service Level Indicators" +summary="Track performance and reliability as perceived by users with Service Level Indicators (SLIs) and Service Level Objectives (SLOs)." > Service Level Indicators (SLIs) and Service Level Objectives (SLOs) are essential components in monitoring and maintaining the performance and reliability of {project_name} in production environments. diff --git a/docs/guides/observability/metrics-for-troubleshooting-clustering-and-network.adoc b/docs/guides/observability/metrics-for-troubleshooting-clustering-and-network.adoc index 516d005c3cf..192311dc372 100644 --- a/docs/guides/observability/metrics-for-troubleshooting-clustering-and-network.adoc +++ b/docs/guides/observability/metrics-for-troubleshooting-clustering-and-network.adoc @@ -2,8 +2,8 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Clustering and network metrics" -summary="Learn about metrics monitoring communication between {project_name} nodes" +title="Clustering metrics" +summary="Learn about metrics monitoring communication between {project_name} nodes." tileVisible="false" > diff --git a/docs/guides/observability/metrics-for-troubleshooting-database.adoc b/docs/guides/observability/metrics-for-troubleshooting-database.adoc index 265a6222dfc..09938807dc7 100644 --- a/docs/guides/observability/metrics-for-troubleshooting-database.adoc +++ b/docs/guides/observability/metrics-for-troubleshooting-database.adoc @@ -2,7 +2,7 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="{project_name} Database Metrics" +title="Database Metrics" summary="Learn about metrics describing {project_name}'s connection to the database" tileVisible="false" > diff --git a/docs/guides/observability/metrics-for-troubleshooting-embedded-caches-multi-site.adoc b/docs/guides/observability/metrics-for-troubleshooting-embedded-caches-multi-site.adoc index fb2ea08be14..e92bfaf0ebd 100644 --- a/docs/guides/observability/metrics-for-troubleshooting-embedded-caches-multi-site.adoc +++ b/docs/guides/observability/metrics-for-troubleshooting-embedded-caches-multi-site.adoc @@ -2,7 +2,7 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Embedded Infinispan metrics for multiple sites deployments" +title="Embedded Infinispan metrics for multi-site deployments" summary="Learn about metrics monitoring caching health" tileVisible="false" > diff --git a/docs/guides/observability/metrics-for-troubleshooting-http.adoc b/docs/guides/observability/metrics-for-troubleshooting-http.adoc index a858f531c13..4c85260184c 100644 --- a/docs/guides/observability/metrics-for-troubleshooting-http.adoc +++ b/docs/guides/observability/metrics-for-troubleshooting-http.adoc @@ -2,7 +2,7 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="{project_name} HTTP metrics" +title="HTTP metrics" summary="Learn about metrics for monitoring the {project_name} HTTP requests processing" tileVisible="false" > diff --git a/docs/guides/observability/metrics-for-troubleshooting-jvm.adoc b/docs/guides/observability/metrics-for-troubleshooting-jvm.adoc index 17081022ee6..6546c04720d 100644 --- a/docs/guides/observability/metrics-for-troubleshooting-jvm.adoc +++ b/docs/guides/observability/metrics-for-troubleshooting-jvm.adoc @@ -2,7 +2,7 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="{project_name} JVM metrics" +title="JVM metrics" summary="Learn about key JVM metrics for observing performance of {project_name}" tileVisible="false" > diff --git a/docs/guides/observability/metrics-for-troubleshooting-keycloak.adoc b/docs/guides/observability/metrics-for-troubleshooting-keycloak.adoc index f34439960d2..963676726ef 100644 --- a/docs/guides/observability/metrics-for-troubleshooting-keycloak.adoc +++ b/docs/guides/observability/metrics-for-troubleshooting-keycloak.adoc @@ -2,7 +2,7 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="{project_name} self-provided metrics" +title="Self-provided metrics" summary="Learn about key metrics that {project_name} provides" tileVisible="false" > diff --git a/docs/guides/observability/metrics-for-troubleshooting.adoc b/docs/guides/observability/metrics-for-troubleshooting.adoc index 352d8c0d68b..1fceadfb980 100644 --- a/docs/guides/observability/metrics-for-troubleshooting.adoc +++ b/docs/guides/observability/metrics-for-troubleshooting.adoc @@ -2,8 +2,8 @@ <#import "/templates/links.adoc" as links> <@tmpl.guide -title="Metrics for troubleshooting {project_name} deployment" -summary="Learn about metrics that can indicate where the issue is, for example, when service level objective is not met" +title="Troubleshooting using metrics" +summary="Learn which metrics exist and how to use them for troubleshooting errors and performance issues." > For a running {project_name} deployment it is important to understand how the system performs and whether it meets your service level objectives (SLOs). diff --git a/docs/guides/observability/pinned-guides b/docs/guides/observability/pinned-guides index b1bd59384e2..9a48de8820e 100644 --- a/docs/guides/observability/pinned-guides +++ b/docs/guides/observability/pinned-guides @@ -3,5 +3,13 @@ configuration-metrics event-metrics keycloak-service-level-indicators metrics-for-troubleshooting +metrics-for-troubleshooting-keycloak +metrics-for-troubleshooting-jvm +metrics-for-troubleshooting-database +metrics-for-troubleshooting-http +metrics-for-troubleshooting-clustering-and-network +metrics-for-troubleshooting-embedded-caches +metrics-for-troubleshooting-embedded-caches-multi-site +metrics-for-troubleshooting-external-infinispan-multi-site tracing grafana-dashboards diff --git a/docs/guides/observability/tracing.adoc b/docs/guides/observability/tracing.adoc index ba9817ad555..d93fea863f5 100644 --- a/docs/guides/observability/tracing.adoc +++ b/docs/guides/observability/tracing.adoc @@ -4,14 +4,14 @@ <#import "/templates/links.adoc" as links> <#import "/templates/profile.adoc" as profile> -<@tmpl.guide title="Enabling Tracing" -summary="Learn how to enable distributed tracing in {project_name}" +<@tmpl.guide title="Root cause analysis with tracing" +summary="Record information during the request lifecycle with OpenTelementry tracing to identify root cases for latencies and errors in {project_name} and connected systems." includedOptions="tracing-* log-*-include-trace"> This {section} explains how you can enable and configure distributed tracing in {project_name} by utilizing https://opentelemetry.io/[OpenTelemetry] (OTel). Tracing allows for detailed monitoring of each request's lifecycle, which helps quickly identify and diagnose issues, leading to more efficient debugging and maintenance. -It also provides valuable insights into performance bottlenecks and can help optimize the system's overall efficiency. +It provides valuable insights into performance bottlenecks and can help optimize the system's overall efficiency and across system boundaries. {project_name} uses a supported https://quarkus.io/guides/opentelemetry-tracing[Quarkus OTel extension] that provides smooth integration and exposure of application traces. == Enable tracing