|
此版本仍在开发中，尚不被认为是稳定的。对于最新的稳定版本，请使用 Spring Framework 6.2.10！ |
可观测性支持
Micrometer 定义了一个观察概念，可在应用程序中同时启用度量和跟踪。 指标支持提供了一种创建计时器、仪表或计数器的方法，用于收集有关应用程序运行时行为的统计信息。 指标可以帮助您跟踪错误率、使用模式、性能等。 跟踪提供了整个系统的整体视图，跨越了应用程序边界;您可以放大特定的用户请求，并跨应用程序跟踪它们的整个完成情况。
Spring Framework 会检测其自己的代码库的各个部分来发布观察结果，如果ObservationRegistry已配置。
您可以了解有关在 Spring Boot 中配置可观测性基础设施的更多信息。
已生成的观察结果列表
Spring Framework 检测了各种功能以实现可观察性。 如本节开头所述，观察可以根据配置生成计时器指标和/或跟踪。
| 观测名称 | 描述 |
|---|---|
HTTP 客户端交换所花费的时间 |
|
框架级别的 HTTP 服务器交换的处理时间 |
|
消息生产者将 JMS 消息发送到目标所花费的时间。 |
|
消息使用者先前接收的 JMS 消息的处理时间。 |
|
执行 |
| 观测使用 Micrometer 的官方命名约定，但 Metrics 名称将自动转换为监控系统后端首选的格式（Prometheus、Atlas、Graphite、InfluxDB 等）。 |
千分尺观察概念
如果您不熟悉千分尺观察，这里简要总结了您应该了解的概念。
-
Observation是应用程序中发生的事情的实际记录。这是由ObservationHandler实现以生成指标或跟踪。 -
每个观测值都有一个对应的
ObservationContext实现;此类型包含用于提取元数据的所有相关信息。 在 HTTP 服务器观察的情况下，上下文实现可以保存 HTTP 请求、HTTP 响应、处理期间抛出的任何异常等。 -
每
Observation持有KeyValues元数据。对于 HTTP 服务器观察，这可能是 HTTP 请求方法、HTTP 响应状态等。 此元数据由ObservationConvention应声明类型ObservationContext他们支持。 -
KeyValues如果可能的值数量较低，则称为“低基数”KeyValue元组（HTTP 方法就是一个很好的例子）。 低基数值仅对指标有贡献。 相反，“高基数”值是无界的（例如，HTTP 请求 URI），并且仅贡献给跟踪。 -
一
ObservationDocumentation记录特定域中的所有观察结果，列出预期的键名称及其含义。
配置观测
全局配置选项可在ObservationRegistry#observationConfig()水平。
每个检测组件将提供两个扩展点：
-
将
ObservationRegistry;如果未设置，则不会记录观察结果，并且将无作 -
提供自定义
ObservationConvention更改默认观测名称和提取KeyValues
使用自定义观察约定
让我们以 Spring MVC“http.server.requests”指标检测为例，其中包含ServerHttpObservationFilter.
此观察使用ServerRequestObservationConvention使用ServerRequestObservationContext;可以在 Servlet 过滤器上配置自定义约定。
如果要自定义使用观察生成的元数据，可以扩展DefaultServerRequestObservationConvention根据您的要求：
import io.micrometer.common.KeyValue;
import io.micrometer.common.KeyValues;
import org.springframework.http.server.observation.DefaultServerRequestObservationConvention;
import org.springframework.http.server.observation.ServerRequestObservationContext;
public class ExtendedServerRequestObservationConvention extends DefaultServerRequestObservationConvention {
@Override
public KeyValues getLowCardinalityKeyValues(ServerRequestObservationContext context) {
// here, we just want to have an additional KeyValue to the observation, keeping the default values
return super.getLowCardinalityKeyValues(context).and(custom(context));
}
private KeyValue custom(ServerRequestObservationContext context) {
return KeyValue.of("custom.method", context.getCarrier().getMethod());
}
}如果需要完全控制，可以为感兴趣的观察实现整个约定协定：
import java.util.Locale;
import io.micrometer.common.KeyValue;
import io.micrometer.common.KeyValues;
import org.springframework.http.server.observation.ServerHttpObservationDocumentation;
import org.springframework.http.server.observation.ServerRequestObservationContext;
import org.springframework.http.server.observation.ServerRequestObservationConvention;
public class CustomServerRequestObservationConvention implements ServerRequestObservationConvention {
@Override
public String getName() {
// will be used as the metric name
return "http.server.requests";
}
@Override
public String getContextualName(ServerRequestObservationContext context) {
// will be used for the trace name
return "http " + context.getCarrier().getMethod().toLowerCase(Locale.ROOT);
}
@Override
public KeyValues getLowCardinalityKeyValues(ServerRequestObservationContext context) {
return KeyValues.of(method(context), status(context), exception(context));
}
@Override
public KeyValues getHighCardinalityKeyValues(ServerRequestObservationContext context) {
return KeyValues.of(httpUrl(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());
}
// 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 httpUrl(ServerRequestObservationContext context) {
return KeyValue.of(ServerHttpObservationDocumentation.HighCardinalityKeyNames.HTTP_URL, context.getCarrier().getRequestURI());
}
}您还可以使用自定义ObservationFilter– 添加或删除观测值的关键值。
过滤器不会取代默认约定，而是用作后处理组件。
import io.micrometer.common.KeyValue;
import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationFilter;
import org.springframework.http.server.observation.ServerRequestObservationContext;
public class ServerRequestObservationFilter implements ObservationFilter {
@Override
public Observation.Context map(Observation.Context context) {
if (context instanceof ServerRequestObservationContext serverContext) {
context.setName("custom.observation.name");
context.addLowCardinalityKeyValue(KeyValue.of("project", "spring"));
String customAttribute = (String) serverContext.getCarrier().getAttribute("customAttribute");
context.addLowCardinalityKeyValue(KeyValue.of("custom.attribute", customAttribute));
}
return context;
}
}您可以配置ObservationFilter实例ObservationRegistry.
@Scheduled任务检测
为以下对象创建每次执行@Scheduled任务.
应用程序需要配置ObservationRegistry在ScheduledTaskRegistrar启用观察记录。
这可以通过声明SchedulingConfigurer设置观察注册表的 bean：
import io.micrometer.observation.ObservationRegistry;
import org.springframework.scheduling.annotation.SchedulingConfigurer;
import org.springframework.scheduling.config.ScheduledTaskRegistrar;
public class ObservationSchedulingConfigurer implements SchedulingConfigurer {
private final ObservationRegistry observationRegistry;
public ObservationSchedulingConfigurer(ObservationRegistry observationRegistry) {
this.observationRegistry = observationRegistry;
}
@Override
public void configureTasks(ScheduledTaskRegistrar taskRegistrar) {
taskRegistrar.setObservationRegistry(this.observationRegistry);
}
}它使用org.springframework.scheduling.support.DefaultScheduledTaskObservationConvention默认情况下，由ScheduledTaskObservationContext.
您可以在ObservationRegistry径直。
在执行调度方法期间，当前观察将在ThreadLocalcontext 或 Reactor 上下文（如果调度方法返回Mono或Flux类型）。
默认情况下，以下内容KeyValues被创建：
名称 |
描述 |
|
Java 的名称 |
|
保存调度方法的 bean 实例的类的规范名称，或 |
|
执行期间抛出的异常的类名，或 |
|
复制 |
|
方法执行的结果。可以 |
JMS 消息传递检测
Spring Framework 使用 Micrometer 提供的 Jakarta JMS 工具，如果io.micrometer:micrometer-jakarta9依赖于类路径。
这io.micrometer.jakarta9.instrument.jms.JmsInstrumentation仪器jakarta.jms.Session并记录相关观察结果。
该仪器将创建 2 种类型的观测值：
-
"jms.message.publish"当 JMS 消息发送到代理时，通常使用JmsTemplate. -
"jms.message.process"当应用程序处理 JMS 消息时，通常使用MessageListener或@JmsListener注释方法。
目前没有用于"jms.message.receive"观察值，因为测量等待收到消息所花费的时间几乎没有价值。
这种整合通常会MessageConsumer#receive方法调用。但是，一旦这些返回，处理时间就不会被测量，跟踪作用域也无法传播到应用程序。 |
默认情况下，两个观测值共享同一组可能的KeyValues:
名称 |
描述 |
|
消息传递作期间引发的异常的类名（或“无”）。 |
|
复制 |
|
目标是否为 |
|
正在执行的 JMS作的名称（值： |
名称 |
描述 |
|
JMS 消息的相关标识。 |
|
当前消息发送到的目标的名称。 |
|
消息传递系统用作消息标识符的值。 |
JMS 消息发布检测
"jms.message.publish"当将 JMS 消息发送到代理时，将记录观察结果。
它们测量发送消息所花费的时间，并使用传出的 JMS 消息头传播跟踪信息。
您需要配置ObservationRegistry在JmsTemplate要启用观察，请执行以下作：
import io.micrometer.observation.ObservationRegistry;
import jakarta.jms.ConnectionFactory;
import org.springframework.jms.core.JmsMessagingTemplate;
import org.springframework.jms.core.JmsTemplate;
public class JmsTemplatePublish {
private final JmsTemplate jmsTemplate;
private final JmsMessagingTemplate jmsMessagingTemplate;
public JmsTemplatePublish(ObservationRegistry observationRegistry, ConnectionFactory connectionFactory) {
this.jmsTemplate = new JmsTemplate(connectionFactory);
// configure the observation registry
this.jmsTemplate.setObservationRegistry(observationRegistry);
// For JmsMessagingTemplate, instantiate it with a JMS template that has a configured registry
this.jmsMessagingTemplate = new JmsMessagingTemplate(this.jmsTemplate);
}
public void sendMessages() {
this.jmsTemplate.convertAndSend("spring.observation.test", "test message");
}
}它使用io.micrometer.jakarta9.instrument.jms.DefaultJmsPublishObservationConvention默认情况下，由io.micrometer.jakarta9.instrument.jms.JmsPublishObservationContext.
类似的观察结果记录在@JmsListener从侦听器方法返回响应消息时，带注释的方法。
JMS 消息处理检测
"jms.message.process"当应用程序处理 JMS 消息时，将记录观察结果。
它们测量处理消息所花费的时间，并使用传入的 JMS 消息头传播跟踪上下文。
大多数应用程序将使用@JmsListener带注释的方法处理传入消息的机制。
您需要确保ObservationRegistry在专用JmsListenerContainerFactory:
import io.micrometer.observation.ObservationRegistry;
import jakarta.jms.ConnectionFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jms.annotation.EnableJms;
import org.springframework.jms.config.DefaultJmsListenerContainerFactory;
@Configuration
@EnableJms
public class JmsConfiguration {
@Bean
public DefaultJmsListenerContainerFactory jmsListenerContainerFactory(ConnectionFactory connectionFactory, ObservationRegistry observationRegistry) {
DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory();
factory.setConnectionFactory(connectionFactory);
factory.setObservationRegistry(observationRegistry);
return factory;
}
}需要默认的容器工厂才能启用注解支持
但请注意：@JmsListener注释可以引用用于特定目的的特定容器工厂 Bean。
在所有情况下，仅当在容器工厂上配置了观察注册表时，才会记录观察。
类似的观察结果记录在JmsTemplate当消息由MessageListener.
此类侦听器设置为MessageConsumer在会话回调中（请参阅JmsTemplate.execute(SessionCallback<T>)).
此观察使用io.micrometer.jakarta9.instrument.jms.DefaultJmsProcessObservationConvention默认情况下，由io.micrometer.jakarta9.instrument.jms.JmsProcessObservationContext.
HTTP Server 检测
HTTP 服务器交换观察使用"http.server.requests"用于 Servlet 和 Reactive 应用程序。
Servlet 应用程序
应用程序需要配置org.springframework.web.filter.ServerHttpObservationFilterServlet 过滤器。它使用org.springframework.http.server.observation.DefaultServerRequestObservationConvention默认情况下，由ServerRequestObservationContext.
只有在以下情况下，这才会将观测值记录为错误Exception尚未被 Web 框架处理，并且已冒泡到 Servlet 过滤器。通常，Spring MVC 的@ExceptionHandler和ProblemDetail支持将不会与观察结果一起记录。在请求处理期间，您可以随时在ObservationContext你自己：
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.filter.ServerHttpObservationFilter;
@Controller
public class UserController {
@ExceptionHandler(MissingUserException.class)
ResponseEntity<Void> handleMissingUser(HttpServletRequest request, MissingUserException exception) {
// We want to record this exception with the observation
ServerHttpObservationFilter.findObservationContext(request)
.ifPresent(context -> context.setError(exception));
return ResponseEntity.notFound().build();
}
static class MissingUserException extends RuntimeException {
}
}由于检测是在 Servlet 过滤器级别完成的，因此观察范围仅涵盖在此过滤器之后排序的过滤器以及请求的处理。通常，Servlet 容器错误处理在较低级别执行，并且不会有任何活动观察或跨度。对于此用例，需要特定于容器的实现，例如org.apache.catalina.Valve对于 Tomcat;这超出了本项目的范围。 |
默认情况下，以下内容KeyValues被创建：
名称 |
描述 |
|
交换期间引发的异常的类名，或 |
|
复制 |
|
HTTP 请求方法的名称或 |
|
HTTP 服务器交换的结果。 |
|
HTTP 响应原始状态代码，或 |
|
匹配处理程序的 URI 模式（如果可用），回退到 |
名称 |
描述 |
|
HTTP 请求 URI。 |
响应式应用
应用程序需要配置WebHttpHandlerBuilder使用MeterRegistry以启用服务器检测。
这可以在WebHttpHandlerBuilder如下：
import io.micrometer.observation.ObservationRegistry;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.server.reactive.HttpHandler;
import org.springframework.web.server.adapter.WebHttpHandlerBuilder;
@Configuration(proxyBeanMethods = false)
public class HttpHandlerConfiguration {
private final ApplicationContext applicationContext;
public HttpHandlerConfiguration(ApplicationContext applicationContext) {
this.applicationContext = applicationContext;
}
@Bean
public HttpHandler httpHandler(ObservationRegistry registry) {
return WebHttpHandlerBuilder.applicationContext(this.applicationContext)
.observationRegistry(registry)
.build();
}
}它使用org.springframework.http.server.reactive.observation.DefaultServerRequestObservationConvention默认情况下，由ServerRequestObservationContext.
只有在以下情况下，这才会将观测值记录为错误Exception尚未由应用程序控制器处理。
通常，所有异常都由 Spring WebFlux 的@ExceptionHandler和ProblemDetail支持将不会与观察结果一起记录。在请求处理期间，您可以随时在ObservationContext你自己：
import org.springframework.http.ResponseEntity;
import org.springframework.http.server.reactive.observation.ServerRequestObservationContext;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.server.ServerWebExchange;
@Controller
public class UserController {
@ExceptionHandler(MissingUserException.class)
ResponseEntity<Void> handleMissingUser(ServerWebExchange exchange, MissingUserException exception) {
// We want to record this exception with the observation
ServerRequestObservationContext.findCurrent(exchange.getAttributes())
.ifPresent(context -> context.setError(exception));
return ResponseEntity.notFound().build();
}
static class MissingUserException extends RuntimeException {
}
}默认情况下，以下内容KeyValues被创建：
名称 |
描述 |
|
交换期间引发的异常的类名，或 |
|
复制 |
|
HTTP 请求方法的名称或 |
|
HTTP 服务器交换的结果。 |
|
HTTP 响应原始状态代码，或 |
|
匹配处理程序的 URI 模式（如果可用），回退到 |
名称 |
描述 |
|
HTTP 请求 URI。 |
HTTP 客户端检测
HTTP 客户端交换观察使用"http.client.requests"用于阻止和响应式客户端。
此观察值测量整个 HTTP 请求/响应交换，从连接建立到正文反序列化。
与服务器对应项不同，检测直接在客户端中实现，因此唯一需要的步骤是配置ObservationRegistry在客户端上。
Rest模板
应用程序必须配置ObservationRegistry上RestTemplate实例以启用检测;没有它，观测就是“无作”。
Spring Boot 将自动配置RestTemplateBuilder已设置观察注册表的 bean。
检测使用org.springframework.http.client.observation.ClientRequestObservationConvention默认情况下，由ClientRequestObservationContext.
名称 |
描述 |
|
HTTP 请求方法的名称或 |
|
用于 HTTP 请求的 URI 模板，或 |
|
从请求 URI 主机派生的客户端名称。 |
|
HTTP 响应原始状态代码，或 |
|
HTTP 客户端交换的结果。 |
|
交换期间引发的异常的类名，或 |
|
复制 |
名称 |
描述 |
|
HTTP 请求 URI。 |
Rest客户端
应用程序必须配置ObservationRegistry在RestClient.Builder启用仪器;没有它，观测就是“无作”。
检测使用org.springframework.http.client.observation.ClientRequestObservationConvention默认情况下，由ClientRequestObservationContext.
名称 |
描述 |
|
HTTP 请求方法的名称或 |
|
用于 HTTP 请求的 URI 模板，或 |
|
从请求 URI 主机派生的客户端名称。 |
|
HTTP 响应原始状态代码，或 |
|
HTTP 客户端交换的结果。 |
|
交换期间引发的异常的类名，或 |
|
复制 |
名称 |
描述 |
|
HTTP 请求 URI。 |
网络客户端
应用程序必须配置ObservationRegistry在WebClient.Builder启用仪器;没有它，观测就是“无作”。
Spring Boot 将自动配置WebClient.Builder已设置观察注册表的 bean。
检测使用org.springframework.web.reactive.function.client.ClientRequestObservationConvention默认情况下，由ClientRequestObservationContext.
名称 |
描述 |
|
HTTP 请求方法的名称或 |
|
用于 HTTP 请求的 URI 模板，或 |
|
从请求 URI 主机派生的客户端名称。 |
|
HTTP 响应原始状态代码，或 |
|
HTTP 客户端交换的结果。 |
|
交换期间引发的异常的类名，或 |
|
复制 |
名称 |
描述 |
|
HTTP 请求 URI。 |
应用程序事件和@EventListener
Spring Framework 不贡献 Observations@EventListener调用, 因为它们没有此类检测的正确语义。默认情况下，事件发布和处理在同一线程上同步完成。这意味着在执行该任务期间，ThreadLocals 和日志记录上下文将与事件发布者相同。
如果应用程序全局配置自定义ApplicationEventMulticaster对于在不同线程上调度事件处理的策略，这不再正确。 都@EventListener方法将在主事件发布线程之外的不同线程上处理。在这些情况下，Micrometer Context Propagation 库可以帮助传播此类值并更好地关联事件的处理。应用程序可以配置所选的TaskExecutor使用ContextPropagatingTaskDecorator来装饰任务并传播上下文。要使其正常工作，请io.micrometer:context-propagationlibrary 必须存在于类路径上：
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.event.SimpleApplicationEventMulticaster;
import org.springframework.core.task.SimpleAsyncTaskExecutor;
import org.springframework.core.task.support.ContextPropagatingTaskDecorator;
@Configuration
public class ApplicationEventsConfiguration {
@Bean(name = "applicationEventMulticaster")
public SimpleApplicationEventMulticaster simpleApplicationEventMulticaster() {
SimpleApplicationEventMulticaster eventMulticaster = new SimpleApplicationEventMulticaster();
SimpleAsyncTaskExecutor taskExecutor = new SimpleAsyncTaskExecutor();
// decorate task execution with a decorator that supports context propagation
taskExecutor.setTaskDecorator(new ContextPropagatingTaskDecorator());
eventMulticaster.setTaskExecutor(taskExecutor);
return eventMulticaster;
}
}同样，如果该异步选择是在本地为每个@EventListenerannotated 方法，通过添加@Async到它，你可以选择一个TaskExecutor通过其限定符引用上下文来传播上下文。给定以下内容TaskExecutorbean 定义，配置了专用的任务装饰器：
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.task.SimpleAsyncTaskExecutor;
import org.springframework.core.task.TaskExecutor;
import org.springframework.core.task.support.ContextPropagatingTaskDecorator;
@Configuration
public class EventAsyncExecutionConfiguration {
@Bean(name = "propagatingContextExecutor")
public TaskExecutor propagatingContextExecutor() {
SimpleAsyncTaskExecutor taskExecutor = new SimpleAsyncTaskExecutor();
// decorate task execution with a decorator that supports context propagation
taskExecutor.setTaskDecorator(new ContextPropagatingTaskDecorator());
return taskExecutor;
}
}使用@Async相关限定符将实现类似的上下文传播结果：
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.springframework.context.event.EventListener;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Component;
@Component
public class EmailNotificationListener {
private final Log logger = LogFactory.getLog(EmailNotificationListener.class);
@EventListener(EmailReceivedEvent.class)
@Async("propagatingContextExecutor")
public void emailReceived(EmailReceivedEvent event) {
// asynchronously process the received event
// this logging statement will contain the expected MDC entries from the propagated context
logger.info("email has been received");
}
}