使用Maven而非Gradle创建OpenTelemetry扩展Jar遇问题求助

以下是针对Maven构建扩展Jar无法正常加载的常见排查点：

1. 检查SPI配置文件是否正确打包 #

OpenTelemetry JavaAgent通过Java SPI机制加载扩展，必须确保Jar中包含META-INF/services/io.opentelemetry.javaagent.extension.AgentExtension文件，文件内容为你的扩展类全限定名。

• Maven默认会打包src/main/resources下的文件，但如果项目配置了资源过滤，可能会漏掉该文件。可在pom.xml中添加maven-resources-plugin确保资源被正确包含：

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-resources-plugin</artifactId>
      <version>3.3.1</version>
      <configuration>
        <nonFilteredFileExtensions>
          <nonFilteredFileExtension>services</nonFilteredFileExtension>
        </nonFilteredFileExtensions>
      </configuration>
    </plugin>
  </plugins>
</build>

2. 确认依赖打包方式正确 #

扩展Jar需要包含自身依赖（除OpenTelemetry核心依赖外，避免与Agent冲突），Maven默认打包不会包含依赖，需使用maven-shade-plugin：

• 配置shade插件打包依赖，并排除Agent已有的OpenTelemetry核心库：

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-shade-plugin</artifactId>
      <version>3.4.1</version>
      <executions>
        <execution>
          <phase>package</phase>
          <goals>
            <goal>shade</goal>
          </goals>
          <configuration>
            <artifactSet>
              <excludes>
                <exclude>io.opentelemetry:*</exclude>
                <!-- 排除其他与Agent冲突的依赖 -->
              </excludes>
            </artifactSet>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

3. 验证扩展类实现与类加载 #

• 确保扩展类正确实现了AgentExtension接口（或对应扩展点如InstrumentationModule），类全限定名无拼写错误。
• 检查Java版本兼容性：Agent通常基于Java 8编译，扩展代码不要使用Java 8以上的语法特性，避免类加载失败。

4. 检查Jar包结构 #

手动解压Maven构建的Jar，确认：

• META-INF/services/io.opentelemetry.javaagent.extension.AgentExtension存在且内容正确
• 扩展类及需打包的依赖类在Jar中路径正确
• 无重复类或冲突依赖

5. 开启调试日志排查 #

启动应用时添加-Dotel.javaagent.debug=true，查看Agent的调试输出，重点关注：

• 扩展加载的日志条目，比如是否显示“Loaded extension from...”或加载失败的异常信息
• 确认-Dotel.javaagent.extensions参数路径正确，建议使用绝对路径避免路径解析问题

内容的提问来源于stack exchange，提问作者S317