TracesMetricsApp LogsCustom LogsProfiling

This guide walks you through setting up Application Performance Monitoring (APM) on a Java application. These instructions can also be found on the Installation page in your Middleware Account. View example code here.

Prerequisites

  • Middleware Host Agent (MW Agent), to install the MW Agent please see our installation guide.
  • Java 8+, you can check your Java version with the following command.
Shell
java --version

Step 1: Download JAR

Download the latest Middleware instrumentation JAR file from the Github release page.

Step 2: Container Variables

Applications running in a container require an additional environment variable. If your application is not running in a container, move to Step 5.

For Docker containers, add the following environment variable to your application.

Shell
MW_AGENT_SERVICE=<DOCKER_BRIDGE_GATEWAY_ADDRESS>
docker bridge gateway address is the IP address of the gateway between the Docker host and the bridge network, which is 172.17.0.1 by default. Refer more about Docker bridge networking here
Shell
kubectl get service --all-namespaces | grep mw-service

Then add the following environment variable to your application deployment YAML file.

Shell
MW_AGENT_SERVICE=mw-service.mw-agent-ns.svc.cluster.local

Step 3: Capture Application Data

Traces

Distributed tracing will be automatically enabled upon completing Step 4: Run Application.

Metrics

Metrics collection will be automatically enabled upon completing Step 4: Run Application.

Application & Custom Logs

Application Logs will be automatically enabled upon completing Step 4: Run Application.

To add custom logs, add this dependency in the pom.xml file.

Java
<dependency>
  <groupId>io.github.middleware-labs</groupId>
  <artifactId>agent-apm-java</artifactId>
  <version>0.0.16</version>
</dependency>

Install the package into the local repository.

Shell
mvn install

Import the logger package.

Java
import io.github.middlewarelabs.agentapmjava.Logger;

Then utilize the following functions based on desired log severity levels.

Java
Logger.info("info message");
Logger.debug("debug message");
Logger.warn("warn message");
Logger.error("error message");

Profiling

Application Profiling is automatically enabled upon completing Step 4: Run Application.

Stack Traces

Use the Logger.recordError(e) method to record a stack trace when an error occurs. See an example of this method below.

Java
import io.github.middlewarelabs.agentapmjava.Logger;
        
try {
       int[] myNumbers = {1, 2, 3};
       System.out.println(myNumbers[10]);
     } catch (Throwable  e) {
       Logger.recordError(e);
       System.out.println("Something went wrong.");
     }

Step 4: Run Application

Run your application with the command given below.

Java
MW_API_KEY={MW_API_KEY} java -javaagent:/PATH/TO/middleware-javaagent-{version}.jar \
    -Dotel.service.name={APM-SERVICE-NAME} \
    -Dotel.resource.attributes=project.name={APM-PROJECT-NAME} \
    -jar <YOUR_APP>.jar
Need assistance or want to learn more about Middleware? Contact us at support[at]middleware.io.