JVM Agent

Configuring a Client Environment

This section will help you to configure a JVM based client environment to instrument an application and send trace fragment data to the APM server.

First step is to obtain the Hawkular APM distribution. If you have not already done so, then see the instructions on the Server Installation page.

Once the Hawkular APM distribution zip has been unpacked, you will find a folder called apm. This folder contains the necessary environment script and agent jar(s) to configure a client JVM environment.

This section will explain how to use the supplied environment script, to setup the necessary client configuration, before starting the JVM. However if you would prefer to integrate this environment into your application/container configuration, then simply copy the entries from the contained setenv.sh script, moving the relevant agent jar into an appropriate location.

To configure a client environment, simply run the setenv.sh script:

. ${APM_HOME}/apm/setenv.sh port [opentracing]

This sets the JAVA_OPTS environment variable with the appropriate arguments to instrument any technology for which instrumentation rules have been defined.

The port parameter defines the local port upon which which the APM server has been started, usually 8080.

The optional opentracing parameter indicates that the new prototype OpenTracing based java agent should be used. This agent provides simpler ByteMan rules that leverage the OpenTracing Java provider, however it currently does not cover the range of technologies handled by the default agent, or support the transaction configuration capabilities.

Properties

The properties that can be supplied to the client collector mechanism as environment variables and/or system properties. If both mechanisms are used, then the system properties will override the environment variables. The property names are:

Name Description

HAWKULAR_APM_URI

The URI for the APM server. The default value defined in the setenv.sh script is the supplied port on the localhost.

HAWKULAR_APM_USERNAME

The username to use with the REST client when communicating with the APM server. The default defined in the setenv.sh script is jdoe.

HAWKULAR_APM_PASSWORD

The password to use with the REST client when communicating with the APM server. The default defined in the setenv.sh script is password.

HAWKULAR_APM_CONFIG_REFRESH

Optional business transaction configuration refresh interval (in seconds).

HAWKULAR_APM_LOG_LEVEL

The logging level to use when reporting client collector information to the console (uses Java Util Logging levels. The default is INFO.

HAWKULAR_APM_SERVICE_NAME

The service name to be added to the trace information. When not set, the environment variables OPENSHIFT_BUILD_NAMESPACE and OPENSHIFT_BUILD_NAME are used to derive a sensible value. NOTE: These properties are only used with the OpenTracing providers, so won’t be relevant if using the older Java Agent.

Container Specific Configuration

Although the steps above will work in many situations (e.g. Java standalone, Apache Tomcat), some environments have tighter control over the classpath made available to the business applications. Therefore some additional container specific configuration will be required.

Wildfly / JBoss EAP

Wildfly requires any 'system packages', that need to be generally accessible by any application, to be defined in a system property called jboss.modules.system.pkgs.

This property has been preconfigured in the setenv.sh script so no additional actions are required. However it has been described to highlight the additional step that was required.

Karaf

Edit the etc/config.properties file, within the Karaf installation, and append the following to the org.osgi.framework.bootdelegation property:

org.osgi.framework.bootdelegation=...,org.jboss.byteman.*

Instrumenting a Docker Image

If a docker image has been defined to run a Java based application, it is possible to instrument it, to collect trace data and report it to the APM server. This can be achieved by creating a derived Docker image, which adds the APM agent and defines the properties required to communicate with the server.

The Dockerfile should be:

FROM <Name of image being instrumented>

ENV APM_VERSION=<APM Version being used>
ENV APM_AGENT=/libs/hawkular-apm-agent.jar

ADD https://repository.jboss.org/nexus/service/local/artifact/maven/redirect?r=releases&g=org.hawkular.apm&a=hawkular-apm-agent&v=$APM_VERSION&e=jar $APM_AGENT

ENV JAVA_OPTS -javaagent:$APM_AGENT=boot:$APM_AGENT

The environment variables HAWKULAR_APM_URI, HAWKULAR_APM_USERNAME and HAWKULAR_APM_PASSWORD should be supplied at runtime.

Note
 If using the OpenTracing based java agent, then replace hawkular-apm-agent in the Dockerfile with hawkular-apm-agent-opentracing.

Instrumented Technologies

This section lists the technologies that have instrumentation rules defined:

  • Apache Camel (core only, but this provides details of various components that are called)

  • HTTP clients

    • Java HttpURLConnection *

    • Apache httpclient *

    • RESTEasy JAX-RS client *

  • JMS

  • Servlet

  • Restlet

  • JDBC *

  • EJB (within Wildfly / JBoss EAP)

  • SwitchYard

  • RxJava

  • Netty

(*) Also supported in the OpenTracing based Java Agent.

Adding Custom Rules to the OpenTracing JVM Agent

When using the OpenTracing based JVM agent approach, it is possible to include custom ByteMan rules to:

  • instrument third party libraries not currently covered by the standard set of rules bundled with the agent (please consider contributing these to the Hawkular APM project for wider use and support)

  • instrument your own application code/libraries

  • add tags (application context and/or business metrics) and logs to spans

The rule files should be placed in a sub-folder apmrules within the application’s classpath.

The rules should use a helper class org.hawkular.apm.agent.opentracing.OpenTracingManager to provide functions for accessing the OpenTracing tracer and performing specific tasks.