Merge pull request #72877 from bburt-rh/OBSDOCS-900-expand-revise-monitoring-API-access-section

OBSDOCS-900: expand and revise monitoring API access section

Author: bburt-rh

modules/accessing-metrics-outside-cluster.adoc

@@ -6,7 +6,7 @@
 [id="accessing-metrics-from-outside-cluster_{context}"]
 = Accessing metrics from outside the cluster for custom applications
 
-Learn how to query Prometheus statistics from the command line when monitoring your own services. You can access monitoring data from outside the cluster with the `thanos-querier` route.
+You can query Prometheus metrics from outside the cluster when monitoring your own services with user-defined projects. Access this data from outside the cluster by using the `thanos-querier` route.
 
 This access only supports using a Bearer Token for authentication.
 

modules/monitoring-about-accessing-monitoring-web-service-apis.adoc

@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//
+// * monitoring/accessing-third-party-monitoring-uis-and-apis.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="about-accessing-monitoring-web-service-apis_{context}"]
+= About accessing monitoring web service APIs
+
+You can directly access web service API endpoints from the command line for the following monitoring stack components:
+
+* Prometheus
+* Alertmanager
+* Thanos Ruler
+* Thanos Querier
+
+[NOTE]
+====
+To access Thanos Ruler and Thanos Querier service APIs, the requesting account must have `get` permission on the namespaces resource, which can be granted by binding the `cluster-monitoring-view` cluster role to the account.
+====
+
+Accessing web service APIs only supports using a Bearer Token for authentication.

modules/monitoring-accessing-third-party-monitoring-web-service-apis.adoc

@@ -3,37 +3,41 @@
 // * monitoring/accessing-third-party-monitoring-uis-and-apis.adoc
 
 :_mod-docs-content-type: PROCEDURE
-[id="accessing-third-party-monitoring-web-service-apis_{context}"]
-= Accessing third-party monitoring web service APIs
+[id="accessing-a-monitoring-web-service-api_{context}"]
+= Accessing a monitoring web service API
 
-[role="_abstract"]
-You can directly access third-party web service APIs from the command line for the following monitoring stack components: Prometheus, Alertmanager, Thanos Ruler, and Thanos Querier.
+The following example shows how to query the service API receivers for the Alertmanager service used in core platform monitoring.
+You can use a similar method to access the `prometheus-k8s` service for core platform Prometheus and the `thanos-ruler` service for Thanos Ruler.
 
-The following example commands show how to query the service API receivers for Alertmanager.
-This example requires that the associated user account be bound against the `monitoring-alertmanager-edit` role in the `openshift-monitoring` namespace and that the account has the privilege to view the route.
-This access only supports using a Bearer Token for authentication.
+.Prerequisites
 
-[source,terminal]
-----
-$ oc login -u <username> -p <password>
-----
+* You are logged in to an account that is bound against the `monitoring-alertmanager-edit` role in the `openshift-monitoring` namespace.
+* You are logged in to an account that has permission to get the Alertmanager API route.
++
+[NOTE]
+====
+If your account does not have permission to get the Alertmanager API route, a cluster administrator can provide the URL for the route.
+====
+
+.Procedure
 
+. Extract an authentication token by running the following command:
++
 [source,terminal]
 ----
-$ host=$(oc -n openshift-monitoring get route alertmanager-main -ojsonpath={.spec.host})
+$ TOKEN=$(oc whoami -t)
 ----
 
+. Extract the `alertmanager-main` API route URL by running the following command:
++
 [source,terminal]
 ----
-$ token=$(oc whoami -t)
+$ HOST=$(oc -n openshift-monitoring get route alertmanager-main -ojsonpath={.spec.host})
 ----
 
+. Query the service API receivers for Alertmanager by running the following command:
++
 [source,terminal]
 ----
-$ curl -H "Authorization: Bearer $token" -k "https://$host/api/v2/receivers"
+$ curl -H "Authorization: Bearer $TOKEN" -k "https://$HOST/api/v2/receivers"
 ----
-
-[NOTE]
-====
-To access Thanos Ruler and Thanos Querier service APIs, the requesting account must have `get` permission on the namespaces resource, which can be done by granting the `cluster-monitoring-view` cluster role to the account.
-====

modules/monitoring-querying-metrics-by-using-the-federation-endpoint-for-prometheus.adoc

@@ -9,7 +9,7 @@
 You can use the federation endpoint to scrape platform and user-defined metrics from a network location outside the cluster.
 To do so, access the Prometheus `/federate` endpoint for the cluster via an {product-title} route.
 
-[WARNING]
+[IMPORTANT]
 ====
 A delay in retrieving metrics data occurs when you use federation.
 This delay can affect the accuracy and timeliness of the scraped metrics.
@@ -44,15 +44,15 @@ You can only use bearer token authentication to access the federation endpoint.
 +
 [source,terminal]
 ----
-$ token=`oc whoami -t`
+$ TOKEN=`oc whoami -t`
 ----
 
 . Query metrics from the `/federate` route.
 The following example queries `up` metrics:
 +
 [source,terminal]
 ----
-$ curl -G -s -k -H "Authorization: Bearer $token" \
+$ curl -G -s -k -H "Authorization: Bearer $TOKEN" \
     'https://<federation_host>/federate' \ <1>
     --data-urlencode 'match[]=up'
 ----

monitoring/accessing-third-party-monitoring-apis.adoc

@@ -9,12 +9,33 @@ toc::[]
 [role="_abstract"]
 In {product-title} {product-version}, you can access web service APIs for some third-party monitoring components from the command line interface (CLI).
 
+[IMPORTANT]
+====
+In certain situations, accessing API endpoints can degrade the performance and scalability of your cluster, especially if you use endpoints to retrieve, send, or query large amounts of metrics data.
+
+To avoid these issues, follow these recommendations:
+
+* Avoid querying endpoints frequently. Limit queries to a maximum of one every 30 seconds.
+* Do not try to retrieve all metrics data via the `/federate` endpoint for Prometheus. Query it only when you want to retrieve a limited, aggregated data set. For example, retrieving fewer than 1,000 samples for each request helps minimize the risk of performance degradation.
+====
+
 // Accessing service APIs for third-party monitoring components
+include::modules/monitoring-about-accessing-monitoring-web-service-apis.adoc[leveloffset=+1]
 include::modules/monitoring-accessing-third-party-monitoring-web-service-apis.adoc[leveloffset=+1]
 
 // Querying metrics by using the federation endpoint for Prometheus
 include::modules/monitoring-querying-metrics-by-using-the-federation-endpoint-for-prometheus.adoc[leveloffset=+1]
 
+// Accessing metrics from outside the cluster for custom applications 
+include::modules/accessing-metrics-outside-cluster.adoc[leveloffset=+1]
+
+ifndef::openshift-dedicated,openshift-rosa[]
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../monitoring/enabling-monitoring-for-user-defined-projects.adoc#enabling-monitoring-for-user-defined-projects_enabling-monitoring-for-user-defined-projects[Enabling monitoring for user-defined projects]
+endif::openshift-dedicated,openshift-rosa[]
+
 [role="_additional-resources"]
 [id="additional-resources_accessing-third-party-monitoring-apis"]
 == Additional resources