Observability：统一可观测性

Mon, 01 Jan 0001 00:00:00 +0000

概览

本模块为 Macula Boot 提供统一可观测性能力，基于 Spring Boot Actuator、Micrometer Observation、 Micrometer Tracing 和 OpenTelemetry 实现 Metrics、Traces、Logs 三类信号的采集与 OTLP 导出。

主要功能包括：

Metrics：通过 Micrometer OTLP Registry 推送应用指标，并自动增加 application 公共标签
Traces：使用 OpenTelemetry 和 W3C Trace Context 完成服务端、客户端及网关链路传播
Logs：自动挂载 OpenTelemetry Logback Appender，导出带 traceId、spanId 的日志
Structured Logging：支持 Spring Boot 原生 logstash、ecs、gelf 及自定义结构化日志格式
Context Propagation：配合 macula-boot-starter-async 传播 Trace、MDC、Tenant 和 GrayVersion 上下文
安全控制：默认不采集任意 MDC、请求头、Token、Cookie、请求体或响应体

本模块统一替代 Macula Boot 6.1 之前的 Prometheus、Logstash、Sleuth 和 SkyWalking Starter。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-observability</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

基础配置

引入组件后，根据需要开启三类 OTLP 导出。以下配置默认把数据发送到本机 OpenTelemetry Collector：

Auditing

Mon, 01 Jan 0001 00:00:00 +0000

概览

本模块通过 @AuditLog 采集审计事件，由应用监听 OperLogEvent 完成持久化。日志导出可结合 macula-boot-starter-observability，本模块不提供日志存储后端。

操作日志功能模块，提供基于注解的操作日志记录功能。

组件坐标

<!-- 日志审计 -->
<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-auditlog</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

无独立 YAML 配置项；记录范围由下文 @AuditLog 参数控制。默认保存请求和响应数据，敏感字段应通过 excludeParamNames 排除，或关闭对应记录。异步监听示例需启用 @EnableAsync 或引入 Async Starter。

AuditLog

添加macula-boot-starter-auditlog依赖后，在需要审计的方法上加上@AuditLog注解，添加注解后调用方法会触发OperLogEvent事件，可以定义Listener监听事件用于持久化审计日志。

 @Operation(summary = "新增菜单")
 @AuditLog(title = "新增菜单")
 @PostMapping
 @CacheEvict(cacheNames = "system", key = "'routes'")
 public boolean addMenu(@RequestBody SysMenu menu) {
 boolean result = menuService.saveMenu(menu);
 return result;
 }

@AuditLog注解定义如下：

@Target({ElementType.PARAMETER, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface AuditLog {
 /**
 * 模块
 */
 String title() default "";

 /**
 * 功能
 */
 BusinessType businessType() default BusinessType.OTHER;

 /**
 * 操作人类别
 */
 OperatorType operatorType() default OperatorType.MANAGE;

 /**
 * 是否保存请求的参数
 */
 boolean isSaveRequestData() default true;

 /**
 * 是否保存响应的参数
 */
 boolean isSaveResponseData() default true;

 /**
 * 排除指定的请求参数
 */
 String[] excludeParamNames() default {};

}

Listenter定义参考：

生产准备 on Macula

Observability：统一可观测性

概览

组件坐标

使用配置

基础配置

Auditing

概览

组件坐标

使用配置

AuditLog