Merge pull request #47335 from bburt-rh/RHDEVDOCS-3920-document-accessing-federation-endpoints-for-metrics

RHDEVDOCS-3920 - document querying the federate endpoint for Prometheus metrics

Author: abrennan89

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

@@ -0,0 +1,71 @@
+// Module included in the following assemblies:
+//
+// * monitoring/accessing-third-party-monitoring-apis.adoc
+
+:_content-type: PROCEDURE
+[id="monitoring-querying-metrics-by-using-the-federation-endpoint-for-prometheus_{context}"]
+= Querying metrics by using the federation endpoint for Prometheus
+
+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]
+====
+A delay in retrieving metrics data occurs when you use federation. 
+This delay can affect the accuracy and timeliness of the scraped metrics.
+
+Using the federation endpoint can also degrade the performance and scalability of your cluster, especially if you use the federation endpoint to retrieve large amounts of metrics data.
+To avoid these issues, follow these recommendations:
+
+* Do not try to retrieve all metrics data via the federation endpoint.
+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. 
+
+* Avoid querying the federation endpoint frequently. 
+Limit queries to a maximum of one every 30 seconds.
+
+If you need to forward large amounts of data outside the cluster, use remote write instead. For more information, see the _Configuring remote write storage_ section.
+====
+
+.Prerequisites
+
+* You have installed the OpenShift CLI (`oc`).
+* You have obtained the host URL for the {product-title} route.
+* You have access to the cluster as a user with the `cluster-monitoring-view` role or have obtained a bearer token with `get` permission on the `namespaces` resource.
++
+[NOTE]
+====
+You can only use bearer token authentication to access the federation endpoint.
+====
+
+.Procedure
+
+. Retrieve the bearer token:
++
+[source,terminal]
+----
+$ 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" \
+    'https:/<federation_host>/federate' \ <1>
+    --data-urlencode 'match[]=up'
+----
++
+<1> For <federation_host>, substitute the host URL for the federation route.
++
+.Example output
++
+[source,terminal]
+----
+# TYPE up untyped
+up{apiserver="kube-apiserver",endpoint="https",instance="10.0.143.148:6443",job="apiserver",namespace="default",service="kubernetes",prometheus="openshift-monitoring/k8s",prometheus_replica="prometheus-k8s-0"} 1 1657035322214
+up{apiserver="kube-apiserver",endpoint="https",instance="10.0.148.166:6443",job="apiserver",namespace="default",service="kubernetes",prometheus="openshift-monitoring/k8s",prometheus_replica="prometheus-k8s-0"} 1 1657035338597
+up{apiserver="kube-apiserver",endpoint="https",instance="10.0.173.16:6443",job="apiserver",namespace="default",service="kubernetes",prometheus="openshift-monitoring/k8s",prometheus_replica="prometheus-k8s-0"} 1 1657035343834
+...
+----

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

@@ -2,7 +2,7 @@
 [id="accessing-third-party-monitoring-apis"]
 = Accessing third-party monitoring APIs
 include::_attributes/common-attributes.adoc[]
-:context: accessing-third-party-monitoring-uis-and-apis
+:context: accessing-third-party-monitoring-apis
 
 toc::[]
 
@@ -12,10 +12,13 @@ In {product-title} {product-version}, you can access web service APIs for some t
 // Accessing service APIs for third-party monitoring components
 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]
+
 [role="_additional-resources"]
-[id="additional-resources_accessing-third-party-monitoring-uis-and-apis"]
+[id="additional-resources_accessing-third-party-monitoring-apis"]
 == Additional resources
 
+* xref:../monitoring/configuring-the-monitoring-stack.adoc#configuring_remote_write_storage_configuring-the-monitoring-stack[Configuring remote write storage]
 * xref:../monitoring/managing-metrics.adoc#managing-metrics[Managing metrics]
 * xref:../monitoring/managing-alerts.adoc#managing-alerts[Managing alerts]
-* xref:../monitoring/reviewing-monitoring-dashboards.adoc#reviewing-monitoring-dashboards[Reviewing monitoring dashboards]