Vert.x 4.2.1服务Zipkin追踪在IDEA正常，fat JAR运行无上报问题求助

1. 核心常见原因：Maven Shade插件未合并SPI服务配置文件 #

Vert.x的链路追踪能力依赖SPI（服务提供者接口）机制加载对应的Tracer实现，默认Maven Shade插件在打包时遇到多个依赖Jar中同路径的SPI配置文件（如META-INF/services/io.vertx.core.spi.tracing.VertxTracerFactory）会直接覆盖而非合并，导致fat JAR中缺失Zipkin追踪实现的SPI注册信息，运行时无法加载追踪逻辑，自然不会上报日志。

解决方案 #

在pom.xml的Maven Shade插件配置中添加ServicesResourceTransformer，自动合并所有SPI服务配置文件，配置示例如下：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.2.4</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>shade</goal>
      </goals>
      <configuration>
        <transformers>
          <!-- 合并SPI服务配置 -->
          <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
          <!-- 保留原有的Vert.x Launcher相关配置 -->
          <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
            <mainClass>io.vertx.core.Launcher</mainClass>
            <manifestEntries>
              <Main-Verticle>你的启动Verticle全类名</Main-Verticle>
            </manifestEntries>
          </transformer>
        </transformers>
      </configuration>
    </execution>
  </executions>
</plugin>

2. 其他排查方向 #

• 确认vertx-zipkin依赖的scope为compile，若为provided则不会被打入fat JAR，运行时缺失对应类无法初始化追踪能力。
• 确认命令行启动时的配置与IDEA运行时一致：IDEA中配置的环境变量、VM参数、程序参数（如Zipkin服务端地址、采样率配置）在命令行启动时是否同步传入，避免配置缺失导致追踪未开启。
• 可解压生成的server.jar，检查META-INF/services/io.vertx.core.spi.tracing.VertxTracerFactory文件内容，确认是否包含io.vertx.tracing.zipkin.ZipkinTracerFactory配置项，快速定位是否为SPI合并问题。

内容的提问来源于stack exchange，提问作者Q. Zhang