1. Overview
Aspectow AppMon is a lightweight, real-time monitoring solution for applications based on the Aspectran framework. It is designed to minimize the impact on application performance while allowing real-time observation of various events, logs, and system metrics that occur during operation through a web UI.
It can be easily integrated into Aspectran applications without complex setup, helping developers and operators to intuitively understand the internal workings of the application and quickly diagnose problems.
2. Key Features
- Real-time Monitoring: Streams data generated from the server in real-time to the UI using WebSocket or Long-Polling methods.
- Lightweight and Easy Integration: Can be simply registered as an Aspectran bean in the target application, minimizing performance degradation by using minimal resources.
- Dynamic Monitoring: Utilizes Aspectran’s AOP features to dynamically track the execution of specific transactions (Activity) and measure performance without code changes.
- Support for Various Data Sources:
- Events: Tracks and counts major application events such as HTTP request processing and session creation/destruction.
- Metrics: Collects various system metrics like JVM heap memory usage, Undertow thread pool status, and HikariCP connection pool status.
- Logs: Tails specified log files in real-time and displays them on the UI.
- Data Persistence: Periodically saves key event count data to an embedded H2 database, ensuring that statistics are maintained even after an application restart.
- Flexible Configuration: Allows flexible definition of which instances and what data to monitor through an APON (Aspectran Object Notation) based configuration file.
3. Core Architecture
Aspectow AppMon consists of the following main components:
- AppMonManager: The core engine that manages the overall lifecycle and configuration of AppMon.
- Exporter: Responsible for collecting data from specific data sources (logs, metrics, events).
- Reader: Implements the specific method for how the
Exporter
collects data (e.g., querying JVM metrics via JMX, reading log files from the filesystem).
- Reader: Implements the specific method for how the
- PersistManager: Handles the persistence of collected data (mainly event counts) to the database.
- CounterPersistSchedule: Periodically executed by a scheduler to save counter data to the DB.
- ExportService: Responsible for communication with the client (web UI), transmitting collected data via WebSocket or Polling.
- Activity (Front/Backend): Acts as a controller that handles HTTP requests from the web UI or external agents.
4. Getting Started (Quick Guide)
- Add Dependency: Add the
aspectow-appmon
dependency to yourpom.xml
. - Register Factory Bean: Register
AppMonManagerFactoryBean
as a component in your Aspectran configuration file. This factory bean activates all of AppMon’s features. - Create Configuration File: Create an
appmon-config.apon
file to define in detail the instances, events, metrics, and logs to be monitored. - Run Application: When you run your Aspectran application, AppMon will start up with it.
- Access Web UI: Access the provided URL to start real-time monitoring.
5. Data Persistence Structure
Aspectow AppMon saves event counting data to a database to maintain statistics. By default, it uses an embedded H2 database, and the schema is as follows:
appmon_event_count
- Stores event count data aggregated by minute, hour, day, month, and year.
- The data in this table is used to draw statistical charts.
- Key Columns:
domain
,instance
,event
: Identifies which event is being counted.datetime
: The aggregated time unit (e.g.,yyyyMMddHHmm
).total
: The cumulative total count.delta
: The count that occurred during that time unit.error
: The error count that occurred during that time unit.
appmon_event_count_last
- Stores the last count state for each event.
- When the application restarts, it reads the data from this table to restore the counters, ensuring that statistics are not lost.
- It has a similar structure to the
appmon_event_count
table but has areg_dt
column indicating the last registration time instead ofdatetime
.
6. How to Configure AppMon
All of AppMon’s behavior is configured through the appmon-config.apon
file. This file consists of several sections that define what to monitor and how.
Main Configuration Sections
counterPersistInterval
: Sets the interval, in minutes, for saving aggregated event counter data to the database. If not set, it defaults to 5 minutes.pollingConfig
: Configures the behavior when a client connects via Long-Polling (pollingInterval
,sessionTimeout
, etc.).domain
: Defines and logically groups the server instances to be monitored. Eachdomain
points to a single monitoring target server and contains the endpoint information for connecting to it.instance
: Defines the individual application or component unit to be monitored. Most of the detailed settings are located under this section.
instance
Detailed Settings
Under the instance
section, you can configure event
, metric
, and log
to collect the desired data.
event
Settings:name
: Specifies a predefined event type, such asactivity
orsession
.target
: Specifies the target to be monitored.- For
activity
: The name of Aspectran’s ActivityContext (e.g.,jpetstore
). - For
session
: The servlet context path (e.g.,tow.server/jpetstore
).
- For
parameters
: Sets a Pointcut foractivity
events to include or exclude specific request paths.
metric
Settings:reader
: Specifies the full class name of theMetricReader
implementation that will collect the metrics. This allows for easy addition of custom metric collectors.- Example:
com.aspectran.appmon.exporter.metric.jvm.HeapMemoryUsageReader
- Example:
parameters
: Sets parameters to be passed to thereader
class (e.g.,poolName
for HikariCP).
log
Settings:file
: Specifies the path to the log file to be tailed.lastLines
: Specifies the number of last lines of the log to display on initial UI access.
Configuration Example (appmon-config.apon
)
Here is an example configuration that defines two servers (backend1
, backend2
) as monitoring targets and details the monitoring of a jpetstore
instance among them.
# DB persistence interval (in minutes), 0 to disable
counterPersistInterval: 10
# Define monitored server targets
domain: {
name: backend1
title: Server-1
endpoint: {
mode: auto
url: /appmon/backend1
}
}
domain: {
name: backend2
title: Server-2
endpoint: {
mode: auto
url: /appmon/backend2
}
}
# Define monitoring instance details
instance: {
name: jpetstore
title: JPetStore
event: {
name: activity
target: jpetstore
parameters: {
+: /**
}
}
event: {
name: session
target: tow.server/jpetstore
}
metric: {
name: cp-jpetstore
title: CP-jpetstore
description: Shows the JDBC connection pool usage status
reader: com.aspectran.appmon.exporter.metric.jdbc.HikariPoolMBeanReader
parameters: {
poolName: jpetstore
}
sampleInterval: 50
exportInterval: 900
}
log: {
name: app
title: JPetStore App
file: /logs/jpetstore.log
lastLines: 1000
sampleInterval: 300
}
}
7. Conclusion
Aspectow AppMon is a powerful tool that greatly enhances the transparency and observability of Aspectran applications. It can be an optimal choice when a complex APM solution is burdensome, and you want to look into the internal state of your application in real-time with minimal setup to detect performance issues early.