主题
starter-monitor
1. 职责
给链路追踪与指标打「项目级标签」:注册 Tracer、把 trace-id 写进响应头、用一个切面把关键业务方法(@BizTrace)包成 span,并给所有 Micrometer 指标加上 application 公共标签,方便在 SkyWalking / Prometheus 里按服务区分。
它只做「埋点约定」,不做数据采集与上报:真正的 SDK、采样率、exporter 由外部 agent(如 SkyWalking javaagent)决定。
它不解决:日志聚合、访问日志(starter-web 的 ApiAccessLog)、JVM 指标采集本身的开启(Actuator/Micrometer 负责)。
本节路径均省略公共前缀
framework/pmforge-spring-boot-starter-monitor/src/main/java/com/pmforge/framework/。
2. 关键类
| 类 | 作用 | 路径 |
|---|---|---|
PmforgeTracerAutoConfiguration | 注册 Tracer、BizTraceAspect、FilterRegistrationBean<TraceFilter> | tracer/config/PmforgeTracerAutoConfiguration.java |
TracerProperties | 空配置类,只承载 pmforge.tracer.enable | tracer/config/TracerProperties.java |
BizTrace | 注解:operationName()、id()、type(),后两个支持 SpEL | tracer/core/annotation/BizTrace.java |
BizTraceAspect | 用 OpenTelemetry 建 span:component=biz、biz.type、biz.id;异常记 recordException | tracer/core/aop/BizTraceAspect.java |
TraceFilter | 响应头 trace-id 写入当前链路 ID | tracer/core/filter/TraceFilter.java |
PmforgeMetricsAutoConfiguration | 给 MeterRegistryCustomizer 加公共标签 application=<spring.application.name> | tracer/config/PmforgeMetricsAutoConfiguration.java |
TracerFrameworkUtils | 异常上抛时补 error.stack 等 span 事件 | tracer/core/util/TracerFrameworkUtils.java |
3. 自动配置
| 配置类 | 生效条件 | 注册了什么 |
|---|---|---|
PmforgeTracerAutoConfiguration | @ConditionalOnClass(name={"io.opentelemetry.api.trace.Tracer","javax.servlet.Filter"}) + @ConditionalOnProperty(prefix="pmforge.tracer", value="enable", matchIfMissing=true) | Tracer(GlobalOpenTelemetry.getTracer(applicationName),@ConditionalOnMissingBean)、BizTraceAspect(@ConditionalOnMissingBean)、FilterRegistrationBean<TraceFilter>(order = WebFilterOrderEnum.TRACE_FILTER) |
PmforgeMetricsAutoConfiguration | @ConditionalOnClass(MeterRegistryCustomizer.class) + pmforge.metrics.enable=true(缺省 true) | MeterRegistryCustomizer<MeterRegistry>:commonTags("application", spring.application.name) |
4. 配置项
| 前缀 | 键 | 默认值 | 说明 |
|---|---|---|---|
pmforge.tracer | enable | true | 关闭后 Tracer/切面/trace-id 响应头都不装配 |
pmforge.metrics | enable | true | 指标公共标签开关 |
spring.application.name | — | pmforge-server(示例) | 同时作为 Tracer 名与 application 标签值 |
5. 扩展点
- 给业务方法加 span:方法上标
@BizTrace(operationName = "创建任务", type = "'task'", id = "#req.id"),未写operationName时用「类名/方法名」,span 名会加Biz/前缀。 - 加自定义 span 属性:注入
Tracer自己spanBuilder(...);或包一层切面复用TracerFrameworkUtils。 - 改指标标签:声明自己的
MeterRegistryCustomizerBean,与本模块的可叠加(commonTags会合并)。 - 换追踪后端:保持 OpenTelemetry API 不变,只换 javaagent 的 exporter 配置。
6. 常见坑
- 没有 agent 就没有数据:这里只拿
GlobalOpenTelemetry.getTracer(...),若 JVM 没挂 OpenTelemetry/SkyWalking agent,它返回的是 no-op 实现,trace-id也只会是空值——「装了 starter 却查不到链路」多半是这个原因。 @BizTrace的属性要配 OAP 才能搜:BizTraceAspect类注释明确要求 SkyWalking OAP 的SW_SEARCHABLE_TAG_KEYS加上biz.type、biz.id,否则标签只存在 span 上、搜不到。- package-info 与实际实现不一致:模块注释写「使用 SkyWalking」,实现是 OpenTelemetry API + Micrometer,读代码时以
build.gradle/pom 里的依赖为准。 TracerProperties是空类:除enable外没有别的配置项,不要指望在pmforge.tracer.*下调采样率(那是 agent 的事)。TraceFilter用的是javax.servlet:本项目是 Spring Boot 2.7 + JDK 8(全栈javax.*),条件能命中;但一旦升到 Spring Boot 3(jakarta.servlet),@ConditionalOnClass(name="javax.servlet.Filter")会静默不满足,整个 tracer 自动配置随之失效——升级时必须改成jakarta.servlet.Filter。
7. 关联页面
- starter-web:Filter 顺序枚举
WebFilterOrderEnum - starter-job:
@Async线程池的上下文传递 - 配置项速查、访问日志、横切机制