Merge pull request #111630 from lcavalle/TELCODOCS-2694-dita-rewrite

slovern · web-flow · commit f141aea878bd · 2026-06-17T11:07:25.000+01:00
TELCODOCS-2694 DITA migration cleanup for observability.adoc
diff --git a/modules/observability-alerting.adoc b/modules/observability-alerting.adoc
@@ -2,30 +2,26 @@
 //
 // * edge_computing/day_2_core_cnf_clusters/observability/observability.adoc
 
-:_mod-docs-content-type: PROCEDURE
+:_mod-docs-content-type: CONCEPT
 [id="observability-alerting_{context}"]
-
 = Alerting
 
+[role="_abstract"]
 {product-title} includes a large number of alert rules, which can change from release to release. 
 
 [id="viewing-default-alerts_{context}"]
 == Viewing default alerts
 
-Review all of the alert rules in a cluster.
-
-.Procedure
+To review all of the alert rules in a cluster, run the following command:
 
-* To review all the alert rules in a cluster, run the following command:
 [source,terminal]
-+
 ----
 $ oc get cm -n openshift-monitoring prometheus-k8s-rulefiles-0 -o yaml
 ----
-+
+
 Rules can include a description and provide a link to additional information and mitigation steps. 
 For example, see the rule for `etcdHighFsyncDurations`:
-+
+
 [source,terminal]
 ----
       - alert: etcdHighFsyncDurations
diff --git a/modules/observability-key-performance-metrics.adoc b/modules/observability-key-performance-metrics.adoc
@@ -6,6 +6,7 @@
 [id="observability-key-performance-metrics_{context}"]
 = Key performance metrics
 
+[role="_abstract"]
 Depending on your system, you can have hundreds of available measurements.
 
 Consider the following key metrics:
diff --git a/modules/observability-monitoring-stack.adoc b/modules/observability-monitoring-stack.adoc
@@ -4,7 +4,10 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="observability-monitoring-stack_{context}"]
-= Understanding the monitoring stack
+= Monitoring stack components
+
+[role="_abstract"]
+The monitoring stack in {product-title} consists of several integrated components that collect, analyze, store, and alert on metrics.
 
 The monitoring stack uses the following components:
 
diff --git a/modules/observability-monitoring-the-edge.adoc b/modules/observability-monitoring-the-edge.adoc
@@ -4,10 +4,10 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="observability-monitoring-the-edge_{context}"]
-
 = Monitoring at the far edge network
 
-{product-title} clusters at the edge must keep the footprint of the platform components to a minimum. 
+[role="_abstract"]
+{product-title} clusters at the edge must keep the footprint of the platform components to a minimum.
 The following procedure is an example of how to configure a {sno} or a node at the far edge network with a small monitoring footprint.
 
 .Prerequisites
@@ -198,7 +198,7 @@ $ oc get routes,pods -n open-cluster-management-observability
 ----
 NAME                                         HOST/PORT                                                                                        PATH      SERVICES                          PORT          TERMINATION          WILDCARD
 route.route.openshift.io/alertmanager        alertmanager-open-cluster-management-observability.cloud.example.com        /api/v2   alertmanager                      oauth-proxy   reencrypt/Redirect   None
-route.route.openshift.io/grafana             grafana-open-cluster-management-observability.cloud.example.com                       grafana                           oauth-proxy   reencrypt/Redirect   None <1>
+route.route.openshift.io/grafana             grafana-open-cluster-management-observability.cloud.example.com                       grafana                           oauth-proxy   reencrypt/Redirect   None
 route.route.openshift.io/observatorium-api   observatorium-api-open-cluster-management-observability.cloud.example.com             observability-observatorium-api   public        passthrough/None     None
 route.route.openshift.io/rbac-query-proxy    rbac-query-proxy-open-cluster-management-observability.cloud.example.com              rbac-query-proxy                  https         reencrypt/Redirect   None
 
@@ -213,6 +213,10 @@ pod/observability-thanos-store-shard-1-0                       1/1     Running
 pod/observability-thanos-store-shard-2-0                       1/1     Running   0          1d
 
 ----
-<1> A dashboard is accessible at the grafana route listed. You can use this to view metrics across all managed clusters.
++
+[NOTE]
+====
+A dashboard is accessible at the grafana route listed. You can use this to view metrics across all managed clusters.
+====
 
-For more information on observability in {rh-rhacm-title}, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.12/html/observability/index[Observability].
+For more information on observability in {rh-rhacm-title}, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.12/html/observability/index[Observability].
diff --git a/modules/observability-workload-monitoring.adoc b/modules/observability-workload-monitoring.adoc
@@ -6,7 +6,8 @@
 [id="observability-workload-monitoring_{context}"]
 = Workload monitoring
 
-By default, {product-title} does not collect metrics for application workloads. You can configure a cluster to collect workload metrics.
+[role="_abstract"]
+By default, {product-title} does not collect metrics for application workloads. You can configure a cluster to collect workload metrics and create alerts for user workloads.
 
 .Prerequisites
 
@@ -25,9 +26,10 @@ metadata:
   namespace: openshift-monitoring
 data:
   config.yaml: |
-    enableUserWorkload: true <1>
+    enableUserWorkload: true
 ----
-<1> Set to `true` to enable workload monitoring.
++
+Set `enableUserWorkload` to `true` to enable workload monitoring.
 
 . Apply the `ConfigMap` CR by running the following command:
 +
@@ -48,58 +50,33 @@ metadata:
   name: myapp
   namespace: myns
 spec:
-  endpoints: <1>
+  endpoints:
   - interval: 30s
     port: ui-http
     scheme: http
-    path: /healthz <2>
+    path: /healthz
   selector:
     matchLabels:
       app: ui
 ----
-<1> Use endpoints to define workload metrics. 
-<2> Prometheus scrapes the path `/metrics` by default. You can define a custom path here. 
++
+--
+* `endpoints` specifies the workload metrics endpoints to scrape.
+* `path` specifies a custom scrape path. Prometheus scrapes the `/metrics` path by default.
+--
 
 . Apply the `ServiceMonitor` CR by running the following command:
 +
 [source,terminal]
 ----
 $ oc apply -f monitoringServiceMonitor.yaml
 ----
-
-Prometheus scrapes the `/metrics` path by default. However, you can define a custom path. 
-The vendor of the application must decide whether to expose the endpoint for scraping, with metrics that they deem relevant.
-
-== Creating a workload alert
-
-You can enable alerts for user workloads on a cluster.
-
-.Procedure
-
-. Create a `ConfigMap` CR, and save it as `monitoringConfigMap.yaml`, as in the following example:
 +
-[source,yaml]
-----
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: cluster-monitoring-config
-  namespace: openshift-monitoring
-data:
-  config.yaml: |
-    enableUserWorkload: true <1>
-# ...
-----
-<1> Set to `true` to enable workload monitoring.
+The vendor of the application must decide whether to expose the endpoint for scraping, with metrics that they deem relevant.
 
-. Apply the `ConfigMap` CR by running the following command:
-+
-[source,terminal]
-----
-$ oc apply -f monitoringConfigMap.yaml
-----
+. To enable alerts for user workloads, verify that the `cluster-monitoring-config` ConfigMap has `enableUserWorkload: true` set. If you completed step 1, this is already configured.
 
-. Create a YAML file for alerting rules, `monitoringAlertRule.yaml`, as in the following example:
+. Create a YAML file for alerting rules and save it as `monitoringAlertRule.yaml`, as in the following example:
 +
 [source,yaml]
 ----
