Add details of the purpose of the metrics endpoint #44767
Conversation
jonatan-ivanov
added
the
status: waiting-for-triage
| @@ -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. | |||
There was a problem hiding this comment.
I wanted to link "external metrics backend" to https://docs.spring.io/spring-boot/reference/actuator/metrics.html but Antora did not like xref:reference:actuator/metrics.adoc[external metrics backend], could somebody help me with the right xref?
There was a problem hiding this comment.
What failure did you get? That xref seems to work for me.
There was a problem hiding this comment.
I just pushed a change to your branch. Let's see what CI makes of it.
There was a problem hiding this comment.
It failed. :spring-boot-project:spring-boot-docs:antora which pulls in the Actuator API docs worked for me locally. It's spring-boot-project:spring-boot-actuator-autoconfigure:antora that's failing on CI though.
Any ideas, @philwebb? The reference works fine when built as part of spring-boot-docs but not when just building the Actuator API docs on their own.
There was a problem hiding this comment.
I ran ./gradlew antora and got the same error as CI:
ERROR (asciidoctor): target of xref not found: reference:actuator/metrics.adoc
Not sure if it helps but here's my build-scan (pulling down the changes you made and running the "root" antora task): https://ge.spring.io/s/g7ozmgj4eabn2
wilkinsona
force-pushed
the
metrics-endpoint-docs
branch
from
dc7a464 to
7730937
Compare
|
Can we merge this without the link and I can open a PR with adding the link back and try to figure out what's wrong with xref? |
As far as I know, the purpose of the
/metricsactuator endpoint is mainly for troubleshooting the metrics the app recorded just like the/envendpoint is for troubleshooting the config of the app. It should not be used in production like Prometheus (you scrape it and try to create dashboards from the data) but it should be able to answer questions like:This PR tries to call out this detail (the endpoint is for diagnosing the metrics).