CQA for Observability

_topic_maps/_topic_map_osd.yml

@@ -1140,8 +1140,6 @@ Topics:
     Topics:
     - Name: Maintenance and support for monitoring
       File: maintenance-and-support-for-monitoring
-    - Name: Accessing monitoring for user-defined projects
-      File: sd-accessing-monitoring-for-user-defined-projects
     - Name: Disabling monitoring for user-defined projects
       File: sd-disabling-monitoring-for-user-defined-projects
   - Name: Configuring user workload monitoring

_topic_maps/_topic_map_rosa.yml

@@ -1465,8 +1465,6 @@ Topics:
     Topics:
     - Name: Maintenance and support for monitoring
       File: maintenance-and-support-for-monitoring
-    - Name: Accessing monitoring for user-defined projects
-      File: sd-accessing-monitoring-for-user-defined-projects
     - Name: Disabling monitoring for user-defined projects
       File: sd-disabling-monitoring-for-user-defined-projects
   - Name: Configuring user workload monitoring

modules/monitoring-excluding-a-user-defined-project-from-monitoring.adoc

@@ -5,10 +5,10 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="excluding-a-user-defined-project-from-monitoring_{context}"]
-= Excluding a user-defined project from monitoring
+= Exclude a user-defined project from monitoring
 
 [role="_abstract"]
-Individual user-defined projects can be excluded from user workload monitoring. To do so, add the `openshift.io/user-monitoring` label to the project's namespace with a value of `false`.
+You can exclude individual user-defined projects from monitoring to reduce resource consumption or when projects use custom monitoring solutions. Exclusion is controlled by applying a label to the project namespace.
 
 .Procedure
 

modules/monitoring-for-user-defined-projects.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// * observability/monitoring/getting-started/sd-disabling-monitoring-for-user-defined-projects.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="monitoring-for-user-defined-projects_{context}"]
+= Monitoring for user-defined projects
+
+[role="_abstract"]
+You can monitor your own {product-title} projects without requiring an additional monitoring solution. {product-title} enables this capability by default when you install a cluster, allowing you to track metrics and performance for your custom workloads.
+
+The `dedicated-admin` user has default permissions to configure and access monitoring for user-defined projects.
+
+Optionally, you can disable monitoring for user-defined projects during or after a cluster installation.
+
+[NOTE]
+====
+Custom Prometheus instances and the Prometheus Operator installed through Operator Lifecycle Manager (OLM) can cause issues with user-defined project monitoring if it is enabled. Custom Prometheus instances are not supported.
+====

modules/monitoring-support-considerations.adoc

@@ -7,7 +7,7 @@
 = Support considerations for monitoring
 
 [role="_abstract"]
-The {product-title} monitoring has configuration limitations. Understanding them is essential for avoiding automated configuration resets.
+You can avoid automated configuration resets by understanding and adhering to the supported configuration options for the {product-title} monitoring stack. Unsupported modifications are automatically reverted.
 
 [NOTE]
 ====

modules/monitoring-support-policy-for-monitoring-operators.adoc

@@ -7,11 +7,11 @@
 = Support policy for monitoring Operators
 
 [role="_abstract"]
-Monitoring Operators ensure that {product-title} monitoring resources function as designed and tested. If Cluster Version Operator (CVO) control of an Operator is overridden, the Operator does not respond to configuration changes, reconcile the intended state of cluster objects, or receive updates.
+You must not override Cluster Version Operator (CVO) control of monitoring Operators. Overriding CVO control prevents Operators from responding to configuration changes, reconciling cluster state, and receiving updates, placing your cluster in an unsupported state.
 
-While overriding CVO control for an Operator can be helpful during debugging, this is  unsupported and the cluster administrator assumes full control of the individual component configurations and upgrades.
+== Overriding the Cluster Version Operator
 
