1. Overview
OPENMARU APM is an APM (Application Performance Monitoring) tool that provides real-time monitoring of Java-based web applications, so failures can be prevented in advance and performance improved continuously.
Beyond real-time monitoring of Java-based web applications, OPENMARU APM applies real-time statistical analysis to provide capabilities for judging problems before they arrive.
What This Guide Does
It installs the agents. An agent is a small program that runs on the monitored server, gathers performance data, and sends it to the APM server. The APM server and console are assumed to be installed already -- building the server is covered in a separate installation guide.
There Are Two Kinds of Agent
| What it watches | Where it is installed | Does it change the application | |
|---|---|---|---|
| System agent | The server's CPU, memory, disk, and network, plus web servers and databases | One per server | No (a separate process) |
| WAS agent | The request flow, SQL, external calls, and JVM memory inside the application | One per WAS instance | No (only a startup option is added) |
Installing both is recommended. Telling whether a slow response is a shortage of server resources or a problem in the code requires data from both sides.
What You Get Once It Is Installed
- Servers and application instances appear in the console and their metrics refresh in real time
- Clicking one slow request shows where the time went
- Alerts can be configured for when a threshold is passed (covered in the event configuration guide)
How Long It Takes
10 to 20 minutes per agent. Most of it is downloading a file, unpacking it, and writing in the connection details; the WAS agent needs one WAS restart at the end. Schedule the restart in advance.
About This Installation Guide
This document is an installation guide for those who want to monitor web application servers (WAS) using OPENMARU APM.
Audience
| Audience | Description |
|---|---|
| System administrators | Responsible for installing the APM server and agents |
| DevOps engineers | Responsible for integrating APM into the CI/CD pipeline |
| Developers | Responsible for application performance analysis and optimization |
| Operations teams | Responsible for real-time monitoring and incident response |
Purpose of the Document
- Provide how to install and configure the OPENMARU APM agents
- Guide the identification of failure causes through web application monitoring
- Provide monitoring configuration for performance analysis and optimization
Key Features
Installing the agents makes the features below available in the console. Knowing what can be seen comes before deciding which agent to install where, so skim this before starting the installation. The agent needed for each feature is in parentheses.
Performance Analysis and Monitoring
Service Satisfaction Index (APDEX) -- WAS agent
It answers "is the service all right now" with a single number. Reading response time in milliseconds means arguing every time about whether 1.2 seconds is acceptable, whereas APDEX converts it into a score from 0 to 100 based on whether the user was satisfied, which makes a target such as "keep it above 90" easy to set.
That is why it is often used as the service level objective (SLO) metric in cross-department agreements and management reports. When the value drops, the T-Map below is used to find which transaction pulled it down.
Short for Application Performance Index, it is an industry-standard metric expressing user satisfaction with application performance as a single number between 0 and 100.
Grades:
- 94-100: Excellent -- nearly perfect performance
- 85-94: Good -- sound performance
- 70-85: Fair -- acceptable performance
- 50-70: Poor -- needs improvement
- 0-50: Unacceptable -- immediate action needed
Response time bands:
- Satisfied: T or less -- the user stays focused and is satisfied with the performance
- Tolerating: T to 4T -- the user finds it hard to stay focused and is not satisfied with the performance
- Frustrated: over 4T -- the user gives up on the service; the service is unacceptable
The APDEX formula: (satisfied requests + (tolerating requests ÷ 2)) ÷ total requests × 100
T (the threshold) can be set in the WAS agent configuration file (the default is 3.0).
T-Map (Transaction Distribution) -- WAS agent
It finds the slow requests the average hides. It is a screen that plots every transaction as a point of time (horizontal) against response time (vertical).
Looking only at the average response time ends at "0.4 seconds, fine", but in the T-Map the few points sitting high up are visible as they are. Clicking one of those points opens how that one request was handled -- which method spent how long, which SQL ran and how many times, and how long an external system was waited on.
The shape of the scatter suggests the cause. Points bunched vertically at a particular time mean something happened then (a batch, GC, a deployment); one screen constantly sitting high up means the problem is that screen.
Real-Time Forecast -- WAS and system agents
It warns before a threshold is passed. It extends the recent trend to work out "at this rate, the threshold is reached in this many minutes".
It is useful in situations that are hard to reverse once they blow up, such as a slow memory leak. A threshold alert comes after the problem has already happened; a forecast alert gives time to act.
The forecast targets are CPU utilization, memory usage, and delayed transactions.
Failure Analysis Tools
WAS Failure Analysis -- WAS agent
This is the tool that answers "the WAS stopped and I do not know why". Instead of connecting to
the server when a failure occurs, taking a jstack, and reading it by eye, you take it straight from
the console and see the analysis.
| Tool | When to use it |
|---|---|
| Thread dump collection and analysis | When there is no response or it is slow -- which thread is stuck where, and whether it is a deadlock |
| Heap dump analysis | When memory is short -- what is holding the memory |
| Running SQL tracing | When the database is suspected -- what query is running right now |
| Transaction profiling | When a particular request is slow -- which part inside it takes long |
| Method execution statistics | When deciding what code to fix -- the call count and cumulative time |
In a failure it can be hard even to connect to the server. Installing this in advance secures the material with only the console at that moment.
Anomaly Monitoring -- WAS and system agents
This is monitoring without having to set thresholds. Setting a threshold by hand for each metric requires knowing the service's character and every time of day, whereas this feature learns the usual distribution and tells you when it deviates.
For a service that is quiet at dawn and busy during the day, one fixed threshold cannot fit both. Looking at whether it differs from usual gives a judgement regardless of the hour.
What it detects is a sudden rise in average response time, a rising error rate, unusual CPU and memory usage patterns, and traffic spikes and drops.
System and Infrastructure Monitoring
OS Resource Monitoring -- system agent
It separates a slow application from an under-resourced server. WAS metrics alone tell you the response got slower but not whether the cause is code or resources. Overlaying the server resources at the same moment separates the two.
| Monitored item | Metrics collected | What it decides |
|---|---|---|
| CPU | Utilization, per-core usage, system/user time | Is computation piled up? Is it kernel side or user code? |
| Memory | Usage, available memory, swap usage | Is memory short? Has swapping made it slow? |
| Disk | Utilization, I/O performance, read/write speed | Are log and data writes the bottleneck? Is capacity about to fill? |
| Network | Traffic, packet count, error rate, socket state | Is bandwidth short? Are sockets piling up? |
| Load average | The 1-, 5-, and 15-minute average load | Is it a spike now, or has it been like this? |
Why 1, 5, and 15 minutes are read together -- if only the 1-minute is high and the 15-minute is low, it just piled up; if all three are high, the load has been on for a while. The former is worth waiting out; the latter calls for more capacity.
Web Server Monitoring -- system agent (plugin)
It watches the stretch between the user and the WAS. When nothing reached the WAS but users say it is slow, only web server metrics show what happened in between.
| Metric | What it tells you |
|---|---|
| Traffic | How much is actually coming in |
| RPS (requests per second) | Has the load risen, and by how many times against usual |
| Active connections | Are connections piling up unprocessed |
| Response code distribution | 2xx, 3xx, 4xx, 5xx -- did the error come from the web server or the WAS |
If 5xx is caught at the web server while the WAS transaction count is unchanged, the requests never reached the WAS. Look at the connection count and worker state.
Events and Alerts
Statistics-Based Event Processing
The aim is to avoid the state where there are so many alerts nobody reads them. Alerting every time a value passes a threshold sends an alert on a momentary spike too, and once those pile up the important ones get missed.
So the judgement is made not on the instantaneous value but on statistics over a window (average and standard deviation). A brief spike is buried in the average and only a genuinely worsened state remains.
| Approach | What it does |
|---|---|
| Statistics-based thresholds | Judges on average and standard deviation -- filters out momentary spikes |
| Event filtering | Bundles repeated alerts from the same cause |
| Alert channels | Email, SMS, webhook, Slack, MS Teams |
How to configure each channel is covered in the OPENMARU APM Event Configuration Guide.
User Interface
HTML5-Based Web Console
There is no program to install separately. A browser is all it takes, so during a failure it can be checked from a mobile phone away from the office.
| Characteristic | Description |
|---|---|
| Responsive design | The layout adapts to desktop, tablet, and phone screens |
| Real-time dashboard | Refreshes over WebSocket whenever a value changes -- no reload needed |
| Dashboard composition | Pick the charts you look at often and build your own screen |
| Dark mode | A dark theme for viewing in dark places, such as a night operations room |
System Architecture
Architecture Overview
Data flows in one direction. The agents installed on the monitored servers push the values they collect up to the APM server; the APM server aggregates them into storage; and the operator reads them through the web console. The APM server never initiates a connection to a monitored server -- the firewall only has to open the outbound direction from the monitored server to the APM server.
Because of this structure, installation is done per monitored server too. Watching 100 servers means installing the agent 100 times; it is not a matter of registering a server list on the APM server.
Components
Five things appear, but only the two agents are installed by hand. The other three (the APM server, the storage, and the web console) come up together when the APM server is installed.
| Component | Where it is | Covered in this guide |
|---|---|---|
| WAS agent | On every WAS to be monitored | Covered -- chapter 3 and chapter 4 |
| System agent | On every server to be monitored | Covered -- chapter 2 |
| APM server, data storage, web console | Gathered in one place | No -- there is a separate installation guide |
WAS Agent -- What Happens inside the Application
It goes inside the Java application and follows the path one request took to be handled. It adds
one -javaagent line to the WAS startup options, so the application source is not changed.
| What can be seen | What question it answers |
|---|---|
| Transaction execution time and profile | Which screen is slow, and which part inside it takes long |
| SQL query execution | Is the database the cause of the slowness, and which query |
| External calls (HTTP, REST API) | Is it slow because it is waiting on another system |
| JVM memory (heap, non-heap) | Is memory leaking, and is it about to run short |
| Thread state | Where is it stuck, and is it a deadlock |
| GC (garbage collection) statistics | Is the pause down to GC, and how often and how long |
Supported WAS -- Apache Tomcat, SpringBoot, JBoss EAP / WildFly, WebLogic, JEUS, Jetty. The file the option goes in differs by WAS. Chapter 4 covers which file and where, per kind.
System Agent -- The Server and the Products Running on It
It is a separate process running one per server. Unlike the WAS agent it does not touch the application, so it is also installed on non-Java servers (web servers, database servers).
By default it watches only operating system resources -- CPU, memory, disk, network, processes, and file system usage. To see the products running on the same server as well, turn on the relevant plugin.
| Plugin | What it makes visible |
|---|---|
| Apache, NGINX, HAProxy | Request count, response code distribution, worker and connection state |
| MySQL, CUBRID | Session count, slow queries, database and broker state |
| Docker, CRI-O, containerd | CPU, memory, and network per container |
Only what is turned on runs. Leaving a plugin on for something you do not use keeps asking a product that is not there for its state, so collection errors pile up in the log. Each plugin needs something prepared on the target product -- a status page for a web server, a read-only account for a database, and read permission on the runtime socket for containers. The details are in chapter 2.
APM Server, Data Storage, and Web Console
This is the side that receives the values the agents send, aggregates them, judges events against thresholds, and accumulates them in storage. Communication is WebSocket (port 80 by default) and the agent initiates the connection.
Storage keeps time-series data and event history separately, and the retention period is set in the configuration. The web console reads that data over HTTP(S) and presents it as dashboards, transaction analysis (T-Map), statistics, event history, and configuration screens. To take the same data into a program, use the REST API -- covered in the OPENMARU APM API Integration Guide.
These three are out of scope for this guide. It explains only agent installation, on the assumption that the APM server is already installed and its address is known.
Network Architecture
Supported Environments
Supported Environments for Installing the APM Server
On RHEL and CentOS operating systems, the OPENMARU APM Server can be installed automatically with the OPENMARU Installer.
Supported Operating Systems
| Operating system | Version | Architecture |
|---|---|---|
| Red Hat Enterprise Linux (RHEL) | 7.x / 8.x / 9.x | x86_64 |
| CentOS | 7.x / 8.x | x86_64 |
| Rocky Linux | 8.x / 9.x | x86_64 |
| AlmaLinux | 8.x / 9.x | x86_64 |
- RHEL: for enterprise environments and where long-term support is needed
- Rocky Linux / AlmaLinux: a CentOS replacement, with community support
System Requirements
Minimum / Recommended Specifications
| Item | Minimum | Recommended | Note |
|---|---|---|---|
| CPU | 8 cores | 16 cores | Virtual machine cores |
| Memory | 16 GB | 32 GB | Keeping spare memory is recommended |
| Disk | 500 GB | 1 TB or more | SSD recommended |
| Network | 1 Gbps | 10 Gbps | For large environments |
The system specification is strongly affected by the following:
- The number of monitored servers: more servers need more resources
- The number of WAS instances: each instance increases the data collected
- Transaction throughput: higher TPS needs more CPU and memory
- The data retention period: a longer period needs more disk
Sizing examples:
- Small (10 servers, 20 instances): 8 cores, 16 GB, 500 GB
- Medium (50 servers, 100 instances): 16 cores, 32 GB, 1 TB
- Large (100 or more servers, 300 or more instances): 32 cores, 64 GB, 2 TB or more
Network Requirements
| Item | Requirement |
|---|---|
| Port | 80 (HTTP/WebSocket) |
| Firewall | Communication in the agent → server direction has to be allowed |
Supported Environments for Installing the Agents
Supported Environments for the WAS Agent
| WAS | Version | JDK version |
|---|---|---|
| Apache Tomcat | 7.x / 8.x / 9.x / 10.x / 11.x | JDK 7, 8, 11, 17, 21, 25 |
| JBoss EAP | 6.x / 7.x / 8.x | JDK 8, 11, 17 |
| WildFly | 10.x to 30.x | JDK 8, 11, 17, 21 |
| WebLogic | 12c / 14c | JDK 8, 11 |
| WebSphere | 8.5 / 9.x | JDK 8, 11 |
| Jetty | 9.x / 10.x / 11.x | JDK 8, 11, 17, 21 |
- JDK 8: stable support on every WAS
- JDK 11: the enterprise standard, with long-term support (LTS)
- JDK 17: the latest LTS, with performance improvements
- JDK 21: the latest LTS, supporting the newest features
- JDK 25: the latest LTS. The agent has been updated to read and write the newest class file format
-noverify or -Xverify:noneOlder documents and configuration examples advised adding these options to avoid class loading errors. They are not needed with the current agent, and adding them can make the JVM terminate abnormally in production. Remove them from the startup script if they are still there -- for the details, see 6. Troubleshooting Guide.
Supported Environments for the System Agent
| Operating system | Version | Architecture |
|---|---|---|
| Linux | RHEL/CentOS 6.x to 9.x | x86_64 |
| Windows | Windows Server 2012 R2 / 2016 / 2019 / 2022 | x64 |
| Windows | Windows 10 / 11 | x64 |
| AIX | AIX 7.x | Power (ppc64) |
| HP-UX | HP-UX 11i v3 (11.31) | Itanium (ia64) |
| Solaris | Solaris 10 / 11 | SPARC, x86_64 |
- Linux: most major distributions are supported (RHEL, CentOS, AlmaLinux, RockyLinux, and others)
- AIX: the Unix specific to IBM Power systems
- HP-UX: the Unix specific to HP Integrity servers
- Solaris: supports Oracle SPARC and x86 systems
Supported web servers:
- Apache HTTP Server 2.2 / 2.4
- Nginx 1.x
How to Install the Agents
OPENMARU APM offers two ways to install the agents:
1. Automatic Installation with the Installer (Recommended)
Using the provisioning feature of the OPENMARU Installer installs and configures the agent automatically.
Advantages:
- Fast installation: finished within minutes
- Automatic configuration: the configuration file is generated automatically
- Fewer errors: manual configuration mistakes are minimized
The installation process:
1. Access the APM Server UI
2. Add agent → download the automatic installation script
3. Run the script on the target server
4. The agent is installed and configured automatically
- The target server has to be able to reach the APM server -- the agent files are downloaded from the APM server, so external Internet access is not required. It is used in closed networks too
- You have to have permission to run the script
2. Manual Installation
Where provisioning cannot be used or has been ruled out, install by hand following the steps in the next chapters.
When to choose manual installation:
- The target server cannot reach the APM server -- when the networks are separated and the files have to be moved across
- Automatic script execution is blocked by security policy
- The installation location or account has to match site rules -- when the default paths of automatic installation cannot be used
- Attaching to a WAS already in production -- when the startup script has already been modified and you want to see exactly which lines change
The manual installation steps:
1. Download the agent package
2. Unpack it on the target server
3. Edit the configuration file (agent.conf)
4. Edit the WAS startup options (-javaagent)
5. Restart the WAS
| Situation | Recommended method |
|---|---|
| A newly built server | Automatic installation -- the fastest |
| Attaching to a WAS already in production | Manual installation -- add it while checking the existing startup script |
| Kubernetes / OpenShift | Automatic injection by the Operator -- no image changes, and upgrades are handled for you |
| Networks separated so the APM server is unreachable | Manual installation -- move the files and install |
Where to Install -- Choosing a Chapter
It is the same agent, but the steps differ by where it is attached. Find your environment below and go to that chapter.
| Where to attach it | How | Where to look |
|---|---|---|
| The server's OS and web server | Install the system agent | Chapter 2 |
| A WAS installed directly on the server | -javaagent in the JVM options | Chapter 3 and chapter 4 |
| A container image | Bake it into the image or build with S2I | Chapter 5 |
| A Kubernetes / OpenShift workload | Automatic injection just by adding a label | OPENMARU APM Operator Guide |
In a Kubernetes environment, consider the Operator's automatic injection first. The image does not have to be changed and the Operator handles upgrades too. The method in chapter 5 is for when the Operator cannot be used or the image has to be managed directly.
Next Steps
For the details of agent installation, see the following chapters:
- Installing the System Agent: installing the agent that monitors the system and web servers
- Installing the WAS Agent: installing the agent that monitors a Java WAS
- Agent Configuration per WAS Type: how to configure each WAS
- Installing on Containers and Kubernetes: image builds, S2I, and pod environment variables
- Troubleshooting: resolving problems that arise during installation