Skip to content

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.enabletracer/config/TracerProperties.java
BizTrace注解:operationName()、id()、type(),后两个支持 SpELtracer/core/annotation/BizTrace.java
BizTraceAspect用 OpenTelemetry 建 span:component=biz、biz.type、biz.id;异常记 recordExceptiontracer/core/aop/BizTraceAspect.java
TraceFilter响应头 trace-id 写入当前链路 IDtracer/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.tracerenabletrue关闭后 Tracer/切面/trace-id 响应头都不装配
pmforge.metricsenabletrue指标公共标签开关
spring.application.name—pmforge-server(示例)同时作为 Tracer 名与 application 标签值

5. 扩展点 ​

  • 给业务方法加 span:方法上标 @BizTrace(operationName = "创建任务", type = "'task'", id = "#req.id"),未写 operationName 时用「类名/方法名」,span 名会加 Biz/ 前缀。
  • 加自定义 span 属性:注入 Tracer 自己 spanBuilder(...);或包一层切面复用 TracerFrameworkUtils。
  • 改指标标签:声明自己的 MeterRegistryCustomizer Bean,与本模块的可叠加(commonTags 会合并)。
  • 换追踪后端:保持 OpenTelemetry API 不变,只换 javaagent 的 exporter 配置。

6. 常见坑 ​

  1. 没有 agent 就没有数据:这里只拿 GlobalOpenTelemetry.getTracer(...),若 JVM 没挂 OpenTelemetry/SkyWalking agent,它返回的是 no-op 实现,trace-id 也只会是空值——「装了 starter 却查不到链路」多半是这个原因。
  2. @BizTrace 的属性要配 OAP 才能搜:BizTraceAspect 类注释明确要求 SkyWalking OAP 的 SW_SEARCHABLE_TAG_KEYS 加上 biz.type、biz.id,否则标签只存在 span 上、搜不到。
  3. package-info 与实际实现不一致:模块注释写「使用 SkyWalking」,实现是 OpenTelemetry API + Micrometer,读代码时以 build.gradle/pom 里的依赖为准。
  4. TracerProperties 是空类:除 enable 外没有别的配置项,不要指望在 pmforge.tracer.* 下调采样率(那是 agent 的事)。
  5. 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. 关联页面 ​