From 09fd202abd69fcd042738de865beaa6068570429 Mon Sep 17 00:00:00 2001
From: Jonatan Ivanov <jonatan.ivanov@gmail.com>
Date: Tue, 18 Mar 2025 17:37:23 -0700
Subject: [PATCH 1/2] Add details of the purpose of the metrics endpoint

See gh-44767
---
 .../docs/antora/modules/api/pages/rest/actuator/metrics.adoc    | 2 +-
 .../docs/antora/modules/reference/pages/actuator/endpoints.adoc | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/antora/modules/api/pages/rest/actuator/metrics.adoc b/spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/antora/modules/api/pages/rest/actuator/metrics.adoc
index fe153d63efd2..b7c53c3bba72 100644
--- a/spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/antora/modules/api/pages/rest/actuator/metrics.adoc
+++ b/spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/antora/modules/api/pages/rest/actuator/metrics.adoc
@@ -1,7 +1,7 @@
 [[metrics]]
 = Metrics (`metrics`)
 
-The `metrics` endpoint provides access to application metrics.
+The `metrics` endpoint provides access to application metrics to diagnose the metrics the application has recorded. This endpoint should not be "scraped" or used as a metrics backend in production. It's purpose is to show the currently registered metrics so users can see what metrics are available, what their current values are, and if triggering certain operations cause any change in certain values. If you want to diagnose your applications through the metrics they collect, you should use an external metrics backend. In this case, the `metrics` endpoint can still be useful.
 
 
 
diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/endpoints.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/endpoints.adoc
index 24b35b99ac74..3ec551d1a9fc 100644
--- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/endpoints.adoc
+++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/endpoints.adoc
@@ -66,7 +66,7 @@ Subject to xref:actuator/endpoints.adoc#actuator.endpoints.sanitization[sanitiza
   Requires one or more javadoc:{url-liquibase-javadoc}/liquibase.Liquibase[] beans.
 
 | `metrics`
-| Shows "`metrics`" information for the current application.
+| Shows "`metrics`" information for the current application to diagnose the metrics the application has recorded.
 
 | `mappings`
 | Displays a collated list of all javadoc:org.springframework.web.bind.annotation.RequestMapping[format=annotation] paths.

From 7730937596eb425522de73a0799534063de166ea Mon Sep 17 00:00:00 2001
From: Andy Wilkinson <andy.wilkinson@broadcom.com>
Date: Wed, 19 Mar 2025 19:44:52 +0000
Subject: [PATCH 2/2] Polish "Add details of the purpose of the metrics
 endpoint"

See gh-44767
---
 .../antora/modules/api/pages/rest/actuator/metrics.adoc     | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/antora/modules/api/pages/rest/actuator/metrics.adoc b/spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/antora/modules/api/pages/rest/actuator/metrics.adoc
index b7c53c3bba72..9c5fcc89221c 100644
--- a/spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/antora/modules/api/pages/rest/actuator/metrics.adoc
+++ b/spring-boot-project/spring-boot-actuator-autoconfigure/src/docs/antora/modules/api/pages/rest/actuator/metrics.adoc
@@ -1,7 +1,11 @@
 [[metrics]]
 = Metrics (`metrics`)
 
-The `metrics` endpoint provides access to application metrics to diagnose the metrics the application has recorded. This endpoint should not be "scraped" or used as a metrics backend in production. It's purpose is to show the currently registered metrics so users can see what metrics are available, what their current values are, and if triggering certain operations cause any change in certain values. If you want to diagnose your applications through the metrics they collect, you should use an external metrics backend. In this case, the `metrics` endpoint can still be useful.
+The `metrics` endpoint provides access to application metrics to diagnose the metrics the application has recorded.
+This endpoint should not be "scraped" or used as a metrics backend in production.
+Its purpose is to show the currently registered metrics so users can see what metrics are available, what their current values are, and if triggering certain operations cause any change in certain values.
+If you want to diagnose your applications through the metrics they collect, you should use an xref:reference:actuator/metrics.adoc[external metrics backend].
+In this case, the `metrics` endpoint can still be useful.