Java Agent Custom Extension - Application Real-Time Monitoring Service

Starting from version 4.x, the ARMS Java agent has been completely restructured based on opentelemetry-java-instrumentation. Therefore, the ARMS 4.x version agent also inherits the custom instrumentation capabilities of opentelemetry-java-instrumentation. This topic demonstrates the overall process of custom instrumentation using the example of adding custom instrumentation to Motan (an RPC framework).

Opentelemetry-java-instrumentation supports specifying the path of a custom extension JAR file by setting the -Dotel.javaagent.extensions parameter or the environment variable key OTEL_JAVAAGENT_EXTENSIONS. You can implement the following features in this JAR file:

Custom TraceId generator
Custom Trace context propagation protocol
Custom trace sampler
Custom SpanProcessor
Custom instrumentation logic

For stability and security considerations, the 4.x agent currently only supports custom instrumentation functionality.

Procedure

Step 1: Download and compile the custom instrumentation code

Execute the following command to download the custom instrumentation demo project.
This project implements client and server instrumentation for the Motan framework by generating a Span when the client initiates an RPC call and when the server receives an RPC call. It also uses the Motan framework's protocol header to propagate the trace context.
```
git clone git@github.com:aliyun-observability/aliyun-javaagent-extension-demo.git
```
Enter the project root directory and execute the ./gradlew build command.
Note
The JDK version of the current compilation environment must be JDK17.
After executing this command, the compiled JAR file will be in the .build/libs directory. This is the custom extension JAR package.

Step 2: Download the ARMS agent

Log on to the ARMS console.
In the navigation pane on the left, choose Application Monitoring > Agent Management. In the top navigation bar, select a region.
Click the Agent Release Notes tab, download version 4.x or later of the agent, and place it in an appropriate directory.

Step 3: Download and compile the Motan demo application

Download the Motan application.

git clone https://github.com/weibocom/motan.git

Enter the project root directory and execute the cd motan-demo && mvn clean package command.
After execution, you can find the motan-demo-server and motan-demo-client sample applications in the ${motan-root}/motan-demo/motan-demo-client/target and ${motan-root}/motan-demo/motan-demo-server/target directories.

Step 4: Load the custom extension package when starting the application

Start the server application: java -javaagent:/path/to/aliyun-java-agent.jar -Darms.appName=motan-client -Darms.licenseKey=${your licenseKey} -Dotel.javaagent.extensions=/path/to/opentelemetry-extension-demo-1.0.jar -jar /path/to/motan-demo-server.jar
Start the client application: java -javaagent:/path/to/aliyun-java-agent.jar -Darms.appName=motan-server -Darms.licenseKey=${your licenseKey} -Dotel.javaagent.extensions=/path/to/opentelemetry-extension-demo-1.0.jar -jar /path/to/motan-demo-client.jar

Modify the following parameters according to your actual situation:

/path/to/aliyun-java-agent.jar: The agent downloaded in Step 2.
${your licenseKey}: You can obtain the LicenseKey through the DescribeTraceLicenseKey OpenAPI.
/path/to/opentelemetry-extension-demo-1.0.jar: The custom extension JAR package obtained in Step 1.
/path/to/motan-demo-server.jar: The motan-demo-server sample application downloaded in Step 3.
/path/to/motan-demo-client.jar: The motan-demo-client sample application downloaded in Step 3.

Step 5: View the monitoring results

Execute curl http://localhost:8080/ multiple times to report data to ARMS.
View the Trace details in the ARMS console. You can see the generated Motan client span and Motan server span.

Notes

When implementing custom instrumentation, you need to include OpenTelemetry dependencies. For the best compatibility, please include the OpenTelemetry dependency versions according to the following mapping relationship.
ARMS Java version
OpenTelemetry dependency version
4.1.0 ~ Latest
1.28
Do not start the package name of your custom instrumentation with io.opentelemetry.javaagent.instrumentation to avoid class conflicts with existing enhancement code in the ARMS agent.
In custom instrumentation, try to avoid introducing frameworks other than OpenTelemetry and the framework you are instrumenting to avoid class conflicts between the instrumentation code and the application code.

ARMS Java version	OpenTelemetry dependency version
4.1.0 ~ Latest	1.28