Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Polish

Browse Source 
Closes gh-29619
This commit is contained in:
Johnny Lim
2022-12-02 00:14:36 +09:00
committed by Brian Clozel
parent dd6cb1b728
commit 74ec10bf3a
7 changed files with 26 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
framework-docs/src/docs/asciidoc/integration/observability.adoc
View File

@@ -17,11 +17,11 @@ If you are not familiar with Micrometer Observation, here's a quick summary of t
* `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 an server HTTP observation, this could be the HTTP request method, the HTTP response status...
* Each `Observation` holds `KeyValues` metadata. In the case of a server HTTP observation, this could be the HTTP request method, the HTTP response status...
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 methods is a good example).
* `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" are on the other hand unbounded (for example, HTTP request URIs) and are only contributed to Traces.
High cardinality values are on the other hand 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.
@@ -48,7 +48,7 @@ If you want full control, you can then implement the entire convention contract
include::code:CustomServerRequestObservationConvention[]
You can also 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[]
@@ -74,7 +74,7 @@ By default, the following `KeyValues` are created:
|===
|Name | Description
|`exception` _(required)_|Name of the exception thrown during the exchange, or `KeyValue#NONE_VALUE`} if no exception happened.
|`method` _(required)_|Name of HTTP request method or `KeyValue#NONE_VALUE` if the request was not received properly.
|`method` _(required)_|Name of HTTP request method or `"none"` if the request was not received properly.
|`outcome` _(required)_|Outcome of the HTTP server exchange.
|`status` _(required)_|HTTP response raw status code, or `"UNKNOWN"` if no response was created.
|`uri` _(required)_|URI pattern for the matching handler if available, falling back to `REDIRECTION` for 3xx responses, `NOT_FOUND` for 404 responses, `root` for requests with no path info, and `UNKNOWN` for all other requests.
@@ -100,8 +100,8 @@ By default, the following `KeyValues` are created:
[cols="a,a"]
|===
|Name | Description
|`exception` _(required)_|Name of the exception thrown during the exchange, or `KeyValue#NONE_VALUE` if no exception happened.
|`method` _(required)_|Name of HTTP request method or `KeyValue#NONE_VALUE` if the request was not received properly.
|`exception` _(required)_|Name of the exception thrown during the exchange, or `"none"` if no exception happened.
|`method` _(required)_|Name of HTTP request method or `"none"` if the request was not received properly.
|`outcome` _(required)_|Outcome of the HTTP server exchange.
|`status` _(required)_|HTTP response raw status code, or `"UNKNOWN"` if no response was created.
|`uri` _(required)_|URI pattern for the matching handler if available, falling back to `REDIRECTION` for 3xx responses, `NOT_FOUND` for 404 responses, `root` for requests with no path info, and `UNKNOWN` for all other requests.
@@ -122,7 +122,7 @@ By default, the following `KeyValues` are created:
HTTP client exchanges 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.
[[integration.observability.http-server.resttemplate]]
[[integration.observability.http-client.resttemplate]]
=== RestTemplate
Instrumentation is using the `org.springframework.http.client.observation.ClientRequestObservationConvention` by default, backed by the `ClientRequestObservationContext`.
@@ -131,11 +131,11 @@ Instrumentation is using the `org.springframework.http.client.observation.Client
[cols="a,a"]
|===
|Name | Description
|`exception` _(required)_|Name of the exception thrown during the exchange, or `KeyValue#NONE_VALUE` if no exception happened.
|`method` _(required)_|Name of HTTP request method or `KeyValue#NONE_VALUE` if the request could not be created.
|`exception` _(required)_|Name of the exception thrown during the exchange, or `"none"` if no exception happened.
|`method` _(required)_|Name of HTTP request method or `"none"` if the request could not be created.
|`outcome` _(required)_|Outcome of the HTTP client exchange.
|`status` _(required)_|HTTP response raw status code, or `"IO_ERROR"` in case of `IOException`, or `"CLIENT_ERROR"` if no response was received.
|`uri` _(required)_|URI template used for HTTP request, or `KeyValue#NONE_VALUE` if none was provided.
|`uri` _(required)_|URI template used for HTTP request, or `"none"` if none was provided.
|===
.High cardinality Keys
@@ -148,7 +148,7 @@ Instrumentation is using the `org.springframework.http.client.observation.Client
[[integration.observability.http-server.webclient]]
[[integration.observability.http-client.webclient]]
=== WebClient
Instrumentation is using the `org.springframework.web.reactive.function.client.ClientRequestObservationConvention` by default, backed by the `ClientRequestObservationContext`.
@@ -157,11 +157,11 @@ Instrumentation is using the `org.springframework.web.reactive.function.client.C
[cols="a,a"]
|===
|Name | Description
|`exception` _(required)_|Name of the exception thrown during the exchange, or `KeyValue#NONE_VALUE` if no exception happened.
|`method` _(required)_|Name of HTTP request method or `KeyValue#NONE_VALUE` if the request could not be created.
|`exception` _(required)_|Name of the exception thrown during the exchange, or `"none"` if no exception happened.
|`method` _(required)_|Name of HTTP request method or `"none"` if the request could not be created.
|`outcome` _(required)_|Outcome of the HTTP client exchange.
|`status` _(required)_|HTTP response raw status code, or `"IO_ERROR"` in case of `IOException`, or `"CLIENT_ERROR"` if no response was received.
|`uri` _(required)_|URI template used for HTTP request, or `KeyValue#NONE_VALUE` if none was provided.
|`uri` _(required)_|URI template used for HTTP request, or `"none"` if none was provided.
|===
.High cardinality Keys