-*Overriding the Cluster Version Operator*
+While overriding CVO control for an Operator can be helpful during debugging, this is unsupported and the cluster administrator assumes full control of the individual component configurations and upgrades.
 
 The `spec.overrides` parameter can be added to the configuration for the CVO to allow administrators to provide a list of overrides to the behavior of the CVO for a component. Setting the `spec.overrides[].unmanaged` parameter to `true` for a component blocks cluster upgrades and alerts the administrator after a CVO override has been set:
 

modules/monitoring-support-version-matrix-for-monitoring-components.adoc

@@ -7,7 +7,7 @@
 = Support version matrix for monitoring components
 
 [role="_abstract"]
-The following matrix contains information about versions of monitoring components for {product-title} 4.12 and later releases:
+You can verify the supported versions of Prometheus, Alertmanager, and other monitoring components for each {product-title} release by consulting this version compatibility matrix for releases 4.12 and later.
 
 .{product-title} and component versions
 |===
@@ -34,5 +34,5 @@ The following matrix contains information about versions of monitoring component
 
 [NOTE]
 ====
-The openshift-state-metrics agent and Telemeter Client are OpenShift-specific components. Therefore, their versions correspond with the versions of {product-title}.
+The openshift-state-metrics agent and Telemeter Client are {product-title}-specific components. Therefore, their versions correspond with the versions of {product-title}.
 ====

modules/sd-disabling-monitoring-for-user-defined-projects.adoc

@@ -4,10 +4,10 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="sd-disabling-monitoring-for-user-defined-projects_{context}"]
-= Disabling monitoring for user-defined projects
+= Disable monitoring for user-defined projects
 
 [role="_abstract"]
-By default, monitoring for user-defined projects is enabled. If you do not want to use the built-in monitoring stack to monitor user-defined projects, you can disable it.
+You can disable the built-in monitoring for user-defined projects when you plan to use an external monitoring solution or need to reduce cluster resource consumption.
 
 .Prerequisites
 
@@ -19,6 +19,6 @@ By default, monitoring for user-defined projects is enabled. If you do not want
 
 . Click the *Settings* tab.
 
-. Click the *Enable user workload monitoring* checkbox to deselect the option, and then click *Save*.
+. Click the *Enable user workload monitoring* checkbox to clear the option, and then click *Save*.
 +
 User workload monitoring is disabled. The Prometheus, Prometheus Operator, and Thanos Ruler components are stopped in the `openshift-user-workload-monitoring` project.

modules/sd-monitoring-troubleshooting-issues.adoc

@@ -8,7 +8,7 @@
 = Determining why user-defined project metrics are unavailable
 
 [role="_abstract"]
-If metrics are not displaying when monitoring user-defined projects, follow these steps to troubleshoot the issue.
+You can determine why user-defined project metrics are unavailable by checking metric endpoints, verifying monitor configurations, and validating service-to-pod label matching.
 
 .Procedure
 
@@ -47,7 +47,7 @@ version{version="v0.1.0"} 1
 +
 An invalid output indicates that there is a problem with the corresponding application.
 
-. If you are using a `PodMonitor` CRD, verify that the `PodMonitor` CRD is configured to point to the correct pods using label matching. For more information, see the Prometheus Operator documentation.
+. If you are using a `PodMonitor` CRD, verify that the `PodMonitor` CRD is configured to point to the correct pods using label matching.
 . If you are using a `ServiceMonitor` CRD, and if the `/metrics` endpoint of the pod is showing metric data, follow these steps to verify the configuration:
 .. Verify that the service is pointed to the correct `/metrics` endpoint. The service `labels` in this output must match the services monitor `labels` and the `/metrics` endpoint defined by the service in the subsequent steps.
 +

observability/monitoring/getting-started/maintenance-and-support-for-monitoring.adoc

