如何让Spring Cloud Sleuth识别Spring MVC控制器参数上的@SpanTag注解

云上老周

2026-9-26

问题原因

Spring Cloud Sleuth 默认不会对普通 Spring MVC 控制器方法自动扫描参数上的@SpanTag注解，该注解的解析逻辑默认仅对标注了@NewSpan（生成新Span）或@ContinueSpan（沿用现有Span）的方法生效，所以你直接在控制器方法参数上加@SpanTag不会被识别。

解决方案

方案1：搭配`@ContinueSpan`注解使用

不需要生成新的Span，仅需在控制器方法上添加@ContinueSpan注解，即可触发@SpanTag的解析逻辑，沿用当前请求的根Span添加标签：

@RestController
@RequestMapping("/api/auth")
class ExampleController() {

    // 新增@ContinueSpan注解，不会生成额外Span
    @ContinueSpan
    @PostMapping("/create")
    fun createToken(
            @SpanTag(key="username",expression = "username") 
            @RequestBody 
            authTokenRequest: Request){
        // 业务逻辑
    }
}

注意：如果后续仍不生效，可检查Request类是否存在username字段的公共Getter方法，SpEL表达式需要通过Getter读取属性值。

方案2：手动注入Tracer添加标签

该方案更稳定无额外注解解析开销，直接获取当前活跃Span手动添加标签即可：

@RestController
@RequestMapping("/api/auth")
// 注入Tracer实例
class ExampleController(private val tracer: Tracer) {

    @PostMapping("/create")
    fun createToken(
            @RequestBody 
            authTokenRequest: Request){
        // 手动添加自定义标签到当前Span
        tracer.currentSpan()?.tag("username", authTokenRequest.username)
        // 业务逻辑
    }
}

注意事项