When instrumenting a Java application, whether a standalone Java app, or components running within an application server, we only need to set the JAVA_OPTS environment variable to reference a javaagent jar, and define some properties for contacting the BTM server (i.e. URL and username/password).
When running an application within a docker image, although it is possible to specify environment variables (such as JAVA_OPTS), it is not possible to reference files (i.e. jars) outside of the image. Therefore to be able to instrument an image, we need to create a separate image based on the one we wish to instrument, with the additional steps required to include the javaagent and required properties.
To achieve this, create a separate folder from the image being instrumented, and define the following file:
# To build:
# To run:
ENV BTM_URI http://localhost:8180/hawkular/btm
ENV BTM_USERNAME jdoe
ENV BTM_PASSWORD password
ADD https://repository.jboss.org/nexus/service/local/artifact/maven/redirect?r=releases&g=org.hawkular.btm&a=hawkular-btm-agent-rest&v=$BTM_VERSION&e=jar $BTM_AGENT
ENV JAVA_OPTS -javaagent:$BTM_AGENT=boot:$BTM_AGENT -Dhawkular-btm.base-uri=\$BTM_URI -Dhawkular-btm.config.refresh=10 -Dhawkular-btm.username=\$BTM_USERNAME -Dhawkular-btm.password=\$BTM_PASSWORD
Most of the dockerfile is defining environment variable defaults, but the most important steps are the final two, adding the Hawkular BTM agent to the image and then defining the JAVA_OPTS variable to reference it (along with the required properties).
Next we need to build the new instrumented image:
Once this has been successfully built, we need to start up a BTM server. This can be done by downloading the most recent distribution from https://github.com/hawkular/hawkular-btm/releases, unpacking the distribution and running the following command from the top level folder:
This starts the BTM server on port 8180, so it does not conflict with the port being used by the instrumented application.
Final step is to run the instrumented example:
Instead of defining port mapping, we have used the --net=host option, to enable the instrumented application to call out to the BTM server running on the host. Also, the default environment variables can be overridden by using the --env option (e.g. --env BTM_URI=http://……).
Finally, once the Succeeded in deploying verticle message is displayed, we return to a browser. If we enter a URL http://localhost:8080/test/app and press return, we should see the same message as before (Wild world).
If we now go to the BTM console (http://localhost:8180/hawkular-ui/btm logging in as jdoe with password password), you should see the entered URL in the Candidates page. This shows that the BTM server has been informed about the business transaction performed on that URI.