diff --git a/framework-docs/modules/ROOT/pages/integration/observability.adoc b/framework-docs/modules/ROOT/pages/integration/observability.adoc index 29dabf20d50..0620f4913df 100644 --- a/framework-docs/modules/ROOT/pages/integration/observability.adoc +++ b/framework-docs/modules/ROOT/pages/integration/observability.adoc @@ -2,8 +2,8 @@ = Observability Support Micrometer defines an https://micrometer.io/docs/observation[Observation concept that enables both Metrics and Traces] in applications. -Metrics support offers a way to create timers, gauges or counters for collecting statistics about the runtime behavior of your application. -Metrics can help you to track error rates, usage patterns, performance and more. +Metrics support offers a way to create timers, gauges, or counters for collecting statistics about the runtime behavior of your application. +Metrics can help you to track error rates, usage patterns, performance, and more. Traces provide a holistic view of an entire system, crossing application boundaries; you can zoom in on particular user requests and follow their entire completion across applications. Spring Framework instruments various parts of its own codebase to publish observations if an `ObservationRegistry` is configured. @@ -36,16 +36,16 @@ https://micrometer.io/docs/concepts#_naming_meters[to the format preferred by th [[observability.concepts]] == Micrometer Observation concepts -If you are not familiar with Micrometer Observation, here's a quick summary of the new concepts you should know about. +If you are not familiar with Micrometer Observation, here's a quick summary of the concepts you should know about. * `Observation` is the actual recording of something happening in your application. This is processed by `ObservationHandler` implementations to produce metrics or traces. * Each observation has a corresponding `ObservationContext` implementation; this type holds all the relevant information for extracting metadata for it. - In the case of an HTTP server observation, the context implementation could hold the HTTP request, the HTTP response, any Exception thrown during processing... -* Each `Observation` holds `KeyValues` metadata. In the case of a server HTTP observation, this could be the HTTP request method, the HTTP response status... + In the case of an HTTP server observation, the context implementation could hold the HTTP request, the HTTP response, any exception thrown during processing, and so forth. +* Each `Observation` holds `KeyValues` metadata. In the case of an HTTP server observation, this could be the HTTP request method, the HTTP response status, and so forth. This metadata is contributed by `ObservationConvention` implementations which should declare the type of `ObservationContext` they support. * `KeyValues` are said to be "low cardinality" if there is a low, bounded number of possible values for the `KeyValue` tuple (HTTP method is a good example). Low cardinality values are contributed to metrics only. - High cardinality values are on the other hand unbounded (for example, HTTP request URIs) and are only contributed to Traces. + Conversely, "high cardinality" values are unbounded (for example, HTTP request URIs) and are only contributed to traces. * An `ObservationDocumentation` documents all observations in a particular domain, listing the expected key names and their meaning. @@ -63,16 +63,16 @@ Each instrumented component will provide two extension points: === Using custom Observation conventions Let's take the example of the Spring MVC "http.server.requests" metrics instrumentation with the `ServerHttpObservationFilter`. -This observation is using a `ServerRequestObservationConvention` with a `ServerRequestObservationContext`; custom conventions can be configured on the Servlet filter. +This observation uses a `ServerRequestObservationConvention` with a `ServerRequestObservationContext`; custom conventions can be configured on the Servlet filter. If you would like to customize the metadata produced with the observation, you can extend the `DefaultServerRequestObservationConvention` for your requirements: include-code::./ExtendedServerRequestObservationConvention[] -If you want full control, you can then implement the entire convention contract for the observation you're interested in: +If you want full control, you can implement the entire convention contract for the observation you're interested in: include-code::./CustomServerRequestObservationConvention[] -You can also achieve similar goals using a custom `ObservationFilter` - adding or removing key values for an observation. +You can also achieve similar goals using a custom `ObservationFilter` – adding or removing key values for an observation. Filters do not replace the default convention and are used as a post-processing component. include-code::./ServerRequestObservationFilter[] @@ -83,22 +83,22 @@ You can configure `ObservationFilter` instances on the `ObservationRegistry`. [[observability.http-server]] == HTTP Server instrumentation -HTTP server exchanges observations are created with the name `"http.server.requests"` for Servlet and Reactive applications. +HTTP server exchange observations are created with the name `"http.server.requests"` for Servlet and Reactive applications. [[observability.http-server.servlet]] === Servlet applications Applications need to configure the `org.springframework.web.filter.ServerHttpObservationFilter` Servlet filter in their application. -It is using the `org.springframework.http.server.observation.DefaultServerRequestObservationConvention` by default, backed by the `ServerRequestObservationContext`. +It uses the `org.springframework.http.server.observation.DefaultServerRequestObservationConvention` by default, backed by the `ServerRequestObservationContext`. -This will only record an observation as an error if the `Exception` has not been handled by the web Framework and has bubbled up to the Servlet filter. +This will only record an observation as an error if the `Exception` has not been handled by the web framework and has bubbled up to the Servlet filter. Typically, all exceptions handled by Spring MVC's `@ExceptionHandler` and xref:web/webmvc/mvc-ann-rest-exceptions.adoc[`ProblemDetail` support] will not be recorded with the observation. You can, at any point during request processing, set the error field on the `ObservationContext` yourself: include-code::./UserController[] NOTE: Because the instrumentation is done at the Servlet Filter level, the observation scope only covers the filters ordered after this one as well as the handling of the request. -Typically, the Servlet container error handling is done at a lower level and won't have any active observation nor span. +Typically, Servlet container error handling is performed at a lower level and won't have any active observation or span. For this use case, a container-specific implementation is required, such as a `org.apache.catalina.Valve` for Tomcat; this is outside of the scope of this project. By default, the following `KeyValues` are created: @@ -126,9 +126,9 @@ By default, the following `KeyValues` are created: === Reactive applications Applications need to configure the `org.springframework.web.filter.reactive.ServerHttpObservationFilter` reactive `WebFilter` in their application. -It is using the `org.springframework.http.server.reactive.observation.DefaultServerRequestObservationConvention` by default, backed by the `ServerRequestObservationContext`. +It uses the `org.springframework.http.server.reactive.observation.DefaultServerRequestObservationConvention` by default, backed by the `ServerRequestObservationContext`. -This will only record an observation as an error if the `Exception` has not been handled by the web Framework and has bubbled up to the `WebFilter`. +This will only record an observation as an error if the `Exception` has not been handled by the web framework and has bubbled up to the `WebFilter`. Typically, all exceptions handled by Spring WebFlux's `@ExceptionHandler` and xref:web/webflux/ann-rest-exceptions.adoc[`ProblemDetail` support] will not be recorded with the observation. You can, at any point during request processing, set the error field on the `ObservationContext` yourself: @@ -157,9 +157,9 @@ By default, the following `KeyValues` are created: [[observability.http-client]] -== HTTP Client instrumentation +== HTTP Client Instrumentation -HTTP client exchanges observations are created with the name `"http.client.requests"` for blocking and reactive clients. +HTTP client exchange observations are created with the name `"http.client.requests"` for blocking and reactive clients. Unlike their server counterparts, the instrumentation is implemented directly in the client so the only required step is to configure an `ObservationRegistry` on the client. [[observability.http-client.resttemplate]] @@ -168,7 +168,7 @@ Unlike their server counterparts, the instrumentation is implemented directly in 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`. +Instrumentation uses the `org.springframework.http.client.observation.ClientRequestObservationConvention` by default, backed by the `ClientRequestObservationContext`. .Low cardinality Keys [cols="a,a"] @@ -197,7 +197,7 @@ Instrumentation is using the `org.springframework.http.client.observation.Client 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`. +Instrumentation uses the `org.springframework.web.reactive.function.client.ClientRequestObservationConvention` by default, backed by the `ClientRequestObservationContext`. .Low cardinality Keys [cols="a,a"]