OpenTelemetry agent 对 Spring Boot 应用的影响：一次 SPI 失效的案例

背景

前段时间公司领导让我排查一个关于在 JDK21 环境中使用 Spring Boot 配合一个 JDK18 新增的一个 SPI(java.net.spi.InetAddressResolverProvider) 不生效的问题。

但这个不生效的前置条件有点多：

• JDK 的版本得在 18+
• SpringBoot3.x
• 还在额外再配合使用 -javaagent:opentelemetry-javaagent.jar 使用，也就是 OpenTelemetry 提供的 agent。

才会导致自定义的 InetAddressResolverProvider 无法正常工作。

---

在复现这个问题之前先简单介绍下 java.net.spi.InetAddressResolverProvider 这个 SPI；它是在 JDK18 之后才提供的，在这之前我们使用 InetAddress 的内置解析器来解析主机名和 IP 地址，但这个解析器之前是不可以自定义的。

在某些场景下会不太方便，比如我们需要请求 order.service 这个域名时希望可以请求到某一个具体 IP 地址上，我们可以自己配置 host ，或者使用服务发现机制来实现。

但现在通过 InetAddressResolverProvider 就可以定义在请求这个域名的时候返回一个我们预期的 IP 地址。

同时由于它是一个 SPI，所以我们只需要编写一个第三方包，任何项目依赖它之后在发起网络请求时都会按照我们预期的 IP 进行请求。

复现

要使用它也很简单，主要是两个类：

• InetAddressResolverProvider：这是一个抽象类，我们可以继承它之后重写它的 get 函数返回一个 InetAddressResolver 对象
• InetAddressResolver：一个接口，主要提供了两个函数；一个用于传入域名返回 IP 地址，另一个反之：传入 IP 地址返回域名。

public class MyAddressResolverProvider extends InetAddressResolverProvider {
    @Override
    public InetAddressResolver get(Configuration configuration) {
        return new MyAddressResolver();
    }
    @Override
    public String name() {
        return "MyAddressResolverProvider Internet Address Resolver Provider";
    }
}

public class MyAddressResolver implements InetAddressResolver {

    public MyAddressResolver() {
        System.out.println("=====MyAddressResolver");
    }

    @Override
    public Stream<InetAddress> lookupByName(String host, LookupPolicy lookupPolicy)
            throws UnknownHostException {
        if (host.equals("fedora")) {
            return Stream.of(InetAddress.getByAddress(new byte[] {127, 127, 10, 1}));
        }
        return Stream.of(InetAddress.getByAddress(new byte[] {127, 0, 0, 1}));
    }
    @Override
    public String lookupByAddress(byte[] addr) {
        System.out.println("++++++" + addr[0] + " " + addr[1] + " " + addr[2] + " " + addr[3]);
        return  "fedora";
    }
}

---

```java
addresses = InetAddress.getAllByName("fedora");
// output: 127 127 10 1

这里我简单实现了一个对域名 fedora 的解析，会直接返回 127.127.10.1。

如果使用 IP 地址进行查询时：

InetAddress byAddress = InetAddress.getByAddress(new byte[]{127, 127, 10, 1});

System.out.println("+++++" + byAddress.getHostName());
// output: fedora

当然要要使得这个 SPI 生效的前提条件是我们需要新建一个文件：

META-INF/services/java.net.spi.InetAddressResolverProvider

里面的内容是我们自定义类的全限定名称：

com.example.demo.MyAddressResolverProvider

这样一个完整的 SPI 就实现完成了。

---

正常情况下我们将应用打包为一个 jar 之后运行：

java -jar target/demo-0.0.1-SNAPSHOT.jar

是可以看到输出结果是符合预期的。

一旦我们使用配合上 spring boot 打包之后，也就是加上以下的依赖：

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.2.3</version>
  <relativePath/> <!-- lookup parent from repository -->
</parent>

<build>
  <plugins>
   <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
   </plugin>
  </plugins>
</build>

再次执行其实也没啥问题，也能按照预期输出结果。

但我们加上 OpenTelemetry 的 agent 时：

java  -javaagent:opentelemetry-javaagent.jar \
      -jar target/demo-0.0.1-SNAPSHOT.jar

就会发现在执行解析的时候抛出了 java.net.UnknownHostException异常。

从结果来看就是没有进入我们自定义的解析器。

SPI 原理

在讲排查过程之前还是要先预习下关于 Java SPI 的原理以及应用场景。

以前写过一个 http 框架 cicada，其中有一个可拔插 IOC 容器的功能：

就是可以自定义实现自己的 IOC 容器，将自己实现的 IOC 容器打包为一个第三方包加入到依赖中，cicada 框架就会自动使用自定义的 IOC 实现。

要实现这个功能本质上就是要定义一个接口，然后根据依赖的不同实现创建接口的实例对象。

public interface CicadaBeanFactory {

    /**
     * Register into bean Factory
     * @param object
     */
    void register(Object object);

    /**
     * Get bean from bean Factory
     * @param name
     * @return
     * @throws Exception
     */
    Object getBean(String name) throws Exception;

    /**
     * get bean by class type
     * @param clazz
     * @param <T>
     * @return bean
     * @throws Exception
     */
    <T> T getBean(Class<T> clazz) throws Exception;

    /**
     * release all beans
     */
    void releaseBean() ;
}

获取具体的示例代码时就只需要使用 JDK 内置的 ServiceLoader 进行加载即可：

public static CicadaBeanFactory getCicadaBeanFactory() {
    ServiceLoader<CicadaBeanFactory> cicadaBeanFactories = ServiceLoader.load(CicadaBeanFactory.class);
    if (cicadaBeanFactories.iterator().hasNext()){
        return cicadaBeanFactories.iterator().next() ;
    }
    return new CicadaDefaultBean();
}

代码也非常的简洁，和刚才提到的 InetAddressResolverProvider 一样我们需要新增一个 META-INF/services/top.crossoverjie.cicada.base.bean.CicadaBeanFactory 文件来配置我们的类名称。

private boolean hasNextService() {
    if (nextName != null) {
        return true;
    }
    if (configs == null) {
        try {
        	// PREFIX = META-INF/services/
            String fullName = PREFIX + service.getName();
            if (loader == null)
                configs = ClassLoader.getSystemResources(fullName);
            else
                configs = loader.getResources(fullName);
        } catch (IOException x) {
            fail(service, "Error locating configuration files", x);
        }
    }
    while ((pending == null) || !pending.hasNext()) {
        if (!configs.hasMoreElements()) {
            return false;
        }
        pending = parse(service, configs.nextElement());
    }
    nextName = pending.next();
    return true;
}

在 ServiceLoader 类中会会去查找 META-INF/services 的文件，然后解析其中的内容从而反射生成对应的接口对象。

这里还有一个关键是通常我们的代码都会打包为一个 JAR 包，类加载器需要加载这个 JAR 包，同时需要在这个 JAR 包里找到我们之前定义的那个 spi 文件，如果这里查不到文件那就认为没有定义 SPI。

这个是本次问题的重点，会在后文分析原因的时候用到。

排查

因为问题就出现在是否使用 opentelemetry-javaagent.jar 上，所以我需要知道在使用了 agent 之后有什么区别。

从刚才的对 SPI 的原理分析，加上 agent 出现异常，说明理论上就是没有读取到我们配置的文件: java.net.spi.InetAddressResolverProvider。

于是我便开始 debug，在 ServiceLoader 加载 jar 包的时候是可以看到具体使用的是什么 classLoader 。

这是不配置 agent 的时候使用的 classLoader：



使用这个 loader 是可以通过文件路径在 jar 包中查找到我们配置的文件。

而配置上 agent 之后使用的 classLoader:



却是一个 JarLoader，这样是无法加载到在 springboot 格式下的配置文件的，至于为什么加载不到，那就要提一下 maven 打包后的文件目录和 spring boot 打包后的文件目录的区别了。

这里我截图了同样的一份代码不同的打包方式：

上面的是传统 maven，下图是 spring boot；其实主要的区别就是在 pom 中使用了一个构建插件：

<build>
  <plugins>
   <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
   </plugin>
  </plugins>
</build>

或者使用 spring-boot 命令再次打包的效果也是一样的。

会发现 spring boot 打包后会多出一层 BOOT-INF 的文件夹，然后会在 MANIFIST.MF 文件中定义 Main-Class 和 Start-Class.

---

通过上面的 debug 其实会发现 JarLoader 只能在加载 maven 打包后的文件，也就是说无法识别 BOOT-INF 这个目录。

正常情况下 spring boot 中会有一个额外的 java.nio.file.spi.FileSystemProvider 实现:



通过这个类的实现可以直接从 JAR 包中加载资源，比如我们自定义的 SPI 资源等。

初步判断使用 opentelemetry-javaagent.jar的 agent 之后，它的类加载器优先于了 spring boot ，从而导致后续的加载失败。

远程 debug

这里穿插几个 debug 小技巧，其中一个是远程 debug，因为这里我是需要调试 javaagent，正常情况下是无法直接 debug 的。

所以我们可以使用以下命令启动应用：

java -agentlib:jdwp="transport=dt_socket,server=y,suspend=y,address=5000" -javaagent:opentelemetry-javaagent.jar \
      -jar target/demo-0.0.1-SNAPSHOT.jar

然后在 idea 中配置一个 remote 启动。

注意这里的端口得和命令行中的保持一致。

当应用启动之后便可以在 idea 中启动这个 remote 了，这样便可以正常 debug 了。

条件断点

第二个是条件断点也非常有用，有时候我们需要调试一个公共函数，调用的地方非常多。

而我们只需要关心某一类行为的调用，此时就可以对这个函数中的变量进行判断，当他们满足某些条件时再进入断点，这样可以极大的提高我们的调试效率：

配置也很简单，只需要在断点上右键就可以编辑条件了。

社区咨询

虽然我根据现象初步可以猜测下原因，但依然不确定如何调整才能解决这个问题，于是便去社区提了一个 issue。

最后在社区大佬的帮助下发现我们需要禁用掉 OpenTelemetry agent 中的一个 resource 就可以了。

这个 resource 是由 agent 触发的，它优先于 spring boot 之前进行 SPI 的加载。

目的是为了给 metric 和 trace 新增两个属性：

加载的核心代码在这里，只要禁用掉之后就不会再加载了。

禁用前：

禁用后：

当我们禁用掉之后就不会存在这两个属性了，不过我们目前并没有使用这两个属性，所以为了使得 SPI 生效就只有先禁用掉了，后续再看看社区还有没有其他的方案。

想要复现 debug 的可以在这里尝试：

https://github.com/crossoverJie/demo

参考连接：

• https://github.com/TogetherOS/cicada
• https://docs.spring.io/spring-boot/docs/current/maven-plugin/reference/htmlsingle/#packaging.repackage-goal
• https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/10921
• https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/resources/library/README.md#host