Getting Started with the JAMon API: A Beginner’s GuideJAMon (Java Application Monitor) is a lightweight, open-source library that helps developers measure and monitor performance metrics inside Java applications. It provides simple, in-process monitoring of method execution times, hit counts, errors, and custom metrics, and can output data to logs, web pages, or external systems. This guide walks you through the basics of installing JAMon, instrumenting code, interpreting metrics, and integrating with common tools.
What JAMon Does and When to Use It
JAMon is useful when you need low-overhead, runtime visibility into how often code paths are executed and how long they take. Typical uses:
- Spotting slow methods or database calls
- Tracking request rates and error counts
- Comparing performance across environments (dev/stage/prod)
- Quick diagnostics without a full APM product
JAMon is best for process-local monitoring and lightweight instrumentation. If you need distributed tracing, transaction sampling, or deep profiling across services, a dedicated APM (Application Performance Monitoring) system might be more appropriate.
Key Concepts
- MONITORS: JAMon exposes monitors identified by labels (strings). Each monitor collects metrics such as total hits, total time, average time, min/max, and active counts.
- START/STOP: Timed measurements are created by calling start() and stop() around a code block, or by using the convenience MonitorFactory methods.
- REGISTRY: Monitors are held in an internal registry and can be queried or exported.
- TYPES: JAMon supports timers, counters, and other simple aggregations.
Adding JAMon to Your Project
Maven (example):
<dependency> <groupId>com.jamonapi</groupId> <artifactId>jamon</artifactId> <version>2.81</version> </dependency> Gradle (example):
implementation 'com.jamonapi:jamon:2.81' Check the latest version on the project site or Maven Central.
Basic Instrumentation
The simplest way to time a block of code is:
import com.jamonapi.Monitor; import com.jamonapi.MonitorFactory; Monitor monitor = MonitorFactory.getMonitor("myMethod", "category"); monitor.start(); try { // code to time } finally { monitor.stop(); } Or using the convenience method:
MonitorFactory.start("myMethod","category"); // code MonitorFactory.stop("myMethod","category"); For short-lived operations you can use the MonitorFactory.start/stop pair directly; for nested or recursive calls prefer keeping the Monitor instance.
Measuring Counters and Errors
Increment a counter-like monitor by simply starting and stopping without timing a block:
Monitor counter = MonitorFactory.getMonitor("cache.hit", "cache"); counter.increment(); To record exceptions or errors, you can increment an error monitor when catching failures:
try { // risky operation } catch (Exception e) { MonitorFactory.getMonitor("db.errors","database").increment(); throw e; } Retrieving and Displaying Metrics
Pull monitors from the MonitorFactory and render their statistics:
Collection<Monitor> monitors = MonitorFactory.getMonitors(); for (Monitor m : monitors) { System.out.println(m.getName() + ": hits=" + m.getHits() + ", avg=" + m.getLastValue() + ", total=" + m.getTotal()); } JAMon also includes built-in servlets and JSP pages (if using a web app) that can display formatted reports and charts.
Configuration and Output Options
- Log Output: JAMon can be configured to periodically log summaries to your logging framework.
- Servlet UI: Add the JAMon servlet to see a live web dashboard of monitors.
- CSV/Custom Export: Export monitor data to CSV or push to another monitoring system via custom code.
Configuration is typically done via properties files or programmatic initialization.
Best Practices
- Use clear, hierarchical monitor names (e.g., “service.method”, “db.query.selectUser”) to group metrics.
- Avoid extremely high-cardinality monitor names (per-user or per-request-id) — they bloat the registry.
- Instrument key hot paths rather than everything; start with service entry points, database calls, and expensive loops.
- Ensure start/stop pairs are always in try/finally to avoid leaked active counts.
- Use environment-specific enablement (e.g., enable detailed monitors in staging but sample in production) to control overhead.
Example: Instrumenting a DAO Method
public User findUserById(long id) { Monitor monitor = MonitorFactory.getMonitor("dao.findUserById","dao"); monitor.start(); try { // execute SQL and map to User } catch (SQLException e) { MonitorFactory.getMonitor("dao.sql.errors","dao").increment(); throw new DataAccessException(e); } finally { monitor.stop(); } } This records time spent, hit counts, and allows error counting separately.
Integrating with External Systems
To push JAMon metrics to external systems:
- Poll the MonitorFactory periodically and convert metrics to your required format (Prometheus, InfluxDB, Graphite).
- Use JAMon’s CSV or text export capabilities and ship that data with your log forwarder.
- Write a small adapter that maps JAMon monitors to your APM or metrics SDK.
Example (pseudo-code) for Prometheus push:
for (Monitor m : MonitorFactory.getMonitors()) { gauge.labels(m.getName()).set(m.getLastValue()); counter.labels(m.getName()).inc(m.getHits()); // adapt as needed } Troubleshooting
- Missing metrics: Ensure MonitorFactory is initialized and that code paths actually execute the start/stop calls.
- Stuck active count: Check for code paths that call start() without stop() — wrap stops in finally blocks.
- Too many monitors: Review naming strategy to reduce cardinality and reuse monitors where possible.
Alternatives and When to Upgrade
If you need distributed tracing, high-cardinality labels, or advanced visualization, consider:
- OpenTelemetry (for distributed traces + metrics)
- Prometheus + client libraries (metrics scraping)
- Commercial APMs (Datadog, New Relic, AppDynamics)
JAMon remains useful for simple, fast, in-process monitoring when you want minimal dependencies and straightforward metrics.
Summary
JAMon is a practical tool for quickly adding timing, counting, and basic performance visibility to Java applications. Start by adding the dependency, instrumenting key methods with MonitorFactory.start/stop or Monitor objects, expose metrics via logs or a servlet, and integrate exports for longer-term storage. Keep monitor naming disciplined and ensure start/stop pairs are safe to avoid skewed results.
If you want, I can provide a sample Maven project, a servlet configuration example, or a small adapter to export JAMon metrics to Prometheus.
Leave a Reply