jHiccup
A non-intrusive instrumentation tool that logs and records JVM stalls and platform hiccups in Java applications.
What is jHiccup?
jHiccup is a lightweight instrumentation tool that detects and logs "hiccups"—unexpected pauses or stalls in Java applications caused by JVM, OS, or hardware interference. It helps developers visualize latency spikes and platform noise that degrade application responsiveness, providing data to optimize performance and stability.
Java developers, performance engineers, and SREs who need to diagnose runtime latency issues, monitor JVM stalls, or baseline system noise in production or test environments.
Unlike traditional profilers, jHiccup is non-intrusive, requires no code changes, and captures full latency distributions with minimal overhead. Its integration with HdrHistogram enables high-resolution analysis, making it ideal for continuous monitoring and pinpointing subtle platform-induced delays.
Overview
jHiccup is a non-intrusive instrumentation tool that logs and records platform "hiccups" - including the JVM stalls that often happen when Java applications are executed and/or any OS or hardware platform noise that may cause the running application to not be continuously runnable.
Use Cases
Best For
- Monitoring JVM garbage collection pauses and their impact on application latency
- Baseline measurement of OS or hardware noise affecting Java service responsiveness
- Diagnosing intermittent stalls in production Java applications without code instrumentation
- Comparing application hiccups against a control idle JVM to isolate environment noise
- Processing existing latency or pause logs (e.g., GC logs) into visualized hiccup charts
- Integrating lightweight performance monitoring into CI/CD pipelines or containerized environments
Not Ideal For
- Teams needing detailed, method-level profiling for code optimization rather than high-level latency measurement
- Environments where Java attach API is unavailable or where injecting agents into production JVMs is restricted by security policies
- Projects requiring out-of-the-box alerting and dashboarding without integrating with external monitoring systems
- Applications with very short-lived processes where starting a separate control JVM adds impractical overhead
Pros & Cons
Pros
Supports three modes—Java agent, runtime attachment, and wrapper script—allowing monitoring without code changes, as highlighted in the README's deployment examples.
Uses HdrHistogram to record full latency distributions in compressed logs, enabling detailed statistical analysis of hiccups, which is core to its design for high-fidelity measurement.
Optionally runs a control idle JVM with the -c flag to concurrently measure platform noise, helping distinguish application-specific stalls from environmental factors.
Includes jHiccupLogProcessor to convert binary logs into readable percentiles and supports input from external files like GC logs, adding versatility for post-hoc analysis.
Cons
Raw logs are binary and not human-readable, requiring separate tools like jHiccupLogProcessor or third-party visualizers for analysis, which adds steps to the workflow.
Attaching to live JVMs requires tools.jar in the classpath, as noted in the README, which isn't always default, limiting ad-hoc diagnostics in some environments.
Lacks native graphing capabilities; users must rely on external tools like HistogramLogAnalyzer or custom scripts to generate plots, making immediate insights less accessible.
Frequently Asked Questions
Related Projects
jitwatchLog analyser / visualiser for Java HotSpot JIT compiler. Inspect inlining decisions, hot methods, bytecode, and assembly. View results in the JavaFX user interface.
honest-profilerA sampling JVM profiler without the safepoint sample bias
LatencyUtilsUtilities for latency measurement and reporting
GCeasy cTool to analyze and visualize GC logs. It provides a free cloud-based upload interface
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.