> ## Documentation Index
> Fetch the complete documentation index at: https://mw-docs.middleware.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Java

> Java APM - Setup & Installation Docs | Middleware

<span
  style={{
background: "url(https://img.shields.io/github/v/release/middleware-labs/opentelemetry-java-instrumentation) no-repeat",
width: "125px",
height: "20px",
display: "inline-block",
}}
/>

| Traces | Metrics | App Logs | Custom Logs | Profiling |
| :----: | :-----: | :------: | :---------: | :-------: |
|    ✅   |    ✅    |     ✅    |      ✅      |     ✅     |

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](https://github.com/middleware-labs/demo-apm/tree/master/java).

# Prerequisites

<Steps>
  <Step title="Infra Agent">
    Infrastructure Agent (Infra Agent). To install the Infra Agent, see our [Installation Guide](https://docs.middleware.io/docs/agent-installation/overview).
  </Step>

  <Step title="Java Version">
    `Java version 8` or above. Check your Java version with the following command:

    ```bash Shell theme={null}
    java --version
    ```
  </Step>
</Steps>

# Install

### Step 1: Download JAR File

Download the latest Middleware instrumentation JAR file from the [Github Release Page](https://github.com/middleware-labs/opentelemetry-java-instrumentation/releases).

### 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 3.

#### Docker

Add the following environment variable to your application:

```bash Shell theme={null}
MW_AGENT_SERVICE=<DOCKER_BRIDGE_GATEWAY_ADDRESS>
```

<Note> The `DOCKER_BRIDGE_GATEWAY_ADDRESS` is the IP address of the gateway between the Docker host and bridge network. This is `172.17.0.1` by default.
Learn more about Docker bridge networking [here](https://docs.docker.com/network/network-tutorial-standalone/) </Note>

#### Kubernetes

Run the following command to find the `mw-service` in Kubernetes:

#### Kubernetes

Run the following command to find the `mw-service` in Kubernetes:

```bash Shell theme={null}
kubectl get service --all-namespaces | grep mw-service
```

Add the following environment variable to your application deployment YAML file:

```bash Shell theme={null}
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 Java theme={null}
<dependency>
  <groupId>io.github.middleware-labs</groupId>
  <artifactId>agent-apm-java</artifactId>
  <version>0.0.16</version>
</dependency>
```

Run the following command to download the above dependencies:

```java Shell theme={null}
mvn install
```

Import the logger package:

```java Java theme={null}
import io.github.middlewarelabs.agentapmjava.Logger;
```

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

```java Java theme={null}
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 Java theme={null}
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 Java theme={null}
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
```

# Continuous Profiling

Continuous profiling captures real-time performance insights from your application to enable rapid identification of resource allocation, bottlenecks, and more. Navigate to the [Continuous Profiling](https://docs.middleware.io/workflow/profiling#continuous-profiling) section to learn more about using Continuous Profiling with the Java APM.

<Note> Need assistance or want to learn more about Middleware? Contact us at support\[at]middleware.io. </Note>