2
framework-docs/src/docs/asciidoc/integration/scheduling.adoc
View File

@@ -724,7 +724,7 @@ The specified range is inclusive.
* Following a range (or `*`) with `/` specifies the interval of the number's value through the range.
* English names can also be used for the month and day-of-week fields.
Use the first three letters of the particular day or month (case does not matter).
* The day-of-month and day-of-week fields can contain a `L` character, which has a different meaning
* The day-of-month and day-of-week fields can contain an `L` character, which has a different meaning.
** In the day-of-month field, `L` stands for _the last day of the month_.
If followed by a negative offset (that is, `L-n`), it means _``n``th-to-last day of the month_.
** In the day-of-week field, `L` stands for _the last day of the week_.

11
framework-docs/src/main/java/org/springframework/docs/integration/observability/config/conventions/CustomServerRequestObservationConvention.java
View File

@@ -48,22 +48,21 @@ public class CustomServerRequestObservationConvention implements ServerRequestOb
return KeyValues.of(httpUrl(context));
}
protected KeyValue method(ServerRequestObservationContext context) {
private KeyValue method(ServerRequestObservationContext context) {
// You should reuse as much as possible the corresponding ObservationDocumentation for key names
return KeyValue.of(ServerHttpObservationDocumentation.LowCardinalityKeyNames.METHOD, context.getCarrier().getMethod());
}
// @fold:on // status(), exception(), httpUrl()...
private KeyValue status(ServerRequestObservationContext context) {
return KeyValue.of(ServerHttpObservationDocumentation.LowCardinalityKeyNames.STATUS, String.valueOf(context.getResponse().getStatus()));
}
private KeyValue exception(ServerRequestObservationContext context) {
String exception = (context.getError() != null) ? context.getError().getClass().getSimpleName() : KeyValue.NONE_VALUE;
return KeyValue.of(ServerHttpObservationDocumentation.LowCardinalityKeyNames.EXCEPTION, exception);
}
private KeyValue status(ServerRequestObservationContext context) {
return KeyValue.of(ServerHttpObservationDocumentation.LowCardinalityKeyNames.STATUS, String.valueOf(context.getResponse().getStatus()));
}
private KeyValue httpUrl(ServerRequestObservationContext context) {
return KeyValue.of(ServerHttpObservationDocumentation.HighCardinalityKeyNames.HTTP_URL, context.getCarrier().getRequestURI());
}

2
framework-docs/src/main/java/org/springframework/docs/integration/observability/config/conventions/ExtendedServerRequestObservationConvention.java
View File

@@ -30,7 +30,7 @@ public class ExtendedServerRequestObservationConvention extends DefaultServerReq
return super.getLowCardinalityKeyValues(context).and(custom(context));
}
protected KeyValue custom(ServerRequestObservationContext context) {
private KeyValue custom(ServerRequestObservationContext context) {
return KeyValue.of("custom.method", context.getCarrier().getMethod());
}