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

# Deploy Monitoring & Automation for Java with GermainUX

> GermainUX provides deep monitoring, analytics, and automation for Java applications through the GermainUX Java Agent / Code Profiler and GermainUX Engine.

Components
[`Agent`](https://docs.germainux.com/main/germainux-agent)
[`Engine`](https://docs.germainux.com/main/germain-ux-engine)

Availability
2022.1 or later

> **[Prerequisites](#prerequisites)**
>
> Confirm Java requirements

> **[Attach the Agent to the JVM](#3-attach-the-agent-to-the-jvm)**
>
> Add javaagent startup argument

> **[Deploy a GermainUX Engine](#6-deploy-a-germainux-engine)**
>
> Run checks outside the JVM

> **[Verify the Deployment](#9-verify-the-deployment)**
>
> Enable agent logging

## Overview

GermainUX provides deep monitoring, analytics, and automation for Java applications through the **GermainUX Java Agent / Code Profiler** and **GermainUX Engine**.

The Java Agent attaches to the JVM at startup using the standard Java Instrumentation API. No application code changes are required.

## Prerequisites

| Requirement | Details |
| - | - |
| GermainUX | Running and reachable from the monitored environment |
| JRE | 17 for the current Agent; 8 or 11 for the legacy Agent |
| Supported environments | Apache Tomcat, IBM WebSphere, JBoss/WildFly, standalone Java, and other JVM-based applications |
| Network | The monitored environment must be able to communicate with GermainUX |

## 1. Deploy the GermainUX Java Agent

Obtain the Java Agent files from GermainUX:

| File | Purpose |
| - | - |
| `apm-agent.jar` | Java Agent loaded by the JVM |
| `apm-agent-runtime.jar` | Runtime classes used by the Agent |
| `agent.properties` | Agent configuration template |
| `germain.java.security` | Security policy required for IBM JVM only |

Place the files in a dedicated directory, for example:

```text theme={null}
/opt/germainux/agent/
├── apm-agent.jar
├── apm-agent-runtime.jar
├── agent-myapp.properties
└── germain.java.security
```

Use absolute paths and ensure that the JVM process has read access to the files.

The Agent automatically locates `apm-agent-runtime.jar` when it is stored in the same directory as `apm-agent.jar`.

## 2. Create the Application Configuration

Copy `agent.properties` and create an application-specific configuration file:

```text theme={null}
agent-[APPLICATION_NAME].properties
```

For example:

```text theme={null}
agent-myapp.properties
```

At minimum, configure the GermainUX server:

```text theme={null}
agent.url=http://your-germainux-server:8080
```

The application name can also be explicitly defined:

```text theme={null}
agent.application=myapp
```

Setting an application name is recommended when multiple Java applications are monitored on the same host.

Additional monitoring capabilities, exclusions, sampling, privacy controls, and other options can be configured as described in **Configure Monitoring & Automation for Java**.

## 3. Attach the Agent to the JVM

Add the `-javaagent` argument to the Java application's JVM startup configuration:

```text theme={null}
-javaagent:/opt/germainux/agent/apm-agent.jar=/opt/germainux/agent/agent-myapp.properties
```

### JDK 17+

When outbound HTTP monitoring is enabled on JDK 17 or later, also add:

```text theme={null}
--add-exports java.base/sun.net.www.protocol.http=ALL-UNNAMED
```

### IBM JVM

IBM JVM requires the GermainUX security configuration:

```text theme={null}
-Djava.security.properties=/opt/germainux/agent/germain.java.security
```

JMX should also be disabled in the Agent configuration:

```text theme={null}
agent.jmx.enabled=false
```

## 4. Configure the Application Server

### Apache Tomcat

Add the Agent to `$CATALINA_HOME/bin/setenv.sh` on Linux/macOS:

```text theme={null}
CATALINA_OPTS="$CATALINA_OPTS -javaagent:/opt/germainux/agent/apm-agent.jar=/opt/germainux/agent/agent-myapp.properties"
CATALINA_OPTS="$CATALINA_OPTS --add-exports java.base/sun.net.www.protocol.http=ALL-UNNAMED"
```

On Windows:

```text theme={null}
set CATALINA_OPTS=%CATALINA_OPTS% -javaagent:C:\germainux\agent\apm-agent.jar=C:\germainux\agent\agent-myapp.properties
set CATALINA_OPTS=%CATALINA_OPTS% --add-exports java.base/sun.net.www.protocol.http=ALL-UNNAMED
```

### IBM WebSphere

In the WebSphere Admin Console, navigate to:

**Servers → Application Servers → \[Server] → Java and Process Management → Process Definition → Java Virtual Machine**

Add the following to **Generic JVM Arguments**:

```text theme={null}
-javaagent:/opt/germainux/agent/apm-agent.jar=/opt/germainux/agent/agent-myapp.properties
-Djava.security.properties=/opt/germainux/agent/germain.java.security
```

Save the configuration and restart the application server.

### JBoss / WildFly

Edit:

```text theme={null}
$JBOSS_HOME/bin/standalone.conf
```

and add:

```text theme={null}
JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/germainux/agent/apm-agent.jar=/opt/germainux/agent/agent-myapp.properties"
JAVA_OPTS="$JAVA_OPTS --add-exports java.base/sun.net.www.protocol.http=ALL-UNNAMED"
```

### Standalone Java

Add the Agent directly to the Java startup command:

```text theme={null}
java \
  -javaagent:/opt/germainux/agent/apm-agent.jar=/opt/germainux/agent/agent-myapp.properties \
  --add-exports java.base/sun.net.www.protocol.http=ALL-UNNAMED \
  -jar myapp.jar
```

## 5. Monitor Multiple Java Applications

Multiple applications on the same host can share the Agent JARs while using separate configuration files:

```text theme={null}
/opt/germainux/agent/
├── apm-agent.jar
├── apm-agent-runtime.jar
├── agent-app1.properties
└── agent-app2.properties
```

Each configuration should have a unique application name:

```text theme={null}
agent.application=app1
```

Each JVM then references its corresponding configuration file.

## 6. Deploy a GermainUX Engine

The **GermainUX Engine** complements the Java Agent by providing monitoring and automation capabilities that run independently from the monitored JVM.

Depending on the use case, the Engine can be used for:

* JVM and application health monitoring
* Scheduled monitoring
* Anomaly and SLA detection
* Alerts and notifications
* Script and program execution
* Incident or ticket creation
* Automated operational workflows
* Remediation actions

Deploy or select an Engine with network access to the monitored Java environment and the GermainUX platform.

The Agent and Engine can be used independently or together depending on the required monitoring depth and automation use case.

## 7. Select the Initial Monitoring Scope

The Java Agent supports monitoring of:

* JVM and process metrics
* Inbound and outbound HTTP transactions
* JDBC / SQL
* JMS
* Thread pools
* Connection pools

> **Show all 9**
>
> * Elasticsearch
> * CPU profiling
> * Custom Java classes, methods, and packages

Most standard application-monitoring capabilities are enabled by default. More detailed monitoring, such as Elasticsearch or custom method instrumentation, can be enabled when required.

For production deployments, start with the monitoring required for the application's critical transactions and progressively expand the scope.

See **Configure Monitoring & Automation for Java** for detailed configuration.

## 8. Review Data Privacy

Before enabling monitoring in production, review what application data may be collected.

Pay particular attention to:

* SQL statements
* HTTP session identifiers
* JMS message bodies
* Method arguments
* Method return values
* Application-specific sensitive data

GermainUX monitoring can be configured to exclude, mask, or avoid collecting sensitive information.

## 9. Verify the Deployment

Temporarily enable Agent file logging:

```text theme={null}
agent.log.type=FILE
agent.log.level=INFO
agent.log.path=/opt/germainux/agent/logs/
```

Restart the application and verify that:

* The Agent starts successfully
* The expected monitoring features are initialized
* The correct configuration file is loaded
* The Agent registers with GermainUX
* Java telemetry is received by GermainUX

If the Agent cannot temporarily reach GermainUX, the connection error is logged without preventing the Java application from starting.

Agent activity can also be inspected through JMX using VisualVM or JConsole:

```text theme={null}
com.germainsoftware.agent:type=Statistics
```

Once validated, review monitoring overhead and progressively enable additional monitoring, analytics, alerts, and automation as required.

## Get Help

> **[Contact GermainUX Support](https://docs.germainux.com/main/support.md)**
>
> The Germain Team can help you set this up.

> **Can't find what you need?**
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.