求基于Maven嵌入自定义扩展到OpenTelemetry Java Agent的示例

1. 配置依赖 #

在项目的pom.xml中添加必要依赖：

<dependencies>
    <!-- OpenTelemetry Agent 核心依赖，设为provided避免重复打包 -->
    <dependency>
        <groupId>io.opentelemetry.javaagent</groupId>
        <artifactId>opentelemetry-javaagent</artifactId>
        <version>1.35.0</version> <!-- 替换为最新稳定版本 -->
        <scope>provided</scope>
    </dependency>
    <!-- 你的自定义扩展模块依赖，若扩展是当前项目代码可省略 -->
    <dependency>
        <groupId>com.yourcompany</groupId>
        <artifactId>your-otel-extension</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

2. 配置Maven Shade插件 #

这是实现打包的核心步骤，通过插件将Agent与扩展合并，并处理扩展的注册逻辑：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.5.1</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <configuration>
                        <!-- 自定义最终生成的Jar文件名 -->
                        <finalName>opentelemetry-javaagent-with-my-ext</finalName>
                        <!-- 指定要打包的核心构件 -->
                        <artifactSet>
                            <includes>
                                <include>io.opentelemetry.javaagent:opentelemetry-javaagent</include>
                                <include>com.yourcompany:your-otel-extension</include>
                            </includes>
                        </artifactSet>
                        <!-- 关键：合并扩展注册文件，让Agent识别并加载扩展 -->
                        <transformers>
                            <!-- 合并META-INF/services下的扩展声明文件 -->
                            <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                            <!-- 保留Agent的主类，确保Jar可作为JavaAgent启动 -->
                            <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                                <mainClass>io.opentelemetry.javaagent.OpenTelemetryAgent</mainClass>
                            </transformer>
                        </transformers>
                        <!-- 排除签名文件，避免打包冲突 -->
                        <filters>
                            <filter>
                                <artifact>*:*</artifact>
                                <excludes>
                                    <exclude>META-INF/*.SF</exclude>
                                    <exclude>META-INF/*.DSA</exclude>
                                    <exclude>META-INF/*.RSA</exclude>
                                </excludes>
                            </filter>
                        </filters>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

3. 重要注意事项 #

• 替换配置中的版本号、groupId、artifactId为你项目的实际值。
• 自定义扩展必须实现io.opentelemetry.javaagent.extension.AgentExtension接口，并且在扩展模块的META-INF/services/io.opentelemetry.javaagent.extension.AgentExtension文件中写入实现类的全限定名（例如：com.yourcompany.otel.extension.MyCustomExtension）。
• ServicesResourceTransformer不可省略，它会将扩展的注册信息合并到Agent的services文件中，否则Agent启动时无法加载你的扩展。

4. 执行打包 #

运行以下Maven命令完成打包：

mvn clean package

打包完成后，target目录下的opentelemetry-javaagent-with-my-ext.jar就是内嵌了自定义扩展的完整Agent Jar，直接用java -javaagent:./target/opentelemetry-javaagent-with-my-ext.jar -jar your-app.jar启动应用即可。

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