A miniature library for measuring JVM and OS hiccups that affect your program.
It is inspired by Gil Tene's jHiccup. In
fact, this is a maximally trimmed jHiccup with the implementation taken straight
out of the ancestor library.
jHiccup is a great tool that focuses on very precise on-demand measurement of
platform-induced lags. It uses
HdrHistogram to record
high-fidelity measurement data which can later be queried for real percentile
values on arbitrary time spans. However, jHiccup's API is not convenient for
ongoing always-on measuring and reporting.
jvm-hiccup-meter contains the exact measuring code from jHiccup and exposes it
via the most primitive callback API. This gives developers the utmost
flexibility in consuming the measurements, be it writing them to a monitoring
solution (Metrics, StatsD, etc.) or aggregating in any other way.
The idea behind jHiccup (and, as a consequence, this library) is trivially
brilliant: if an idle thread that does nothing but sleeping is denied the CPU
time by the system, then the real worker threads are likely to observe the
similar effect. jvm-hiccup-meter starts a thread that sleeps for a defined
interval (by default, 10 milliseconds) and measures how much of actual time has
passed. The difference between the desired and actual sleep time becomes the
length of the system "hiccup" for this cycle.
Of course, you can't expect
Thread.sleep(10) to wake up strictly in 10
milliseconds even under ideal conditions when no hiccups are happening. But
obsessing about small fluctuations is not the point, the point is to discover
long pauses of hundreds of milliseconds or even seconds. Those can be caused by
stop-the-world GC phases, stolen CPU cycles in virtualized environments,
unpredicted hardware effects, and other application-independent reasons.
jvm-hiccup-meter is non-invasive — an extra thread that does a few arithmetic
operations and goes to sleep a hundred times per second should not bring a
noticeable overhead to your application.
(require '[clj-hiccup-meter.core :as hmeter])
(def hm (hmeter/start-hiccup-meter callback-fn :resolution-ms 10))
;; To stop the meter thread
The only function
start-hiccup-meter accepts an unary function as an argument
and starts the measuring thread. On each measurement iteration, the callback
will be called with the measured delay in nanoseconds. Optional resolution can
be passed to change the default sleep period.
start-hiccup-meter returns a
nullary function calling which stops the thread.
Here's an example of combining jvm-hiccup-meter with Dropwizard
(def hist (Histogram. (SlidingTimeWindowArrayReservoir. 10 TimeUnit/SECONDS)))
(def hm (hmeter/start-hiccup-meter #(.update ^Histogram hist %)))
;; Now, you can forward this histogram to Graphite, or check the values
;; manually, e.g:
(.getMax (.getSnapshot hist))
jHiccup was written by Gil Tene of Azul Systems, and released to the public
domain, as explained at http://creativecommons.org/publicdomain/zero/1.0/
jvm-hiccup-meter is distributed under the Eclipse Public License. See
Copyright 2018 Alexander Yakushev