@@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 [role="_abstract"]
-Not all configuration options for the monitoring stack are exposed. To configure {product-title} monitoring, configure the {cmo-first} using the options described in the "Config map reference for the {cmo-full}" linked in the _Additional resources_ section. *Do not use other configurations, as they are unsupported.*
+You can configure {product-title} monitoring by using supported configuration options in the {cmo-full}. Using only supported options ensures your monitoring configuration persists across cluster upgrades and Prometheus version changes.
 
 Configuration paradigms might change across Prometheus releases, and such cases can only be handled gracefully if all configuration possibilities are controlled. If you use unsupported configurations, your changes will disappear because the {cmo-short} automatically reconciles any differences and resets any unsupported changes back to the originally defined state by default and by design.
 

observability/monitoring/getting-started/sd-disabling-monitoring-for-user-defined-projects.adoc

@@ -1,16 +1,24 @@
 :_mod-docs-content-type: ASSEMBLY
 include::_attributes/attributes-openshift-dedicated.adoc[]
 [id="sd-disabling-monitoring-for-user-defined-projects"]
-= Disabling monitoring for user-defined projects
+= Disable monitoring for user-defined projects
 :context: sd-disabling-monitoring-for-user-defined-projects
 
 toc::[]
 
 [role="_abstract"]
-As a `dedicated-admin`, you can disable monitoring for user-defined projects. You can also exclude individual projects from user workload monitoring.
+You can disable monitoring for user-defined projects to reduce resource consumption or exclude specific projects when they have custom monitoring solutions. This provides flexibility in managing cluster monitoring resources for your workloads.
+
+// Monitoring for user-defined projects
+include::modules/monitoring-for-user-defined-projects.adoc[leveloffset=+1]
 
 // Disabling monitoring for user-defined projects
 include::modules/sd-disabling-monitoring-for-user-defined-projects.adoc[leveloffset=+1]
 
 // Excluding a user-defined project from monitoring
 include::modules/monitoring-excluding-a-user-defined-project-from-monitoring.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+* xref:../../../observability/monitoring/config-map-reference-for-the-cluster-monitoring-operator.adoc#cluster-monitoring-operator-configuration-reference[Config map reference for the Cluster Monitoring Operator]

observability/monitoring/troubleshooting-monitoring-issues.adoc

@@ -6,23 +6,12 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-ifndef::openshift-dedicated,openshift-rosa[]
-Find troubleshooting steps for common issues with core platform and user-defined project monitoring.
-endif::openshift-dedicated,openshift-rosa[]
-ifdef::openshift-dedicated,openshift-rosa[]
-Find troubleshooting steps for common issues with user-defined project monitoring.
-endif::openshift-dedicated,openshift-rosa[]
+[role="_abstract"]
+You can troubleshoot common monitoring issues by using the procedures in this assembly. These procedures help you resolve problems with metrics collection, Prometheus storage, and alert configuration for both platform and user-defined project monitoring.
 
 // Investigating why user-defined project metrics are unavailable (OCP/ROSA HCP)
 ifndef::openshift-dedicated,openshift-rosa[]
 include::modules/monitoring-investigating-why-user-defined-metrics-are-unavailable.adoc[leveloffset=+1]
-
-[role="_additional-resources"]
-.Additional resources
-
-* xref:../../observability/monitoring/configuring-user-workload-monitoring/preparing-to-configure-the-monitoring-stack-uwm.adoc#enabling-monitoring-for-user-defined-projects-uwm_preparing-to-configure-the-monitoring-stack-uwm[Enabling monitoring for user-defined projects]
-* xref:../../observability/monitoring/configuring-user-workload-monitoring/configuring-metrics-uwm.adoc#specifying-how-a-service-is-monitored_configuring-metrics-uwm[Specifying how a service is monitored]
-* xref:../../observability/monitoring/accessing-metrics/accessing-metrics-as-an-administrator.adoc#getting-detailed-information-about-a-target_accessing-metrics-as-an-administrator[Getting detailed information about a metrics target]
 endif::openshift-dedicated,openshift-rosa[]
 
 // Investigating why user-defined project metrics are unavailable (OSD/ROSA Classic)
