diff --git a/modules/monitoring-querying-metrics-by-using-the-federation-endpoint-for-prometheus.adoc b/modules/monitoring-querying-metrics-by-using-the-federation-endpoint-for-prometheus.adoc new file mode 100644 index 000000000000..9aaf27668057 --- /dev/null +++ b/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://federate' \ <1> + --data-urlencode 'match[]=up' +---- ++ +<1> For , 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 +... +---- diff --git a/monitoring/accessing-third-party-monitoring-apis.adoc b/monitoring/accessing-third-party-monitoring-apis.adoc index fdfb9de97651..3fba15991f8f 100644 --- a/monitoring/accessing-third-party-monitoring-apis.adoc +++ b/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]