Quickstart

This quickstart shows how to start the Hawkular APM server and then instrument your application to start capturing information to help analyse its usage.

Running the Server

Docker

To start and bind to localhost:8080

docker run -p 8080:8080 jboss/hawkular-apm-server-dev

This docker image starts a server with preconfigured user jdoe and password password.

OpenShift

The Hawkular APM can be deployed in OpenShift using two different approaches. Before trying out either approach, make sure you have a running OpenShift environment.

Complete Deployment

The first approach creates a complete deployment of Hawkular APM, including the required services and routes, as well as a default user (admin/password). If you only want to set up a single instance of Hawkular APM, then this is the best option.

oc create -f https://raw.githubusercontent.com/jboss-dockerfiles/hawkular-apm/master/openshift-templates/hawkular-apm-server-deployment.yml

When you log into the OpenShift console you will see the Hawkular APM service. By selecting the associated URL it will bring up the APM UI and allow you to log in using the username admin and password password.

As Template

The second approach creates a "template", which can be used to create new services, and it’s commonly known as "instant app". If you are a service provider and want to let your users deploy APM on demand, on their own namespaces and possibly customizing the deployment, then this is the best option.

oc login -u system:admin
oc create -n openshift -f https://raw.githubusercontent.com/jboss-dockerfiles/hawkular-apm/master/openshift-templates/hawkular-apm-server.yml

Note that the command above installs the template into the openshift namespace, meaning that it’s available to every user on your OpenShift cluster. If you want to restrict this template to a single project, remove the -n openshift option.

The Hawkular APM server will now be listed as an Instant App.

Binary Release

Download and unpack the latest hawkular-apm-dist distribution from Hawkular APM releases.

From the distribution’s root folder:

bin/add-user.sh -a -u jdoe -p password -g read-write,read-only
bin/standalone.sh -b 0.0.0.0 -Djboss.http.port={PORT} (1)

  1. The default port should be 8080, but if a different port is required (e.g. 9411 for zipkin clients) then it can be set here.

Source Build

git clone https://github.com/hawkular/hawkular-apm.git
cd hawkular-apm
mvn clean install -Pdev -DskipTests (1)
cd dist/target/hawkular-apm-dist-${version}
bin/standalone.sh -b 0.0.0.0 -Djboss.http.port={PORT} (2)

  1. The -Pdev argument will build a development distribution containing the default user jdoe with password password.

  2. The default port should be 8080, but if a different port is required (e.g. 9411 for zipkin clients) then it can be set here.

Advanced Configuration

Name Description

HAWKULAR_APM_CORS_ACCESS_CONTROL_ALLOW_HEADERS

List of extra CORS Access-Control-Allow-Headers, this list is added to predefined list of allowed headers.

HAWKULAR_APM_CORS_ALLOWED_ORIGINS

List of allowed CORS origins. By default all origins are allowed.

HAWKULAR_APM_ELASTICSEARCH_CLUSTER

The Elasticsearch cluster name.

HAWKULAR_APM_ELASTICSEARCH_HOSTS

A comma separated list of URLs locating Elasticsearch hosts.

HAWKULAR_PASSWORD

Password for accessing Hawkular Services.

HAWKULAR_URI

Location of the Hawkular Services server.

HAWKULAR_USERNAME

Username for accessing Hawkular Services.

Instrumenting your Application

Explicit instrumentation

Zipkin

If your applcation is instrumented using Zipkin compliant client libraries then simply update your Zipkin URL to point to the Hawkular APM server (e.g. http://localhost:8080 if running all on the local machine).

OpenTracing

OpenTracing is a vendor neutal API used by applications to report distributed tracing information. Hawkular APM currently has implementations for Java and JavaScript (Node.js):

1) Java

If your application is instrumented using the OpenTracing API, then include the following dependencies in your pom.xml:

    <dependency>
      <groupId>org.hawkular.apm</groupId>
      <artifactId>hawkular-apm-client-opentracing</artifactId>
      <version>${version.org.hawkular.apm}</version>
    </dependency>
    <dependency>
      <groupId>org.hawkular.apm</groupId>
      <artifactId>hawkular-apm-trace-publisher-rest-client</artifactId>
      <version>${version.org.hawkular.apm}</version>
    </dependency>

The Hawkular APM Tracer implementation class is org.hawkular.apm.client.opentracing.APMTracer. You will need to set the following:

export HAWKULAR_APM_URI=http://localhost:8080 (1)
export HAWKULAR_APM_USERNAME=jdoe (2)
export HAWKULAR_APM_PASSWORD=password (2)

  1. Set this URL to point to the APM server.

  2. Assumes the default username and password have been configured in the APM server.

2) JavaScript

JavaScript instrumentation can be consumed from npm:

npm install --save hawkular-apm-opentracing

Library can be used in a browser and also in Node.js application. For more examples see our Github repository.

Non-intrusive instrumentation using Java Agent

Note
 There are two variations of the Java Agent. The original one which is the default, and a new prototype which leverages the OpenTracing Java provider to report information to the APM server. This prototype version only instruments a reduced set of technologies currently, and does not support the business transaction configuration capability. The benefit of the new agent is that the rules are simpler (using the OpenTracing API) and therefore will be easier to maintain and hopefully lead to contributions.
Using script from binary release
. ${APM_HOME}/apm/setenv.sh port [opentracing]  (1)

  1. Where port must match the port used for the APM server. The second opentracing parameter is optional and if supplied will use the new prototype OpenTracing based java agent.

This script configures some environment variables and JAVA_OPTS to enable an agent to non-intrusively instrument your application and send the details to the APM server. After executing the script, run your Java application supplying the JAVA_OPTS environment variable.

Setting up the agent manually

Download the latest hawkular-apm-agent.jar (or hawkular-apm-agent-opentracing.jar if using the prototype OpenTracing based agent) from Hawkular APM releases.

export HAWKULAR_APM_URI=http://localhost:8080  (1)
export HAWKULAR_APM_USERNAME=jdoe (2)
export HAWKULAR_APM_PASSWORD=password (2)

If using the original java agent, then:

export JAVA_OPTS="-javaagent:${PATH_TO}/hawkular-apm-agent.jar" (3)

# Wildfly specific
export JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=org.jboss.byteman,org.hawkular.apm.instrumenter,org.hawkular.apm.client.collector"

Otherwise, if using the new prototype OpenTracing based java agent, then:

export JAVA_OPTS="-javaagent:${PATH_TO}/hawkular-apm-agent-opentracing.jar" (3)

# Wildfly specific
export JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=org.jboss.byteman,org.hawkular.apm.agent.opentracing,io.opentracing,org.hawkular.apm.client.opentracing"
java $JAVA_OPTS ....... (4)

  1. Set this URL to point to the APM server.

  2. Assumes the default username and password have been configured in the APM server.

  3. Must define the path to the hawkular-apm-agent.jar

  4. Add the $JAVA_OPTS environment variable to your Java command line