@@ -33,22 +22,26 @@ endif::openshift-dedicated,openshift-rosa[]
 // Determining why Prometheus is consuming a lot of disk space
 include::modules/monitoring-determining-why-prometheus-is-consuming-disk-space.adoc[leveloffset=+1]
 
-[role="_additional-resources"]
-.Additional resources
-
-* xref:../../observability/monitoring/accessing-metrics/accessing-monitoring-apis-by-using-the-cli.adoc#accessing-monitoring-apis-by-using-the-cli[Accessing monitoring APIs by using the CLI]
-* xref:../../observability/monitoring/configuring-user-workload-monitoring/configuring-performance-and-scalability-uwm.adoc#setting-scrape-and-evaluation-intervals-limits-for-user-defined-projects_configuring-performance-and-scalability-uwm[Setting scrape intervals, evaluation intervals, and enforced limits for user-defined projects]
-* xref:../../support/getting-support.adoc#support-submitting-a-case_getting-support[Submitting a support case]
-
 // Resolving the KubePersistentVolumeFillingUp alert firing for Prometheus
 include::modules/monitoring-resolving-the-kubepersistentvolumefillingup-alert-firing-for-prometheus.adoc[leveloffset=+1]
 
 ifndef::openshift-dedicated,openshift-rosa[]
 // Resolving the AlertmanagerReceiversNotConfigured alert firing for Prometheus
 include::modules/monitoring-resolving-the-alertmanagerreceiversnotconfigured-alert.adoc[leveloffset=+1]
+endif::openshift-dedicated,openshift-rosa[]
 
 [role="_additional-resources"]
-.Additional resources
+[id="additional-resources_{context}"]
+== Additional resources
+ifndef::openshift-dedicated,openshift-rosa[]
+* xref:../../observability/monitoring/configuring-user-workload-monitoring/preparing-to-configure-the-monitoring-stack-uwm.adoc#enabling-monitoring-for-user-defined-projects-uwm_preparing-to-configure-the-monitoring-stack-uwm[Enabling monitoring for user-defined projects]
+endif::openshift-dedicated,openshift-rosa[]
+* xref:../../observability/monitoring/configuring-user-workload-monitoring/configuring-metrics-uwm.adoc#specifying-how-a-service-is-monitored_configuring-metrics-uwm[Specifying how a service is monitored]
+* xref:../../observability/monitoring/accessing-metrics/accessing-metrics-as-an-administrator.adoc#getting-detailed-information-about-a-target_accessing-metrics-as-an-administrator[Getting detailed information about a metrics target]
+* xref:../../observability/monitoring/accessing-metrics/accessing-monitoring-apis-by-using-the-cli.adoc#accessing-monitoring-apis-by-using-the-cli[Accessing monitoring APIs by using the CLI]
+* xref:../../observability/monitoring/configuring-user-workload-monitoring/configuring-performance-and-scalability-uwm.adoc#setting-scrape-and-evaluation-intervals-limits-for-user-defined-projects_configuring-performance-and-scalability-uwm[Setting scrape intervals, evaluation intervals, and enforced limits for user-defined projects]
+* xref:../../support/getting-support.adoc#support-submitting-a-case_getting-support[Submitting a support case]
+ifndef::openshift-dedicated,openshift-rosa[]
 * xref:../../observability/monitoring/configuring-core-platform-monitoring/configuring-alerts-and-notifications.adoc#configuring-alert-notifications_configuring-alerts-and-notifications[Configuring alert notifications for default platform monitoring]
 * xref:../../observability/monitoring/configuring-user-workload-monitoring/configuring-alerts-and-notifications-uwm.adoc#configuring-alert-notifications_configuring-alerts-and-notifications-uwm[Configuring alert notifications for user workload monitoring]
 endif::openshift-dedicated,openshift-rosa[]