manoelcampos/java-collections-advisor

An experimental Java 11 Agent to intercept JDK Collection calls, compute metrics and provide some advices (WIP)

Java Collections Advisor

1. Introduction

2. Build and Running

In order to just try the agent you have two options:

• run the com.manoelcampos.collectionsadvisor.AgentEntry class from the agent dir in your IDE;
• or execute the agent/run.sh script.

2.1. Running an independent app

If you are building your own app and want to load the agent during application startup, check the sample-app project. Execute the sample-app/run.sh script to build and run the app using the agent.

The sample app has no agent code and the instrumentation happens in runtime.

3. Results after running the agent with your app

Current results are very basic since this is a working in progress. The agent is not giving any advice about collections utilization yet. Check an example of the agent results over a sample app using some Collections.

# Collections Advisor Agent
## Intercepted java.util.Collection methods calls from com.sample package

java.util.ArrayList from com.sample.ArrayListRegularSample:
  	Calls: 23 Lookups: 10 Clear Ups: 0
	Capacity changes: 1 -> inc 1 dec 0 | Size changes: 11 -> inc 10 dec 1
	Inserts: 10 -> head 0 middle 0 tail 10 moves 0
	Removals: 1 -> head 0 middle 0 tail 1 moves 0
java.util.ArrayList from com.sample.ArrayListAsQueueSample:
  	Calls: 31 Lookups: 0 Clear Ups: 0
	Capacity changes: 1 -> inc 1 dec 0 | Size changes: 20 -> inc 10 dec 10
	Inserts: 10 -> head 0 middle 0 tail 10 moves 0
	Removals: 10 -> head 9 middle 0 tail 1 moves 45
java.util.ArrayList from com.sample.ArrayListHeadAddSample:
  	Calls: 10 Lookups: 0 Clear Ups: 0
	Capacity changes: 1 -> inc 1 dec 0 | Size changes: 10 -> inc 10 dec 0
	Inserts: 10 -> head 9 middle 0 tail 1 moves 45
	Removals: 0 -> head 0 middle 0 tail 0 moves 0
java.util.LinkedList from com.sample.LinkedListSample:
  	Calls: 22 Lookups: 10 Clear Ups: 1
	Capacity changes: 0 -> inc 0 dec 0 | Size changes: 11 -> inc 10 dec 1
	Inserts: 10 -> head 0 middle 0 tail 10 moves 0
	Removals: 0 -> head 0 middle 0 tail 0 moves 0

4. References

• ByteBuddy Tutorial
• Runtime Code Generation with Byte Buddy
• Fixing Bugs in Running Java Code with Dynamic Attach
• How to Make Java More Dynamic with Runtime Java Code Generation (1/2)
• Using Byte Buddy for Annotation Driven Java (2/2)
• Rafael Winterhalter - The definitive guide to Java agents (JPoint 2019)

java-collections-advisor's Issues

Agent is not intercepting method calls when using -javaagent parameter

Try replacing the main and premain methods in CollectionAgent by agentmain as in https://youtu.be/OF3YFGZcQkg?t=1923

Agent advice is not working to instrument JDK classes

Classes loaded on the JVM bootstrap process (such ash JDK classes) need special ByteBuddy configuration so that they can be instrumented using an Advice.

CollectionsAdvice.metricMap is empty when called from a different class

The map is updated inside the exit() method. However, when CollectionAdvice.printMetrics() is called from CollectionAgent, the map is empty.

Moving the map inside other classes such as CollectionAgent throws the following exception:

Starting com.manoelcampos.collectionsadvisor.Test
Exception in thread "main" java.lang.NoClassDefFoundError: com/manoelcampos/collectionsadvisor/CollectionAgent
	at java.base/java.util.LinkedList.add(LinkedList.java:343)
	at com.manoelcampos.collectionsadvisor.Test.<init>(Test.java:17)
	at com.manoelcampos.collectionsadvisor.CollectionAgent.main(CollectionAgent.java:40)

Shows the name of the caller class

When an advised method is called, shows the name of the class from where the object containing the advised method was called.

Calls to metricMap inside the CollectionAdvice are not working

Check details here.

Accept agent command line parameter to indicate the package to track calls from Collection objects

CollectionAdvice.INSPECT_PACKAGE_NAME constant indicates the package where to track calls for methods of JDK java.util.Collection objects.

The agent accepts command line parameters which are passed to its premain() method on CollectionAgent class.
We have to check if this parameter was given to update CollectionAdvice.INSPECT_PACKAGE_NAME.

Extract metrics.jar from collections-advisor-agent uber jar in runtime

That will avoid having to place the metrics jar into some dir where the app is being executed.
That metrics.jar is load in the bootstrap class load because it's shared between the agent and the app.
This way, it enables the agent to store static data and the app to read it.

By requiring the sample jar to be into the app/agent dir so that the agent can load it on the bootstrap classloader, makes it more difficult to use the agent.
Since the agent is a uber jar that have the metrics as a dependency in the pom.xml, we can extract the metrics.jar dynamically from the uber jar and load it on the bootstrap class path.

For more details check #5.