OpenTelemetry Java Agent扩展未加载问题排查求助

问题描述 #

我创建了一个仅包含单个类的简易OpenTelemetry Java Agent扩展，代码如下：

import com.google.auto.service.AutoService;
import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizer;
import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider;

@AutoService(AutoConfigurationCustomizerProvider.class)
public class DummyAutoConfigurationCustomizerProvider implements AutoConfigurationCustomizerProvider {

    static {
        System.out.println("initialized DummyAutoConfigurationCustomizerProvider");
    }

    @Override
    public void customize(AutoConfigurationCustomizer autoConfigurationCustomizer) {
        System.out.println("customizing DummyAutoConfigurationCustomizerProvider");
    }
}

已生成该扩展的shaded JAR包，并通过以下Java选项启动应用：

-javaagent:/opentelemetry-javaagent.jar -Dotel.javaagent.extensions=/lib-all.jar

但未发现扩展加载的迹象，仅输出如下日志：

[otel.javaagent 2024-07-30 16:04:35:751 +0200] [main] INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: 2.5.0

可能的遗漏点及解决方案 #

• 检查AutoService生成的配置文件是否存在
  @AutoService注解需要在JAR包的META-INF/services/目录下生成io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider文件，文件内容是你的实现类的全限定名（比如com.yourpackage.DummyAutoConfigurationCustomizerProvider）。如果shading过程中丢失了这个文件，Agent就找不到你的扩展。可以解压shaded JAR包，确认该文件是否存在且内容正确。

• 确认shaded JAR包的依赖兼容性
  你的扩展依赖的OpenTelemetry SPI版本必须和使用的Java Agent版本（2.5.0）完全匹配。如果shading时引入了不同版本的OTel依赖，会导致类加载冲突，Agent无法加载扩展。确保你的构建脚本（Maven/Gradle）中OTel相关依赖的版本和Agent版本一致，并且shading时正确处理了依赖的relocation（如果需要）。

• 验证扩展JAR的路径是否正确
  检查-Dotel.javaagent.extensions=/lib-all.jar中的路径是否绝对正确，JAR文件是否存在且可读。可以尝试使用绝对路径，或者相对路径时确认当前工作目录是否正确。

• 开启Agent的调试日志排查
  添加-Dotel.javaagent.debug=true启动参数，Agent会输出更详细的加载日志，包括扩展加载的过程和可能的错误信息，这能帮你定位具体是加载时哪一步出了问题。

• 确认扩展类的访问权限
  你的DummyAutoConfigurationCustomizerProvider类必须是public的，并且所在的包是可被Agent类加载器访问的。shading过程中如果意外修改了类的访问权限，也会导致加载失败。

内容的提问来源于stack exchange，提问作者Harold L. Brown