Instrumenting applications at runtime with the binary instrumenter

The binary instrumenter (minerva-agent-1.0.jar) is a Java-based agent which instruments the byte code of your Java monolithic applications so that runtime traces are collected when these applications run. The binary instrumenter dynamically injects instrumentation statements in the form of System.err.println("Entering...") and System.err.println("Exiting...") in all the class methods, including constructors.

The instrumenter uses three JSON files that were created by the code analyzer when it scanned your application Java source files. The JSON files contain metadata about the scanned classes and the binary instrumenter configuration. The metadata includes information such as class names, their typed member attributes, constructors, methods with input arguments and return types, and source file locations of the classes.

The binary instrumenter never prints the value of any variables of your application. The purpose of the instrumentation is to record the temporal flows through various methods and constructors of classes, and not the values of any variables during run time.

Prerequisites

Ensure to meet the system requirements and the following requirements.

• Your application is installed and running on a server such as WebSphere® Application Server or Liberty.
• Run the code analyzer.

Procedure

1. After you run the code analyzer, verify that you have a directory that contains the three JSON files that are created.

   • The symTable.json file
   • The refTable.json file
   • The instrumenter-config.json file

   If you copy these JSON files to another location, make sure to keep them grouped in the same directory.

2. Configure the application server by adding the following argument to its Java virtual machine (JVM).

   -javaagent:<agent-install-path>/minerva-agent-1.0.jar=<agent-config-path>

   Replace the variables with directory paths. Be sure to use the path separator character appropriate for your operating system.

   • <agent-install-path> is the fully qualified path of the directory that contains the minerva-agent-1.0.jar file, which is included in the Mono2Micro-CLI.zip downloadable bundle.
   • <agent-config-path> is the fully qualified path of the directory that contains the three JSON files that are created by the code analyzer.

   For example, if you extracted Mono2Micro-CLI.zip into /m2m-cli/, then the <agent-install-path> is /m2m-cli/instrumenter and the <agent-config-path> is ~/myapp/src-mono2micro/, you would configure the application server by adding the following argument to its JVM.

   -javaagent:/m2m-cli/instrumenter/minerva-agent-1.0.jar=~/myapp/src-mono2micro/

   If your application is installed and running on WebSphere Application Server, you can use the administrative console to specify the JVM argument.

   If your application is installed and running on Liberty, create or update a jvm.options file to specify the JVM argument.

3. Start the application server and your application with the -javaagent JVM argument enabled.

Results

Trace output is added to one or more log files.

What to do next

Deploy the application in nonproduction but representative environments. Follow the same process that you use for deploying the application. Depending on the environments, the applications can be on bare metal machines, virtual machines, or containers.

When the Java monolithic applications run with the binary instrumenter enabled, runtime trace files get generated. Use information from the code analyzer, binary instrumentation, and the use case recorder as input to the AI engine, which generates partition recommendations.