From 7440afe571316af029a264011d3793aaab36e145 Mon Sep 17 00:00:00 2001 From: Brian Clozel Date: Thu, 2 Feb 2023 15:41:48 +0100 Subject: [PATCH] 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 gh-29904 --- .../src/docs/asciidoc/integration/observability.adoc | 6 ++++++ .../src/docs/asciidoc/integration/rest-clients.adoc | 3 +++ framework-docs/src/docs/asciidoc/web/webflux-webclient.adoc | 2 ++ 3 files changed, 11 insertions(+) diff --git a/framework-docs/src/docs/asciidoc/integration/observability.adoc b/framework-docs/src/docs/asciidoc/integration/observability.adoc index ff7faa2eaf2..0fa1af57674 100644 --- 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 index b85fe2ae473..8a47198d4b1 100644 --- 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 <> 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 index 267a690d628..34337a18a15 100644 --- 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 <>. +* `observationConvention`: <> for recorded observations. For example: