Otel扩展引入外部库遇ClassNotFoundException（Maven环境）

核心原因是OpenTelemetry Agent的类加载器是隔离的，不会自动读取应用或全局类路径中的第三方库，必须将依赖的外部库打包到你的instrumentation jar中，让Agent的类加载器能访问到。以下是具体解决方案：

1. 使用Maven Shade Plugin打包外部依赖 #

Shade插件可以将第三方依赖合并到你的instrumentation jar中，确保Agent加载你的扩展时能同时加载这些依赖。

关键配置示例 #

在你的pom.xml中添加Shade插件配置，指定需要打包的外部库（比如com.jayway.jsonpath及其传递依赖），同时排除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>
                            <includes>
                                <!-- 打包jsonpath核心库 -->
                                <include>com.jayway.jsonpath:json-path</include>
                                <!-- 打包jsonpath依赖的jackson相关库 -->
                                <include>com.fasterxml.jackson.core:jackson-databind</include>
                                <include>com.fasterxml.jackson.core:jackson-core</include>
                                <include>com.fasterxml.jackson.core:jackson-annotations</include>
                            </includes>
                            <!-- 排除Otel自身依赖，避免与Agent内置版本冲突 -->
                            <excludes>
                                <exclude>io.opentelemetry:*</exclude>
                            </excludes>
                        </artifactSet>
                        <transformers>
                            <!-- 合并服务注册文件（Otel通过SPI加载InstrumentationModule） -->
                            <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                        </transformers>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

2. 调整依赖Scope #

确保外部库的依赖Scope设置为compile（默认就是compile，无需额外修改），这样Shade插件会将其打包；而OpenTelemetry的核心依赖（如opentelemetry-instrumentation-api）设置为provided，避免重复打包：

<dependencies>
    <!-- Otel核心API，设为provided避免打包 -->
    <dependency>
        <groupId>io.opentelemetry.instrumentation</groupId>
        <artifactId>opentelemetry-instrumentation-api</artifactId>
        <version>1.32.0</version>
        <scope>provided</scope>
    </dependency>
    <!-- jsonpath依赖，compile scope会被Shade打包 -->
    <dependency>
        <groupId>com.jayway.jsonpath</groupId>
        <artifactId>json-path</artifactId>
        <version>2.8.0</version>
    </dependency>
</dependencies>

3. 验证打包结果 #

执行mvn clean package后，解压生成的shaded jar文件，检查是否包含com/jayway/jsonpath及相关依赖的类文件。如果缺少依赖，可通过mvn dependency:tree查看依赖树，补充对应的include配置。

额外注意事项 #

• 不要打包与Agent内置版本冲突的库：比如Otel自身的API、SDK等，否则会引发类加载异常。
• 如果外部库存在签名问题（比如某些jar有数字签名），Shade打包后可能会破坏签名，此时需要在Shade配置中添加filters排除签名文件：

<filters>
    <filter>
        <artifact>*:*</artifact>
        <excludes>
            <exclude>META-INF/*.SF</exclude>
            <exclude>META-INF/*.DSA</exclude>
            <exclude>META-INF/*.RSA</exclude>
        </excludes>
    </filter>
</filters>

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