Document how to enable HTTP client Observation instrumentation

This commit documents how Observation instrumentation should be activated for `RestTemplate` and `WebClient`: they both need an `ObservationRegistry` configured to create and record actual observations. This is being done automatically in Spring Boot if auto-configured builders (`RestTemplateBuilder`, `WebClient.Builder`) are used. Closes spring-projectsgh-29904
mdeinum · Jun 29, 2023 · 7c9fb40 · 7c9fb40
1 parent d0faad0
commit 7c9fb40
Show file tree

Hide file tree

Showing 3 changed files with 11 additions and 0 deletions.
diff --git a/framework-docs/src/docs/asciidoc/integration/observability.adoc b/framework-docs/src/docs/asciidoc/integration/observability.adoc
@@ -125,6 +125,9 @@ Unlike their server counterparts, the instrumentation is implemented directly in
 [[integration.observability.http-client.resttemplate]]
 === RestTemplate
 
+Applications must configure an `ObservationRegistry` on `RestTemplate` instances to enable the instrumentation; without that, observations are "no-ops".
+Spring Boot will auto-configure `RestTemplateBuilder` beans with the observation registry already set.
+
 Instrumentation is using the `org.springframework.http.client.observation.ClientRequestObservationConvention` by default, backed by the `ClientRequestObservationContext`.
 
 .Low cardinality Keys
@@ -151,6 +154,9 @@ Instrumentation is using the `org.springframework.http.client.observation.Client
 [[integration.observability.http-client.webclient]]
 === WebClient
 
+Applications must configure an `ObservationRegistry` on the `WebClient` builder to enable the instrumentation; without that, observations are "no-ops".
+Spring Boot will auto-configure `WebClient.Builder` beans with the observation registry already set.
+
 Instrumentation is using the `org.springframework.web.reactive.function.client.ClientRequestObservationConvention` by default, backed by the `ClientRequestObservationContext`.
 
 .Low cardinality Keys

diff --git a/framework-docs/src/docs/asciidoc/integration/rest-clients.adoc b/framework-docs/src/docs/asciidoc/integration/rest-clients.adoc
@@ -117,6 +117,9 @@ TIP: Note that the `java.net` implementation for HTTP requests can raise an exce
 accessing the status of a response that represents an error (such as 401). If this is an
 issue, switch to another HTTP client library.
 
+NOTE: `RestTemplate` can be instrumented for observability, in order to produce metrics and traces.
+See the <<integration.adoc#integration.observability.http-client.resttemplate,RestTemplate Observability support>> section.
+
 [[rest-resttemplate-uri]]
 ==== URIs
 

diff --git a/framework-docs/src/docs/asciidoc/web/webflux-webclient.adoc b/framework-docs/src/docs/asciidoc/web/webflux-webclient.adoc
@@ -38,6 +38,8 @@ You can also use `WebClient.builder()` with further options:
 * `filter`: Client filter for every request.
 * `exchangeStrategies`: HTTP message reader/writer customizations.
 * `clientConnector`: HTTP client library settings.
+* `observationRegistry`: the registry to use for enabling <<integration.adoc#integration.observability.http-client.webclient, Observability support>>.
+* `observationConvention`: <<integration.adoc#integration.observability.config,an optional, custom convention to extract metadata>> for recorded observations.
 
 For example: