metrics Documentation

File: README.md Copy Chapter

Metrics

📈 Capturing JVM- and application-level metrics. So you know what's going on.

For more information, please see the documentation

Versions Copy Section

Future development Copy Section

New not-backward compatible features (for example, support for tags) will be implemented in a 5.x.x release. The release will have new Maven coordinates, a new package name and a backwards-incompatible API.

Source code for 5.x.x resides in the release/5.0.x branch.

License Copy Chapter

Copyright (c) 2010-2013 Coda Hale, Yammer.com, 2014-2021 Dropwizard Team

Published under Apache Software License 2.0, see LICENSE

File: docs/source/about/contributors.rst Copy Chapter

.. _about-contributors:

############
Contributors
############

Many, many thanks to:

• Aaron Stockmeister <https://github.com/stockmaj>_
• Alan Woodward <https://github.com/romseygeek>_
• Aleksandr Podkutin <https://github.com/apodkutin>_
• Alex Lambert <https://github.com/alambert>_
• Alexander Eyers-Taylor <https://github.com/alexet>_
• Alexander Reelsen <https://github.com/spinscale>_
• Alexey Nezhdanov <https://github.com/snakeru>_
• Andreas Gebhardt <https://github.com/agebhar1>_
• Andrew Fitzgerald <https://github.com/fitzoh>_
• Andrey Rodionov <https://github.com/dernasherbrezon>_
• Anil V <https://github.com/avaitla>_
• Anthony Dahanne <https://github.com/anthonydahanne>_
• Antonin Stefanutti <https://github.com/astefanutti>_
• apirom9 <https://github.com/apirom9>_
• Artem Prigoda <https://github.com/arteam>_
• Ashley Sole <https://github.com/ashisamazin>_
• Bart Prokop <https://github.com/bartprokop>_
• Bartosz Krasiński <https://github.com/krasinski>_
• Basil James Whitehouse III <https://github.com/basil3whitehouse>_
• Ben Tatham <https://github.com/bentatham>_
• Benjamin Gehrels <https://github.com/BGehrels>_
• Bohdan Storozhuk <https://github.com/storozhukBM>_
• Brenden Matthews <https://github.com/brndnmtthws>_
• Brian <https://github.com/codelotus>_
• Brian Roberts <https://github.com/flicken>_
• Bruce Mitchener <https://github.com/waywardmonkeys>_
• C. Scott Andreas <https://github.com/cscotta>_
• Carter Kozak <https://github.com/carterkozak>_
• cburroughs <https://github.com/cburroughs>_
• ceetav <https://github.com/ceetav>_
• Charles Care <https://github.com/ccare>_
• Chris Birchall <https://github.com/cb372>_
• Chris Rohr <https://github.com/chrisrohr>_
• Christopher Gray <https://github.com/chrisgray>_
• Christopher Swenson <https://github.com/swenson>_
• ciamac <https://github.com/ciamac>_
• Coda Hale <https://github.com/codahale>_
• Collin Van Dyck <https://github.com/collinvandyck>_
• Corentin Chary <https://github.com/iksaif>_
• Dag Liodden <https://github.com/daggerrz>_
• Dale Wijnand <https://github.com/dwijnand>_
• Dan Brown <https://github.com/jdanbrown>_
• Dan Everton <https://github.com/deverton>_
• Dan Revel <https://github.com/nopolabs>_
• Daniel James <https://github.com/dwhjames>_
• DarkJenum <https://github.com/DarkJenum>_
• David Hatanian <https://github.com/dhatanian>_
• David M. Karr <https://github.com/davidmichaelkarr>_
• David Pursehouse <https://github.com/dpursehouse>_
• David Schlosnagle <https://github.com/schlosna>_
• David Sutherland <https://github.com/djsutho>_
• Denny Abraham Cheriyan <https://github.com/dennyac>_
• Diwaker Gupta <https://github.com/diwakergupta>_
• Drew Stephens <https://github.com/dinomite>_
• Eduard Martinescu <https://github.com/Arvoreen>_
• Edwin Shin <https://github.com/eddies>_
• Erik van Oosten <https://github.com/erikvanoosten>_
• Erlend Hamnaberg <https://github.com/hamnis>_
• Evan Jones <https://github.com/evanj>_
• Fabien Renaud <https://github.com/fabienrenaud>_
• Fabrizio Cannizzo <https://github.com/smartrics>_
• Fokko Driesprong <https://github.com/Fokko>_
• François Beausoleil <https://github.com/francois>_
• Fred Deschenes <https://github.com/FredDeschenes>_
• g-fresh <https://github.com/g-fresh>_
• Gabor Arki <https://github.com/arkigabor>_
• George Spalding <https://github.com/georgespalding>_
• Gerolf Seitz <https://github.com/gseitz>_
• gilbode <https://github.com/gilbode>_
• goraxe <https://github.com/goraxe>_
• Greg Bowyer <https://github.com/GregBowyer>_
• Gregory Haase <https://github.com/ghaase>_
• Guillermo Calvo <https://github.com/guillermocalvo>_
• Gunnar Ahlberg <https://github.com/gunnarahlberg>_
• Henri Tremblay <https://github.com/henri-tremblay>_
• Hervé Boutemy <https://github.com/hboutemy>_
• Himangi Saraogi <https://github.com/hsaraogi>_
• ho3rexqj <https://github.com/ho3rexqj>_
• Hussein Elsayed <https://github.com/husseincoder>_
• Ian Strachan <https://github.com/ianestrachan>_
• Istvan Meszaros <https://github.com/IstvanM>_
• Ivan Dyedov <https://github.com/idyedov>_
• Jackson Davis <https://github.com/jcdavis>_
• James Burkhart <https://github.com/fourk>_
• James Casey <https://github.com/jamesc>_
• Jan-Helge Bergesen <https://github.com/jhberges>_
• Janne Sinivirta <https://github.com/vertti>_
• Jason A. Beranek <https://github.com/jasonberanek>_
• Jason Slagle <https://github.com/jmslagle>_
• Jason Whitlark <https://github.com/jwhitlark>_
• Jeff Hodges <https://github.com/jmhodges>_
• Jeff Klukas <https://github.com/jklukas>_
• Jeff Wartes <https://github.com/randomstatistic>_
• Jens Schauder <https://github.com/schauder>_
• Jesper Blomquist <https://github.com/jebl01>_
• Jesse Eichar <https://github.com/jesseeichar>_
• jkytomaki <https://github.com/jkytomaki>_
• Jochen Schalanda <https://github.com/joschi>_
• Joe Ellis <https://github.com/ellisjoe>_
• Joel Takvorian <https://github.com/jotak>_
• John Karp <https://github.com/john-karp>_
• John Wang <https://github.com/javasoze>_
• John Watson <https://github.com/jkwatson>_
• John-John Tedro <https://github.com/udoprog>_
• Jonathan Haber <https://github.com/jhaber>_
• Jordan Focht <https://github.com/jfocht>_
• Juha Syrjälä <https://github.com/jsyrjala>_
• Julio Lopez <https://github.com/julio-maginatics>_
• Justin Plock <https://github.com/jplock>_
• Jörg Fischer <https://github.com/g-fresh>_
• Kasa <https://github.com/raskasa>_
• KaseiFR <https://github.com/KaseiFR>_
• Keir Lawson <https://github.com/keirlawson>_
• Kevin Clark <https://github.com/kevinclark>_
• Kevin Herron <https://github.com/kevinherron>_
• Kevin Menard <https://github.com/nirvdrum>_
• Kevin Yeh <https://github.com/kyeah>_
• keze <https://github.com/keze>_
• konnik <https://github.com/konnik>_
• krasinski <https://github.com/krasinski>_
• Larry Shatzer, Jr. <https://github.com/larrys>_
• Luke Amdor <https://github.com/rubbish>_
• Magnus Reftel <https://github.com/reftel>_
• Mahesh Tiyyagura <https://github.com/tmahesh>_
• Marcin L <https://github.com/the-thing>_
• Mark Menard <https://github.com/MarkMenard>_
• Marlon Bernardes <https://github.com/marlonbernardes>_
• Martin Jöhren <https://github.com/matlockx>_
• Martin Traverso <https://github.com/martint>_
• Mateusz Zakarczemny <https://github.com/Matzz>_
• Matheus Cabral <https://github.com/mcgois>_
• Matt Abrams <https://github.com/abramsm>_
• Matt Veitas <https://github.com/mveitas>_
• Matthew Gilliard <https://github.com/mjg123>_
• Matthew O'Connor <https://github.com/oconnor0>_
• Matthias Wiedemann <https://github.com/mwiede>_
• Michael Golahi <https://github.com/mgolahi>_
• Michael Peyton Jones <https://github.com/michaelpj>_
• Michael Vorburger <https://github.com/vorburger>_
• Michał Minicki <https://github.com/martel>_
• Miikka Koskinen <https://github.com/miikka>_
• Mike Gilbode <https://github.com/gilbode>_
• Mike Minicki <https://github.com/martel>_
• Mårten Gustafson <https://github.com/chids>_
• Neil Prosser <https://github.com/neilprosser>_
• Nick Babcock <https://github.com/nickbabcock>_
• Nick Telford <https://github.com/nicktelford>_
• Nikolai Mazurkin <https://github.com/mazurkin>_
• Norbert Potocki <https://github.com/norbertpotocki>_
• Pablo Fernandez <https://github.com/fernandezpablo85>_
• Patryk Najda <https://github.com/patrox>_
• Paul Brown <https://github.com/prb>_
• Paul Doran <https://github.com/dorzey>_
• Paul Oliver <https://github.com/puzza007>_
• Paul Sanwald <https://github.com/pcsanwald>_
• Peter Steiner <https://github.com/pe-st>_
• Philip Dakowitz <https://github.com/philmtd>_
• Philip Helger <https://github.com/phax>_
• Philipp Hauer <https://github.com/phauer>_
• Rahul Ravindran <https://github.com/rahulravindran0108>_
• Raman Gupta <https://github.com/rocketraman>_
• Realbot <https://github.com/realbot>_
• Robby Walker <https://github.com/robbywalker>_
• Ron Klein <https://github.com/kleinron>_
• Ryan Campbell <https://github.com/recampbell>_
• Ryan McCrone <https://github.com/rwmccro>_
• Ryan Tenney <https://github.com/ryantenney>_
• saadmufti <https://github.com/saadmufti>_
• Sam Perman <https://github.com/samperman>_
• Sammy Chu <https://github.com/sammyhk>_
• Samy Dindane <https://github.com/Dinduks>_
• Scott Leberknight <https://github.com/sleberknight>_
• Sean Laurent <https://github.com/organicveggie>_
• Sebastian Lövdahl <https://github.com/slovdahl>_
• Sergey Nazarov <https://github.com/phearnot>_
• Sergio Escalante <https://github.com/sergioescala>_
• Shashank babu <https://github.com/shashank-babu>_
• Silvia Mandalà <https://github.com/simad>_
• sofax <https://github.com/sofax>_
• Stephen Souness <https://github.com/Sounie>_
• Steve Fosdal <https://github.com/sfosdal>_
• Steven Schlansker <https://github.com/stevenschlansker>_
• stockmaj <https://github.com/stockmaj>_
• Stuart Gunter <https://github.com/stuartgunter>_
• Tamas Cservenak <https://github.com/cstamas>_
• Thomas Cashman <https://github.com/tomcashman>_
• Tim Van Laer <https://github.com/timvlaer>_
• Tobias Bieniek <https://github.com/Turbo87>_
• Tobias Lidskog <https://github.com/tobli>_
• Tom Akehurst <https://github.com/tomakehurst>_
• Tom Golden <https://github.com/TomRK1089>_
• Tomas Celaya <https://github.com/tjcelaya>_
• Tomasz Guzik <https://github.com/tguzik>_
• Tomasz Nurkiewicz <https://github.com/nurkiewicz>_
• tomayoola <https://github.com/tomayoola>_
• tvleminckx <https://github.com/tvleminckx>_
• Ufuk Celebi <https://github.com/uce>_
• v-garki <https://github.com/v-garki>_
• Vadym Pechenoha <https://github.com/pechenoha>_
• Vasileios <https://github.com/vasilhsfoto>_
• Vladimir Bukhtoyarov <https://github.com/vladimir-bukhtoyarov>_
• Volker Fritzsch <https://github.com/volker>_
• Wolfgang Hoschek <https://github.com/whoschek>_
• Wolfgang Schell <https://github.com/jetztgradnet>_
• yeyangever <https://github.com/yeyangever>_
• Yuriy Badalyantc <https://github.com/LMnet>_
• Zach A. Thomas <https://github.com/zathomas>_

File: docs/source/about/index.rst Copy Chapter

.. title:: About

.. _about:

#############
About Metrics
#############

.. toctree::
:maxdepth: 1

contributors
release-notes

File: docs/source/about/release-notes.rst Copy Chapter

.. _release-notes:

#############
Release Notes
#############

Please refer to the GitHub releases <https://github.com/dropwizard/metrics/releases>_ for the latest releases of Dropwizard Metrics.

.. _rel-4.0.0:

v4.0.0: Dec 24 2017

• Compiled and targeted JDK8
• Support for running under JDK9 #1236 <https://github.com/dropwizard/metrics/pull/1236>_
• Move JMX reporting to the metrics-jmx module
• Add Bill of Materials for Metrics #1239 #1239 <https://github.com/dropwizard/metrics/pull/1239>_
• Used Java 8 Time API for data formatting
• Removed unnecessary reflection hacks for HealthCheckRegistry
• Removed internal LongAdder
• Removed internal ThreadLocalRandom
• Optimized generating random numbers
• Timer.Context now implements AutoCloseable
• Upgrade Jetty integration to Jetty 9.4
• Support tracking Jersey filters in Jersey resources #1118 <https://github.com/dropwizard/metrics/pull/1239>_
• Add ResponseMetered annotation for Jersey resources #1186 <https://github.com/dropwizard/metrics/pull/1186>_
• Add a method for timing non-throwing functions. #1224 <https://github.com/dropwizard/metrics/pull/1224>_
• Unnecessary clear operation for ChunkedAssociativeArray #1211 <https://github.com/dropwizard/metrics/pull/1211>_
• Add some common metric filters #1210 <https://github.com/dropwizard/metrics/pull/1210>_
• Add possibility to subclass Timer.Context #1226 <https://github.com/dropwizard/metrics/pull/1226>_

.. _rel-3.2.6:

v3.2.6: Dec 24 2017

• Jetty9: unhandled response should be counted as 404 and not 200 #1232 <https://github.com/dropwizard/metrics/pull/1232>_
• Prevent NaN values when calculating mean #1230 <https://github.com/dropwizard/metrics/pull/1230>_
• Avoid NaN values in WeightedSnapshot #1233 <https://github.com/dropwizard/metrics/pull/1233>_

.. _rel-3.2.5:

v3.2.5: Sep 15 2017

• [InstrumentedScheduledExecutorService] Fix the scheduledFixedDelay to call the correct method #1192 <https://github.com/dropwizard/metrics/pull/1192>_

.. _rel-3.2.4:

v3.2.4: Aug 24 2017

• Fix GraphiteReporter rate reporting #1167 <https://github.com/dropwizard/metrics/pull/1167>_
• Remove non Jdk6 compatible letter from date pattern #1163 <https://github.com/dropwizard/metrics/pull/1163>_
• Fix uncaught CancellationException when stopping reporter #1170 <https://github.com/dropwizard/metrics/pull/1170>_

.. _rel-3.2.3:

v3.2.3: Jun 28 2017

• Improve ScheduledReporter convertDurations precision #1115 <https://github.com/dropwizard/metrics/pull/1115>_
• Suppress all kinds of Throwables raised by report() #1128 <https://github.com/dropwizard/metrics/pull/1128>_
• ExponentiallyDecayingReservoir was giving incorrect values in the snapshot if the inactive period was too long #1135 <https://github.com/dropwizard/metrics/pull/1135>_
• Ability to get default metrics registry without an exception #1140 <https://github.com/dropwizard/metrics/pull/1140>_
• Ability to get default health check registry without an exception #1152 <https://github.com/dropwizard/metrics/pull/1152>_
• SlidingTimeWindowArrayReservoir as a fast alternative of SlidingTimeWindowReservoir #1139 <https://github.com/dropwizard/metrics/pull/1139>_
• Avoid a NPE in toString of HealthCheck.Result #1141 <https://github.com/dropwizard/metrics/pull/1141>_

.. _rel-3.1.5:

v3.1.5: Jun 2 2017

• More robust lookup of ThreadLocal and LongAdder on JDK6 (e.g. WebLogic) #1136 <https://github.com/dropwizard/metrics/pull/1136>_

.. _rel-3.2.2:

v3.2.2: Mar 20 2017

• Fix creating a uniform snapshot from a collection #1111 <https://github.com/dropwizard/metrics/pull/1111>_
• Register metrics defined at Resource level #1105 <https://github.com/dropwizard/metrics/pull/1105>_

.. _rel-3.2.1:

v3.2.1: Mar 10 2017

• Support for shutting down the health check registry. #1084 <https://github.com/dropwizard/metrics/pull/1084>_
• Added support for the default shared health check registry name #1095 #1095 <https://github.com/dropwizard/metrics/pull/1095>_
• SharedMetricRegistries are now thread-safe. #1094 <https://github.com/dropwizard/metrics/pull/1095>_
• The size of the snapshot of a histogram is reported via JMX. #1102 <https://github.com/dropwizard/metrics/pull/1102>_
• Don't ignore the counter attribute for reporters. #1090 <https://github.com/dropwizard/metrics/pull/1090>_
• Added support for disabling attributes in ConsoleReporter. #1092 <https://github.com/dropwizard/metrics/pull/1092>_
• Rollbacked GraphiteSanitize to replacing whitespaces. #1099 <https://github.com/dropwizard/metrics/pull/1099>_

.. _rel-3.1.4:

v3.1.4: Mar 10 2017

• Fix accidentally broken Graphite UDP reporter #1100 <https://github.com/dropwizard/metrics/pull/1100>_

.. _rel-3.2.0:

v3.2.0: Feb 24 2017

• GraphiteReporter opens a new TCP connection when sending metrics instead of maintaining a persisted connection. #1047 <https://github.com/dropwizard/metrics/pull/1047>_
• GraphiteReporter retries DNS lookups in case of a lookup failure. #1064 <https://github.com/dropwizard/metrics/pull/1064>_
• ScheduledReporter suppresses all kind of exceptions raised by the report method. #1049 <https://github.com/dropwizard/metrics/pull/1049>_
• JDK's ThreadLocalRandom is now used by default. #1052 <https://github.com/dropwizard/metrics/pull/1052>_
• JDK's LongAdder is now used by default. #1055 <https://github.com/dropwizard/metrics/pull/1055>_
• Fixed a race condition bug in ExponentiallyDecayingReservoir. #1033 <https://github.com/dropwizard/metrics/pull/1033>_
• Fixed a long overflow bug in SlidingTimeWindowReservoir. #1063 <https://github.com/dropwizard/metrics/pull/1063>_
• AdminServlet supports CPU profiling. #927 <https://github.com/dropwizard/metrics/pull/927>_
• GraphiteReporter sanitizes metrics. #938 <https://github.com/dropwizard/metrics/pull/938>_
• Support for publishing BigInteger and BigDecimal metrics in GraphiteReporter. #933 <https://github.com/dropwizard/metrics/pull/933>_
• Support for publishing boolean metrics in GraphiteReporter. #905 <https://github.com/dropwizard/metrics/pull/905>_
• Added support for overriding the format of floating numbers in GraphiteReporter. #1073 <https://github.com/dropwizard/metrics/pull/1073>_
• Added support for disabling reporting of metric attributes. #1048 <https://github.com/dropwizard/metrics/pull/1048>_
• Reporters are more user friendly for managed environments like GAE or JEE. #1018 <https://github.com/dropwizard/metrics/pull/1018>_
• Support for setting a custom initial delay for reporters. #999 <https://github.com/dropwizard/metrics/pull/999>_
• Support for custom details in a result of a health check. #663 <https://github.com/dropwizard/metrics/pull/663>_
• Added a listener for health checks. #1068 <https://github.com/dropwizard/metrics/pull/1068>_
• Support for asynchronous health checks #1077 <https://github.com/dropwizard/metrics/pull/1077>_
• Health checks are reported as unhealthy on exceptions. #783 <https://github.com/dropwizard/metrics/pull/783>_
• Allow setting a custom prefix for Jetty's InstrumentedQueuedThreadPool. #947 <https://github.com/dropwizard/metrics/pull/947>_
• Allow setting custom prefix for Jetty's QueuedThreadPool. #908 <https://github.com/dropwizard/metrics/pull/908>_
• Added support for Jetty 9.3 and higher. #1038 <https://github.com/dropwizard/metrics/pull/1038>_
• Fixed instrumentation of Jetty9 async servlets. #1074 <https://github.com/dropwizard/metrics/pull/1074>_
• Added support for JCache/JSR 107 metrics. #1010 <https://github.com/dropwizard/metrics/pull/1010>_
• Added thread-safe getters for metrics with custom instantiations. #1023 <https://github.com/dropwizard/metrics/pull/1023>_
• Added an overload of Timer#time that takes a Runnable. #989 <https://github.com/dropwizard/metrics/pull/989>_
• Support extracting the request URI from wrapped requests in HttpClientMetricNameStrategies. #947 <https://github.com/dropwizard/metrics/pull/947>_
• Support for the log4j2 xml-based config. #900 <https://github.com/dropwizard/metrics/pull/900>_
• Internal Striped64 doesn't depend on sun.misc.Unsafe anymore. #966 <https://github.com/dropwizard/metrics/pull/966>_
• Optimized creation of UniformSnapshot. #970 <https://github.com/dropwizard/metrics/pull/970>_
• Added a memory pool gauge to the JVM memory usage metrics. #786 <https://github.com/dropwizard/metrics/pull/786>_
• Added support for async servlets for metric-servlet. #796 <https://github.com/dropwizard/metrics/pull/796>_
• Opt-in default shared metric registry. #801 <https://github.com/dropwizard/metrics/pull/801>_
• Added support for patterns in MBean object names #809 <https://github.com/dropwizard/metrics/pull/809>_
• Allow a pluggable strategy for the name of the CSV files for CsvReporter. #882 <https://github.com/dropwizard/metrics/pull/882>_
• Upgraded to slf4j 1.22
• Upgraded to Jackson 2.6.6
• Upgraded to amqp-client 3.6.6
• Upgraded to httpclient 4.5.2
• Upgraded to log4j2 2.3
• Upgraded to logback 1.1.10

.. _rel-3.1.3:

v3.1.3: Feb 24 2017

• GraphiteReporter opens a new TCP connection when sending metrics instead of maintaining a persisted connection. #1036 <https://github.com/dropwizard/metrics/pull/1036>_
• GraphiteReporter retries DNS lookups in case of a lookup failure. #1064 <https://github.com/dropwizard/metrics/pull/1064>_
• ScheduledReporter suppresses all kind of exceptions raised by the report method. #1040 <https://github.com/dropwizard/metrics/pull/1040>_
• JDK's ThreadLocalRandom is now used by default. #1052 <https://github.com/dropwizard/metrics/pull/1052>_
• JDK's LongAdder is now used by default. #1055 <https://github.com/dropwizard/metrics/pull/1055>_
• Fixed a race condition bug in ExponentiallyDecayingReservoir. #1046 <https://github.com/dropwizard/metrics/pull/1046>_
• Fixed a long overflow bug in SlidingTimeWindowReservoir. #1072 <https://github.com/dropwizard/metrics/pull/1072>_

.. _rel-3.1.0:

v3.1.0: Sen 10 2014

https://groups.google.com/forum/#!topic/metrics-user/zwzHnMBcAX4

• Upgrade to Jetty 9.1 (metrics-jetty9, Jetty 9.0 module renamed to metrics-jetty9-legacy)
• Add log4j2 support (metrics-log4j2)
• Upgrade to Jersey2 (metrics-jersey2)
• Add httpasyncclient support (metrics-httpasyncclient)
• Changed maven groupId to io.dropwizard.metrics
• Enable Java8 builds on Travis, fix javadocs and disable some doclinting
• Fixing some compilation warnings about missing generics and varargs invocation
• Instrumentation for java.util.concurrent classes
• ExponentiallyDecayingReservoir: quantiles weighting
• Loosen type requirements for JmxAttributeGauge constructor
• SlidingWindowReservoir - ArrayOutOfBoundsException thrown if # of Reservoir examples exceeds Integer max value
• Classloader metrics
• Add an instrumented ScheduledExecutorService
• Fix race condition in InstrumentedThreadFactoryTest
• Correct comparison of System.nanoTime in SlidingTimeWindowReservoir
• Add SharedHealthCheckRegistries class
• Migrate benchmarks from Caliper to JMH
• New annotations: @CachedGauge, @Counted, @Metric
• Support for annotations on classes and constructors
• Allow @Metric on methods and parameters
• Add @Inherited and @Documented on all type annotations
• Adapted ehcache integration to latest ehcache version 2.8.3
• Upgrade to HttpClient 4.3
• InstrumentedHandler: Remove duplicate calls to requests.update(...)
• New metric 'utilization-max' to track thread usage out of max pool size in jetty
• Replaced Jetty-specific Request with Servlet API interfaces
• Jetty 8: Avoid NPE if InstrumentedQueuedThreadPool gauges are read too early
• Jetty 8: Call updateResponses onComplete of ContinuationListener
• Allow specifying a custom prefix Jetty 9 InstrumentedHandler
• MetricsModule is serializing wrong minute rates for timers
• MeterSerializer.serialize had m1_rate and m15_rate transposed
• Add CachedThreadStatesGaugeSet
• Monitor count of deadlock threads
• Prevent exceptions from ThreadDumpServlet on Google AppEngine
• Upgrade to logback 1.1.1
• Allow InstrumentedAppender use in logback.xml
• Use getClass() in place of AbstractInstrumentedFilter.class in generated metric names
• Update MetricsServlet with support for JSONP as alternative to CORS
• Specify the base name of the metrics as a filter init-param for the metrics captured in the AbstractInstrumentedFilter
• Add option to provide MetricFilter to MetricsServlet
• AdminServlet generates link to pretty printed healthchecks
• MetricsServlet.ContextListener doesn't initialize the context correctly
• Every reporter implements Reporter interface to indicate that is a Reporter
• Added support for passing a ScheduledExecutorService to ScheduledReporters
• Improve the ScheduledReporter#stop method
• Ensure ScheduledReporters get unique thread pools.
• Suppress runtime exceptions thrown from ScheduledReporter#report
• Ability to inject a factory of ObjectName
• Lazy fetch of PlatformMBeanServer
• JMX Reporter throws exception when metric name contains an asterisk
• onTimerRemoved in JmxListener calls registered.add
• Support for mBean servers that rewrite the supplied ObjectName upon registration
• Graphite reporter does not notify when Graphite/Carbon server is unreachable
• Persistent connections to Graphite
• Graphite constructor accepts host/port
• Graphtie Pickle sender
• Graphite UDP sender
• Graphite AMQP sender
• Add a threshold/minimum value to report before converting results to 0
• Report to multiple gmetric instances
• Escape slahes on ganglia metric names
• Upgrade slf4j to 1.7.6
• Enhancement for logging level option on Slf4jReporter

.. _rel-3.0.1:

v3.0.1: Jul 23 2013

• Fixed NPE in MetricRegistry#name.
• ScheduledReporter and JmxReporter now implement Closeable.
• Fixed cast exception for async requests in metrics-jetty9.
• Added support for Access-Control-Allow-Origin to MetricsServlet.
• Fixed numerical issue with Meter EWMA rates.
• Deprecated AdminServletContextListener in favor of MetricsServlet.ContextListener and
  HealthCheckServlet.ContextListener.
• Added additional constructors to HealthCheckServlet and MetricsServlet.

.. _rel-3.0.0:

v3.0.0: June 10 2013

• Renamed DefaultWebappMetricsFilter to InstrumentedFilter.
• Renamed MetricsContextListener to InstrumentedFilterContextListener and made it fully
  abstract to avoid confusion.
• Renamed MetricsServletContextListener to AdminServletContextListener and made it fully
  abstract to avoid confusion.
• Upgraded to Servlet API 3.1.
• Upgraded to Jackson 2.2.2.
• Upgraded to Jetty 8.1.11.

.. _rel-3.0.0-RC1:

v3.0.0-RC1: May 31 2013

• Added SharedMetricRegistries, a singleton for sharing named metric registries.
• Fixed XML configuration for metrics-ehcache.
• Fixed XML configuration for metrics-jersey.
• Fixed XML configuration for metrics-log4j.
• Fixed XML configuration for metrics-logback.
• Fixed a counting bug in metrics-jetty9's InstrumentedHandler.
• Added MetricsContextListener to metrics-servlet.
• Added MetricsServletContextListener to metrics-servlets.
• Extracted the Counting interface.
• Reverted SlidingWindowReservoir to a synchronized implementation.
• Added the implementation version to the JAR manifests.
• Made dependencies for all modules conform to Maven Enforcer's convergence rules.
• Fixed Slf4jReporter's logging of 99th percentiles.
• Added optional name prefixing to GraphiteReporter.
• Added metric-specific overrides of rate and duration units to JmxReporter.
• Documentation fixes.

.. _rel-3.0.0-BETA3:

v3.0.0-BETA3: May 13 2013

• Added ScheduledReporter#report() for manual reporting.
• Fixed overly-grabby catches in HealthCheck and
  InstrumentedResourceMethodDispatchProvider.
• Fixed phantom reads in SlidingWindowReservoir.
• Revamped metrics-jetty9, removing InstrumentedConnector and improving
  the API.
• Fixed OSGi imports for sun.misc.
• Added a strategy class for HttpClient metrics.
• Upgraded to Jetty 9.0.3.
• Upgraded to Jackson 2.2.1.
• Upgraded to Ehcache 2.6.6.
• Upgraded to Logback 1.0.13.
• Upgraded to HttpClient 4.2.5.
• Upgraded to gmetric4j 1.0.3, which allows for host spoofing.

.. _rel-3.0.0-BETA2:

v3.0.0-BETA2: Apr 22 2013

• Metrics is now under the com.codahale.metrics package, with the corresponding changes in Maven
  artifact groups. This should allow for an easier upgrade path without classpath conflicts.
• MetricRegistry no longer has a name.
• Added metrics-jetty9 for Jetty 9.
• JmxReporter takes an optional domain property to disambiguate multiple reporters.
• Fixed Java 6 compatibility problem. (Also added Java 6 as a CI environment.)
• Added MetricRegistryListener.Base.
• Switched Counter, Meter, and EWMA to use JSR133's LongAdder instead of
  AtomicLong, improving contended concurrency.
• Added MetricRegistry#buildMap(), allowing for custom map implementations in
  MetricRegistry.
• Added MetricRegistry#removeMatching(MetricFilter).
• Changed metrics-json to optionally depend on metrics-healthcheck.
• Upgraded to Jetty 8.1.10 for metrics-jetty8.

.. _rel-3.0.0-BETA1:

v3.0.0-BETA1: Apr 01 2013

• Total overhaul of most of the core Metrics classes:

  • Metric names are now just dotted paths like com.example.Thing, allowing for very flexible
    scopes, etc.
  • Meters and timers no longer have rate or duration units; those are properties of reporters.
  • Reporter architecture has been radically simplified, fixing many bugs.
  • Histograms and timers can take arbitrary reservoir implementations.
  • Added sliding window reservoir implementations.
  • Added MetricSet for sets of metrics.

• Changed package names to be OSGi-compatible and added OSGi bundling.

• Extracted JVM instrumentation to metrics-jvm.

• Extracted Jackson integration to metrics-json.

• Removed metrics-guice, metrics-scala, and metrics-spring.

• Renamed metrics-servlet to metrics-servlets.

• Renamed metrics-web to metrics-servlet.

• Renamed metrics-jetty to metrics-jetty8.

• Many more small changes!

.. _rel-2.2.0:

v2.2.0: Nov 26 2012

• Removed all OSGi bundling. This will be back in 3.0.
• Added InstrumentedSslSelectChannelConnector and InstrumentedSslSocketConnector.
• Made all metric names JMX-safe.
• Upgraded to Ehcache 2.6.2.
• Upgraded to Apache HttpClient 4.2.2.
• Upgraded to Jersey 1.15.
• Upgraded to Log4j 1.2.17.
• Upgraded to Logback 1.0.7.
• Upgraded to Spring 3.1.3.
• Upgraded to Jetty 8.1.8.
• Upgraded to SLF4J 1.7.2.
• Replaced usage of Unsafe in InstrumentedResourceMethodDispatchProvider with type erasure
  trickery.

.. _rel-2.1.5:

v2.1.5: Nov 19 2012

• Upgraded to Jackson 2.1.1.

.. _rel-2.1.4:

v2.1.4: Nov 15 2012

• Added OSGi bundling manifests.

.. _rel-2.1.3:

v2.1.3: Aug 06 2012

• Upgraded to Apache HttpClient 4.2.1.
• Changed InstrumentedClientConnManager to extend PoolingClientConnectionManager instead of
  the deprecated ThreadSafeClientConnManager.
• Fixed a bug in ExponentiallyDecayingSample with long periods of inactivity.
• Fixed problems with re-registering metrics in JMX.
• Added support for DnsResolver instances to InstrumentedClientConnManager.
• Added support for formatted health check error messages.

.. _rel-2.1.2:

v2.1.2: Apr 11 2012

• Fixed double-registration in metrics-guice.

.. _rel-2.1.1:

v2.1.1: Mar 13 2012

• Fixed instrumentation of all usages of InstrumentedHttpClient.

.. _rel-2.1.0:

v2.1.0: Mar 12 2012

• Added support for Java 7's direct and mapped buffer pool stats in VirtualMachineMetrics and
  metrics-servlet.
• Added support for XML configuration in metrics-ehcache.
• metrics-spring now support @Gauge-annotated fields.
• Opened GraphiteReporter up for extension.
• Added group and type to metrics-annotations, metrics-guice, metrics-jersey,
  and metrics-spring.
• Fixed handling of non-int gauges in GangliaReporter.
• Fixed NullPointerException errors in metrics-spring.
• General improvements to metrics-spring, including allowing custom Clock instances.

.. _rel-2.0.3:

v2.0.3: Feb 24 2012

• Change logging of InstanceNotFoundException exceptions thrown while unregistering a metric
  in JmxReporter to TRACE. It being WARN resulted in huge log dumps preventing process
  shutdowns when applications had ~1K+ metrics.
• Upgraded to Spring 3.1.1 for metrics-spring.
• Upgraded to JDBI 2.31.2.
• Upgraded to Jersey 1.12.
• Upgraded to Jetty 7.6.1.
• Fixed rate units for meters in GangliaReporter.

.. _rel-2.0.2:

v2.0.2: Feb 09 2012

• InstrumentationModule in metrics-guice now uses the default MetricsRegistry and
  HealthCheckRegistry.

.. _rel-2.0.1:

v2.0.1: Feb 08 2012

• Fixed a concurrency bug in JmxReporter.

.. _rel-2.0.0:

v2.0.0: Feb 07 2012

• Upgraded to Jackson 1.9.4.
• Upgraded to Jetty 7.6.0.
• Added escaping for garbage collector and memory pool names in GraphiteReporter.
• Fixed the inability to start and stop multiple reporter instances.
• Switched to using a backported version of ThreadLocalRandom for UniformSample and
  ExponentiallyDecayingSample to reduce lock contention on random number generation.
• Removed Ordered from TimedAnnotationBeanPostProcessor in metrics-spring.
• Upgraded to JDBI 2.31.1.
• Upgraded to Ehcache 2.5.1.
• Added #timerContext() to Scala Timer.

.. _rel-2.0.0-RC0:

v2.0.0-RC0: Jan 19 2012

• Added FindBugs checks to the build process.
• Fixed the catching of Error instances thrown during health checks.
• Added enable static methods to CsvReporter and changed
  CsvReporter(File, MetricsRegistry) to CsvReporter(MetricsRegistry, File).
• Slimmed down InstrumentedEhcache.
• Hid the internals of GangliaReporter.
• Hid the internals of metrics-guice.
• Changed metrics-httpclient to consistently associate metrics with the org.apache class
  being extended.
• Hid the internals of metrics-httpclient.
• Rewrote InstrumentedAppender in metrics-log4j. It no longer forwards events to an
  appender. Instead, you can just attach it to your root logger to instrument logging.
• Rewrote InstrumentedAppender in metrics-logback. No major API changes.
• Fixed bugs with @ExceptionMetered-annotated resource methods in metrics-jersey.
• Fixed bugs generating Snapshot instances from concurrently modified collections.
• Fixed edge case in MetricsServlet's thread dumps where one thread could be missed.
• Added RatioGauge and PercentGauge.
• Changed InstrumentedQueuedThreadPool's percent-idle gauge to be a ratio.
• Decomposed MetricsServlet into a set of focused servlets: HealthCheckServlet,
  MetricsServlet, PingServlet, and ThreadDumpServlet. The top-level servlet which
  provides the HTML menu page is now AdminServlet.
• Added metrics-spring.

.. _rel-2.0.0-BETA19:

v2.0.0-BETA19: Jan 07 2012

• Added absolute memory usage to MetricsServlet.
• Extracted @Timed etc. to metrics-annotations.
• Added metrics-jersey, which provides a class allowing you to automatically instrument all
  @Timed, @Metered, and @ExceptionMetered-annotated resource methods.
• Moved all classes in metrics-scala from com.yammer.metrics to
  com.yammer.metrics.scala.
• Renamed CounterMetric to Counter.
• Renamed GaugeMetric to Gauge.
• Renamed HistogramMetric to Histogram.
• Renamed MeterMetric to Meter.
• Renamed TimerMetric to Timer.
• Added ToggleGauge, which returns 1 the first time it's called and 0 every time after
  that.
• Now licensed under Apache License 2.0.
• Converted VirtualMachineMetrics to a non-singleton class.
• Removed Utils.
• Removed deprecated constructors from Meter and Timer.
• Removed LoggerMemoryLeakFix.
• DeathRattleExceptionHandler now logs to SLF4J, not syserr.
• Added MetricsRegistry#groupedMetrics().
• Removed Metrics#allMetrics().
• Removed Metrics#remove(MetricName).
• Removed MetricsRegistry#threadPools() and #newMeterTickThreadPool() and added
  #newScheduledThreadPool.
• Added MetricsRegistry#shutdown().
• Renamed ThreadPools#shutdownThreadPools() to #shutdown().
• Replaced HealthCheck's abstract name method with a required constructor parameter.
• HealthCheck#check() is now protected.
• Moved DeadlockHealthCheck from com.yammer.metrics.core to com.yammer.metrics.utils.
• Added HealthCheckRegistry#unregister(HealthCheck).
• Fixed typo in VirtualMachineMetrics and MetricsServlet: commited to committed.
• Changed MetricsRegistry#createName to protected.
• All metric types are created exclusively through MetricsRegistry now.
• Metrics.newJmxGauge and MetricsRegistry.newJmxGauge are deprecated.
• Fixed heap metrics in VirtualMachineMetrics.
• Added Snapshot, which calculates quantiles.
• Renamed Percentiled to Sampling and dropped percentile and percentiles in favor of
  producing Snapshot instances. This affects both Histogram and Timer.
• Renamed Summarized to Summarizable.
• Changed order of CsvReporter's construction parameters.
• Renamed VirtualMachineMetrics.GarbageCollector to
  VirtualMachineMetrics.GarbageCollectorStats.
• Moved Guice/Servlet support from metrics-servlet to metrics-guice.
• Removed metrics-aop.
• Removed newJmxGauge from both Metrics and MetricsRegistry. Just use JmxGauge.
• Moved JmxGauge to com.yammer.metrics.util.
• Moved MetricPredicate to com.yammer.metrics.core.
• Moved NameThreadFactory into ThreadPools and made ThreadPools package-visible.
• Removed Timer#values(), Histogram#values(), and Sample#values(). Use getSnapshot()
  instead.
• Removed Timer#dump(File) and Histogram#dump(File), and Sample#dump(File). Use
  Snapshot#dump(File) instead.

.. _rel-2.0.0-BETA18:

v2.0.0-BETA18: Dec 16 2011

• Added DeathRattleExceptionHandler.
• Fixed NPE in VirtualMachineMetrics.
• Added decorators for connectors and thread pools in metrics-jetty.
• Added TimerMetric#time() and TimerContext.
• Added a shorter factory method for millisecond/second timers.
• Switched tests to JUnit.
• Improved logging in GangliaReporter.
• Improved random number generation for UniformSample.
• Added metrics-httpclient for instrumenting Apache HttpClient 4.1.
• Massively overhauled the reporting code.
• Added support for instrumented, non-public methods in metrics-guice.
• Added @ExceptionMetered to metrics-guice.
• Added group prefixes to GangliaReporter.
• Added CvsReporter, which outputs metric values to .csv files.
• Improved metric name sanitization in GangliaReporter.
• Added Metrics.shutdown() and improved metrics lifecycle behavior.
• Added metrics-web.
• Upgraded to ehcache 2.5.0.
• Many, many refactorings.
• metrics-servlet now responds with 501 Not Implememented when no health checks have been
  registered.
• Many internal refactorings for testability.
• Added histogram counts to metrics-servlet.
• Fixed a race condition in ExponentiallyDecayingSample.
• Added timezone and locale support to ConsoleReporter.
• Added metrics-aop for Guiceless support of method annotations.
• Added metrics-jdbi which adds instrumentation to JDBI_.
• Fixed NPE for metrics which belong to classes in the default package.
• Now deploying artifacts to Maven Central.

.. _JDBI: http://www.jdbi.org

.. _rel-2.0.0-BETA17:

v2.0.0-BETA17: Oct 07 2011

• Added an option message to successful health check results.
• Fixed locale issues in GraphiteReporter.
• Added GangliaReporter.
• Added per-HTTP method timers to InstrumentedHandler in metrics-jetty.
• Fixed a thread pool leak for meters.
• Added #dump(File) to HistogramMetric and TimerMetric.
• Upgraded to Jackson 1.9.x.
• Upgraded to slf4j 1.6.2.
• Upgraded to logback 0.9.30.
• Upgraded to ehcache 2.4.5.
• Surfaced Metrics.removeMetric().

.. _rel-2.0.0-BETA16:

v2.0.0-BETA16: Aug 23 2011

• Fixed a bug in GC monitoring.

.. _rel-2.0.0-BETA15:

v2.0.0-BETA15: Aug 15 2011

• Fixed dependency scopes for metrics-jetty.
• Added time and VM version to vm output of MetricsServlet.
• Dropped com.sun.mangement-based GC instrumentation in favor of a
  java.lang.management-based one. getLastGcInfo has a nasty native memory leak in it, plus
  it often returned incorrect data.
• Upgraded to Jackson 1.8.5.
• Upgraded to Jetty 7.4.5.
• Added sanitization for metric names in GraphiteReporter.
• Extracted out a Clock interface for timers for non-wall-clock timing.
• Extracted out most of the remaining statics into MetricsRegistry and HealthCheckRegistry.
• Added an init parameter to MetricsServlet for disabling the jvm section.
• Added a Guice module for MetricsServlet.
• Added dynamic metric names.
• Upgraded to ehcache 2.4.5.
• Upgraded to logback 0.9.29.
• Allowed for the removal of metrics.
• Added the ability to filter metrics exposed by a reporter to those which match a given predicate.

.. _rel-2.0.0-BETA14:

v2.0.0-BETA14: Jul 05 2011

• Moved to Maven for a build system and extracted the Scala façade to a metrics-scala module
  which is now the only cross-built module. All other modules dropped the Scala version suffix in
  their artifactId.
• Fixed non-heap metric name in GraphiteReporter.
• Fixed stability error in GraphiteReporter when dealing with unavailable servers.
• Fixed error with anonymous, instrumented classes.
• Fixed error in MetricsServlet when a gauge throws an exception.
• Fixed error with bogus GC run times.
• Link to the pretty JSON output from the MetricsServlet menu page.
• Fixed potential race condition in histograms' variance calculations.
• Fixed memory pool reporting for the G1 collector.

.. _rel-2.0.0-BETA13:

v2.0.0-BETA13: May 13 2011

• Fixed a bug in the initial startup phase of the JmxReporter.
• Added metrics-ehcache, for the instrumentation of Ehcache instances.
• Fixed a typo in metrics-jetty's InstrumentedHandler.
• Added name prefixes to GraphiteReporter.
• Added JVM metrics reporting to GraphiteReporter.
• Actually fixed MetricsServlet's links when the servlet has a non-root context path.
• Now cross-building for Scala 2.9.0.
• Added pretty query parameter for MetricsServlet to format the JSON object for human
  consumption.
• Added no-cache headers to the MetricsServlet responses.

.. _rel-2.0.0-BETA12:

v2.0.0-BETA12: May 09 2011

• Upgraded to Jackson 1.7.6.

• Added a new instrumented Log4J appender.

• Added a new instrumented Logback appender. Thanks to Bruce Mitchener
  (@waywardmonkeys) for the patch.

• Added a new reporter for the Graphite_ aggregation system. Thanks to Mahesh Tiyyagura (@tmahesh)
  for the patch.

• Added scoped metric names.

• Added Scala 2.9.0.RC{2,3,4} as build targets.

• Added meters to Jetty handler for the percent of responses which have 4xx or 5xx status
  codes.

• Changed the Servlet API to be a provided dependency. Thanks to Mårten Gustafson (@chids) for
  the patch.

• Separated project into modules:

  • metrics-core: A dependency-less project with all the core metrics.
  • metrics-graphite: A reporter for the Graphite
    aggregation system.
  • metrics-guice: Guice AOP support.
  • metrics-jetty: An instrumented Jetty handler.
  • metrics-log4j: An instrumented Log4J appender.
  • metrics-logback: An instrumented Logback appender.
  • metrics-servlet: The Metrics servlet with context listener.

.. _Graphite: http://graphite.wikidot.com

.. _rel-2.0.0-BETA11:

v2.0.0-BETA11: Apr 27 2011

• Added thread state and deadlock detection metrics.
• Fix VirtualMachineMetrics' initialization.
• Context path fixes for the servlet.
• Added the @Gauge annotation.
• Big reworking of the exponentially-weighted moving average code for meters. Thanks to JD Maturen
  (@sku) and John Ewart (@johnewart) for pointing this out.
• Upgraded to Guice 3.0.
• Upgraded to Jackson 1.7.5.
• Upgraded to Jetty 7.4.0.
• Big rewrite of the servlet's thread dump code.
• Fixed race condition in ExponentiallyDecayingSample. Thanks to Martin Traverso (@martint) for
  the patch.
• Lots of spelling fixes in Javadocs. Thanks to Bruce Mitchener (@waywardmonkeys) for the patch.
• Added Scala 2.9.0.RC1 as a build target. Thanks to Bruce Mitchener (@waywardmonkeys) for the
  patch.
• Patched a hilarious memory leak in java.util.logging.

.. _rel-2.0.0-BETA10:

v2.0.0-BETA10: Mar 25 2011

• Added Guice AOP annotations: @Timed and @Metered.
• Added HealthCheck#name().
• Added Metrics.newJmxGauge().
• Moved health checks into HealthChecks.
• Upgraded to Jackson 1.7.3 and Jetty 7.3.1.

.. _rel-2.0.0-BETA9:

v2.0.0-BETA9: Mar 14 2011

• Fixed JmxReporter lag.
• Added default arguments to timers and meters.
• Added default landing page to the servlet.
• Improved the performance of ExponentiallyDecayingSample.
• Fixed an integer overflow bug in UniformSample.
• Added linear scaling to ExponentiallyDecayingSample.

.. _rel-2.0.0-BETA8:

v2.0.0-BETA8: Mar 01 2011

• Added histograms.
• Added biased sampling for timers.
• Added dumping of timer/histogram samples via the servlet.
• Added dependency on jackon-mapper.
• Added classname filtering for the servlet.
• Added URI configuration for the servlet.

.. _rel-2.0.0-BETA7:

v2.0.0-BETA7: Jan 12 2011

• Added JettyHandler.
• Made the Servlet dependency optional.

.. _rel-2.0.0-BETA6:

v2.0.0-BETA6: Jan 12 2011

• Fix JmxReporter initialization.

.. _rel-2.0.0-BETA5:

v2.0.0-BETA5: Jan 11 2011

• Dropped Counter#++ and Counter#--.
• Added Timer#update.
• Upgraded to Jackson 1.7.0.
• Made JMX reporting implicit.
• Added health checks.

.. _rel-2.0.0-BETA3:

v2.0.0-BETA3: Dec 23 2010

• Fixed thread names and some docs.

.. _rel-2.0.0-BETA2:

v2.0.0-BETA2: Dec 22 2010

• Fixed a memory leak in MeterMetric.

.. _rel-2.0.0-BETA1:

v2.0.0-BETA1: Dec 22 2010

• Total rewrite in Java.

.. _rel-1.0.7:

v1.0.7: Sep 21 2010

• Added median to Timer.
• Added p95 to Timer (95th percentile).
• Added p98 to Timer (98th percentile).
• Added p99 to Timer (99th percentile).

.. _rel-1.0.6:

v1.0.6: Jul 15 2010

• Now compiled exclusively for 2.8.0 final.

.. _rel-1.0.5:

v1.0.5: Jun 01 2010

• Documentation fix.
• Added TimedToggle, which may or may not be useful at all.
• Now cross-building for RC2 and RC3.

.. _rel-1.0.4:

v1.0.4: Apr 27 2010

• Blank Timer instances (i.e., those which have recorded no timings yet) no longer explode when
  asked for metrics for that which does not yet exist.
• Nested classes, companion objects, and singletons don't have trailing $ characters messing up
  JMX's good looks.

.. _rel-1.0.3:

v1.0.3: Apr 16 2010

• Fixed some issues with the implicit.ly__ plumbing.
• Tweaked the sample size for Timer, giving it 99.9% confidence level with a %5 margin of error
  (for a normally distributed variable, which it almost certainly isn't.)
• Sample#iterator returns only the recorded data, not a bunch of zeros.
• Moved units of Timer, Meter, and LoadMeter to their own attributes, which allows for
  easy export of Metrics data via JMX to things like Ganglia__ or whatever.

.. __: http://implicit.ly
.. __: http://ganglia.sourceforge.net/

.. _rel-1.0.2:

v1.0.2: Mar 08 2010

• Timer now uses Welford's algorithm for calculating running variance, which means no more
  hilariously wrong standard deviations (e.g., NaN).
• Timer now supports +=(Long) for pre-recorded, nanosecond-precision timings.

.. _rel-1.0.1:

v1.0.1: Mar 05 2010

• changed Sample to use an AtomicReferenceArray

.. _rel-1.0.0:

v1.0.0: Feb 27 2010

• Initial release

File: docs/source/manual/caffeine.rst Copy Chapter

.. _manual-caffeine:

#####################
Instrumenting Caffeine
#####################

.. highlight:: text

.. rubric:: The metrics-caffeine module provides MetricsStatsCounter, a metrics listener for
Caffeine_ caches:

.. _Caffeine: https://github.com/ben-manes/caffeine

.. code-block:: java

LoadingCache cache = Caffeine.newBuilder()
    .recordStats(() -> new MetricsStatsCounter(registry, "cache"))
    .build(key -> key);

The listener publishes these metrics:

+---------------------------+----------------------------------------------------------------------+
| hits | Number of times a requested item was found in the cache. |
+---------------------------+----------------------------------------------------------------------+
| misses | Number of times a requested item was not found in the cache. |
+---------------------------+----------------------------------------------------------------------+
| loads-success | Timer for successful loads into cache. |
+---------------------------+----------------------------------------------------------------------+
| loads-failure | Timer for failed loads into cache. |
+---------------------------+----------------------------------------------------------------------+
| evictions | Histogram of eviction weights . |
+---------------------------+----------------------------------------------------------------------+
| evictions-weight | Total weight of evicted entries. |
+---------------------------+----------------------------------------------------------------------+
| evictions.<CAUSE> | Histogram of eviction weights for each RemovalCause |
+---------------------------+----------------------------------------------------------------------+

File: docs/source/manual/collectd.rst Copy Chapter

.. _manual-collectd:

#####################
Reporting to Collectd
#####################

The metrics-collectd module provides CollectdReporter, which allows your application to
constantly stream metric values to a Collectd_ server:

.. _Collectd: https://collectd.org/

.. code-block:: java

final Sender sender = new Sender("collectd.example.com", 2007);
final CollectdReporter reporter = CollectdReporter.forRegistry(registry)
                                                  .convertRatesTo(TimeUnit.SECONDS)
                                                  .convertDurationsTo(TimeUnit.MILLISECONDS)
                                                  .filter(MetricFilter.ALL)
                                                  .build(sender);
reporter.start(1, TimeUnit.MINUTES);

File: docs/source/manual/core.rst Copy Chapter

.. _manual-core:

############
Metrics Core
############

.. highlight:: text

The central library for Metrics is metrics-core, which provides some basic functionality:

• Metric :ref:registries <man-core-registries>.
• The five metric types: :ref:man-core-gauges, :ref:man-core-counters,
  :ref:man-core-histograms, :ref:man-core-meters, and :ref:man-core-timers.
• Reporting metrics values via :ref:JMX <man-core-reporters-jmx>, the
  :ref:console <man-core-reporters-console>, :ref:CSV <man-core-reporters-csv> files, and
  :ref:SLF4J loggers <man-core-reporters-slf4j>.

.. _man-core-registries:

Metric Registries

The starting point for Metrics is the MetricRegistry class, which is a collection of all the
metrics for your application (or a subset of your application).

Generally you only need one MetricRegistry instance per application, although you may choose
to use more if you want to organize your metrics in particular reporting groups.

Global named registries can also be shared through the static SharedMetricRegistries class. This
allows the same registry to be used in different sections of code without explicitly passing a MetricRegistry
instance around.

Like all Metrics classes, SharedMetricRegistries is fully thread-safe.

.. _man-core-names:

Metric Names

Each metric is associated with a MetricRegistry, and has a unique name within that registry. This is a simple
dotted name, like com.example.Queue.size. This flexibility allows you to encode a wide variety of
context directly into a metric's name. If you have two instances of com.example.Queue, you can give
them more specific: com.example.Queue.requests.size vs. com.example.Queue.responses.size, for example.

MetricRegistry has a set of static helper methods for easily creating names:

.. code-block:: java

MetricRegistry.name(Queue.class, "requests", "size")
MetricRegistry.name(Queue.class, "responses", "size")

These methods will also elide any null values, allowing for easy optional scopes.

.. _man-core-gauges:

Gauges

A gauge is the simplest metric type. It just returns a value. If, for example, your application
has a value which is maintained by a third-party library, you can easily expose it by registering a
Gauge instance which returns that value:

.. code-block:: java

registry.register(name(SessionStore.class, "cache-evictions"), new Gauge() {
    @Override
    public Integer getValue() {
        return cache.getEvictionsCount();
    }
});

This will create a new gauge named com.example.proj.auth.SessionStore.cache-evictions which will
return the number of evictions from the cache.

.. _man-core-gauges-jmx:

JMX Gauges Copy Chapter

Given that many third-party libraries often expose metrics only via JMX, Metrics provides the
JmxAttributeGauge class, which takes the object name of a JMX MBean and the name of an attribute
and produces a gauge implementation which returns the value of that attribute:

.. code-block:: java

registry.register(name(SessionStore.class, "cache-evictions"),
                 new JmxAttributeGauge("net.sf.ehcache:type=Cache,scope=sessions,name=eviction-count", "Value"));

.. _man-core-gauges-ratio:

Ratio Gauges Copy Chapter

A ratio gauge is a simple way to create a gauge which is the ratio between two numbers:

.. code-block:: java

public class CacheHitRatio extends RatioGauge {
    private final Meter hits;
    private final Timer calls;

    public CacheHitRatio(Meter hits, Timer calls) {
        this.hits = hits;
        this.calls = calls;
    }

    @Override
    public Ratio getRatio() {
        return Ratio.of(hits.getOneMinuteRate(),
                        calls.getOneMinuteRate());
    }
}

This gauge returns the ratio of cache hits to misses using a meter and a timer.

.. _man-core-gauges-cached:

Cached Gauges Copy Chapter

A cached gauge allows for a more efficient reporting of values which are expensive
to calculate. The value is cached for the period specified in the constructor. The "getValue()"
method called by the client only returns the cached value. The protected "loadValue()" method
is only called internally to reload the cache value.

.. code-block:: java

registry.register(name(Cache.class, cache.getName(), "size"),
                  new CachedGauge<Long>(10, TimeUnit.MINUTES) {
                      @Override
                      protected Long loadValue() {
                          // assume this does something which takes a long time
                          return cache.getSize();
                      }
                  });

.. _man-core-gauges-derivative:

Derivative Gauges Copy Chapter

A derivative gauge allows you to derive values from other gauges' values:

.. code-block:: java

public class CacheSizeGauge extends DerivativeGauge<CacheStats, Long> {
    public CacheSizeGauge(Gauge<CacheStats> statsGauge) {
        super(statsGauge);
    }

    @Override
    protected Long transform(CacheStats stats) {
        return stats.getSize();
    }
}

.. _man-core-counters:

Counters

A counter is a simple incrementing and decrementing 64-bit integer:

.. code-block:: java

final Counter evictions = registry.counter(name(SessionStore.class, "cache-evictions"));
evictions.inc();
evictions.inc(3);
evictions.dec();
evictions.dec(2);

All Counter metrics start out at 0.

.. _man-core-histograms:

Histograms

A Histogram measures the distribution of values in a stream of data: e.g., the number of results
returned by a search:

.. code-block:: java

final Histogram resultCounts = registry.histogram(name(ProductDAO.class, "result-counts"));
resultCounts.update(results.size());

Histogram metrics allow you to measure not just easy things like the min, mean, max, and
standard deviation of values, but also quantiles__ like the median or 95th percentile.

.. __: http://en.wikipedia.org/wiki/Quantile

Traditionally, the way the median (or any other quantile) is calculated is to take the entire data
set, sort it, and take the value in the middle (or 1% from the end, for the 99th percentile). This
works for small data sets, or batch processing systems, but not for high-throughput, low-latency
services.

The solution for this is to sample the data as it goes through. By maintaining a small, manageable
reservoir which is statistically representative of the data stream as a whole, we can quickly and
easily calculate quantiles which are valid approximations of the actual quantiles. This technique is
called reservoir sampling.

Metrics provides a number of different Reservoir implementations, each of which is useful.

.. _man-core-histograms-uniform:

Uniform Reservoirs Copy Chapter

A histogram with a uniform reservoir produces quantiles which are valid for the entirety of the
histogram's lifetime. It will return a median value, for example, which is the median of all the
values the histogram has ever been updated with. It does this by using an algorithm called
Vitter's R__), which randomly selects values for the reservoir with linearly-decreasing
probability.

.. __: http://www.cs.umd.edu/~samir/498/vitter.pdf

Use a uniform histogram when you're interested in long-term measurements. Don't use one where you'd
want to know if the distribution of the underlying data stream has changed recently.

.. _man-core-histograms-exponential:

Exponentially Decaying Reservoirs Copy Chapter

A histogram with an exponentially decaying reservoir produces quantiles which are representative of
(roughly) the last five minutes of data. It does so by using a
forward-decaying priority reservoir__ with an exponential weighting towards newer data. Unlike the
uniform reservoir, an exponentially decaying reservoir represents recent data, allowing you to
know very quickly if the distribution of the data has changed. :ref:man-core-timers use histograms
with exponentially decaying reservoirs by default.

.. __: http://dimacs.rutgers.edu/~graham/pubs/papers/fwddecay.pdf

.. _man-core-histograms-sliding:

Sliding Window Reservoirs Copy Chapter

A histogram with a sliding window reservoir produces quantiles which are representative of the past
N measurements.

.. _man-core-histograms-sliding-time:

Sliding Time Window Reservoirs Copy Chapter

A histogram with a sliding time window reservoir produces quantiles which are strictly
representative of the past N seconds (or other time period).

.. warning::

While ``SlidingTimeWindowReservoir`` is easier to understand than
``ExponentiallyDecayingReservoir``, it is not bounded in size, so using it to sample a
high-frequency process can require a significant amount of memory. Because it records every
measurement, it's also the slowest reservoir type.

.. hint::

Try to use our new optimised version of ``SlidingTimeWindowReservoir`` called ``SlidingTimeWindowArrayReservoir``.
It brings much lower memory overhead. Also it's allocation/free patterns are different,
so GC overhead is 60x-80x lower then ``SlidingTimeWindowReservoir``. Now ``SlidingTimeWindowArrayReservoir`` is
comparable with ``ExponentiallyDecayingReservoir`` in terms GC overhead and performance.
As for required memory, ``SlidingTimeWindowArrayReservoir`` takes ~128 bits per stored measurement and you can simply
calculate required amount of heap.

Example: 10K measurements / sec with reservoir storing time of 1 minute will take
10000 * 60 * 128 / 8 = 9600000 bytes ~ 9 megabytes

.. _man-core-meters:

Meters

A meter measures the rate at which a set of events occur:

.. code-block:: java

final Meter getRequests = registry.meter(name(WebProxy.class, "get-requests", "requests"));
getRequests.mark();
getRequests.mark(requests.size());

Meters measure the rate of the events in a few different ways. The mean rate is the average rate
of events. It's generally useful for trivia, but as it represents the total rate for your
application's entire lifetime (e.g., the total number of requests handled, divided by the number of
seconds the process has been running), it doesn't offer a sense of recency. Luckily, meters also
record three different exponentially-weighted moving average rates: the 1-, 5-, and 15-minute
moving averages.

.. hint::

Just like the Unix load averages visible in ``uptime`` or ``top``.

.. _man-core-timers:

Timers

A timer is basically a :ref:histogram <man-core-histograms> of the duration of a type of event and
a :ref:meter <man-core-meters> of the rate of its occurrence.

.. code-block:: java

final Timer timer = registry.timer(name(WebProxy.class, "get-requests"));

final Timer.Context context = timer.time();
try {
    // handle request
} finally {
    context.stop();
}

.. note::

Elapsed times for it events are measured internally in nanoseconds, using Java's high-precision
``System.nanoTime()`` method. Its precision and accuracy vary depending on operating system and
hardware.

.. _man-core-sets:

Metric Sets

Metrics can also be grouped together into reusable metric sets using the MetricSet interface.
This allows library authors to provide a single entry point for the instrumentation of a wide
variety of functionality.

.. _man-core-reporters:

Reporters

Reporters are the way that your application exports all the measurements being made by its metrics.
metrics-core comes with four ways of exporting your metrics:
:ref:JMX <man-core-reporters-jmx>, :ref:console <man-core-reporters-console>,
:ref:SLF4J <man-core-reporters-slf4j>, and :ref:CSV <man-core-reporters-csv>.

.. _man-core-reporters-jmx:

JMX Copy Chapter

With JmxReporter, you can expose your metrics as JMX MBeans. To explore this you can use
VisualVM__ (which ships with most JDKs as jvisualvm) with the VisualVM-MBeans plugins installed
or JConsole (which ships with most JDKs as jconsole):

.. __: http://visualvm.java.net/

.. image:: ../metrics-visualvm.png
:alt: Metrics exposed as JMX MBeans being viewed in VisualVM's MBeans browser

.. tip::

If you double-click any of the metric properties, VisualVM will start graphing the data for that
property. Sweet, eh?

.. warning::

We don't recommend that you try to gather metrics from your production environment. JMX's RPC
API is fragile and bonkers. For development purposes and browsing, though, it can be very
useful.

To report metrics via JMX:

.. code-block:: java

final JmxReporter reporter = JmxReporter.forRegistry(registry).build();
reporter.start();

.. _man-core-reporters-console:

Console Copy Chapter

For simple benchmarks, Metrics comes with ConsoleReporter, which periodically reports all
registered metrics to the console:

.. code-block:: java

final ConsoleReporter reporter = ConsoleReporter.forRegistry(registry)
                                                .convertRatesTo(TimeUnit.SECONDS)
                                                .convertDurationsTo(TimeUnit.MILLISECONDS)
                                                .build();
reporter.start(1, TimeUnit.MINUTES);

.. _man-core-reporters-csv:

CSV Copy Chapter

For more complex benchmarks, Metrics comes with CsvReporter, which periodically appends to a set
of .csv files in a given directory:

.. code-block:: java

final CsvReporter reporter = CsvReporter.forRegistry(registry)
                                        .formatFor(Locale.US)
                                        .convertRatesTo(TimeUnit.SECONDS)
                                        .convertDurationsTo(TimeUnit.MILLISECONDS)
                                        .build(new File("~/projects/data/"));
reporter.start(1, TimeUnit.SECONDS);

For each metric registered, a .csv file will be created, and every second its state will be
written to it as a new row.

.. _man-core-reporters-slf4j:

SLF4J Copy Chapter

It's also possible to log metrics to an SLF4J logger:

.. code-block:: java

final Slf4jReporter reporter = Slf4jReporter.forRegistry(registry)
                                            .outputTo(LoggerFactory.getLogger("com.example.metrics"))
                                            .convertRatesTo(TimeUnit.SECONDS)
                                            .convertDurationsTo(TimeUnit.MILLISECONDS)
                                            .build();
reporter.start(1, TimeUnit.MINUTES);

.. _man-core-reporters-other:

Other Reporters Copy Chapter

Metrics has other reporter implementations, too:

• :ref:MetricsServlet <manual-servlets> is a servlet which not only exposes your metrics as a JSON
  object, but it also runs your health checks, performs thread dumps, and exposes valuable JVM-level
  and OS-level information.
• :ref:GraphiteReporter <manual-graphite> allows you to constantly stream metrics data to your
  Graphite servers.

File: docs/source/manual/ehcache.rst Copy Chapter

.. _manual-ehcache:

#####################
Instrumenting Ehcache
#####################

.. highlight:: text

.. rubric:: The metrics-ehcache module provides InstrumentedEhcache, a decorator for
Ehcache_ caches:

.. _Ehcache: http://ehcache.org/documentation

.. code-block:: java

final Cache c = new Cache(new CacheConfiguration("test", 100));
MANAGER.addCache(c);
this.cache = InstrumentedEhcache.instrument(registry, c);

Instrumenting an Ehcache instance creates gauges for all of the Ehcache-provided statistics:

+---------------------------+----------------------------------------------------------------------+
| hits | The number of times a requested item was found in the cache. |
+---------------------------+----------------------------------------------------------------------+
| in-memory-hits | Number of times a requested item was found in the memory store. |
+---------------------------+----------------------------------------------------------------------+
| off-heap-hits | Number of times a requested item was found in the off-heap store. |
+---------------------------+----------------------------------------------------------------------+
| on-disk-hits | Number of times a requested item was found in the disk store. |
+---------------------------+----------------------------------------------------------------------+
| misses | Number of times a requested item was not found in the cache. |
+---------------------------+----------------------------------------------------------------------+
| in-memory-misses | Number of times a requested item was not found in the memory store. |
+---------------------------+----------------------------------------------------------------------+
| off-heap-misses | Number of times a requested item was not found in the off-heap store.|
+---------------------------+----------------------------------------------------------------------+
| on-disk-misses | Number of times a requested item was not found in the disk store. |
+---------------------------+----------------------------------------------------------------------+
| objects | Number of elements stored in the cache. |
+---------------------------+----------------------------------------------------------------------+
| in-memory-objects | Number of objects in the memory store. |
+---------------------------+----------------------------------------------------------------------+
| off-heap-objects | Number of objects in the off-heap store. |
+---------------------------+----------------------------------------------------------------------+
| on-disk-objects | Number of objects in the disk store. |
+---------------------------+----------------------------------------------------------------------+
| mean-get-time | The average get time. Because ehcache supports JDK1.4.2, each get |
| | time uses System.currentTimeMillis(), rather than nanoseconds. |
| | The accuracy is thus limited. |
+---------------------------+----------------------------------------------------------------------+
| mean-search-time | The average execution time (in milliseconds) within the last sample |
| | period. |
+---------------------------+----------------------------------------------------------------------+
| eviction-count | The number of cache evictions, since the cache was created, or |
| | statistics were cleared. |
+---------------------------+----------------------------------------------------------------------+
| searches-per-second | The number of search executions that have completed in the last |
| | second. |
+---------------------------+----------------------------------------------------------------------+
| accuracy | A human readable description of the accuracy setting. One of "None", |
| | "Best Effort" or "Guaranteed". |
+---------------------------+----------------------------------------------------------------------+

It also adds full timers for the cache's get and put methods.

The metrics are all scoped to the cache's class and name, so a Cache instance named users
would have metric names like net.sf.ehcache.Cache.users.get, etc.

File: docs/source/manual/graphite.rst Copy Chapter

.. _manual-graphite:

#####################
Reporting to Graphite
#####################

The metrics-graphite module provides GraphiteReporter, which allows your application to
constantly stream metric values to a Graphite_ server:

.. _Graphite: http://graphite.wikidot.com/

.. code-block:: java

final Graphite graphite = new Graphite(new InetSocketAddress("graphite.example.com", 2003));
final GraphiteReporter reporter = GraphiteReporter.forRegistry(registry)
                                                  .prefixedWith("web1.example.com")
                                                  .convertRatesTo(TimeUnit.SECONDS)
                                                  .convertDurationsTo(TimeUnit.MILLISECONDS)
                                                  .filter(MetricFilter.ALL)
                                                  .build(graphite);
reporter.start(1, TimeUnit.MINUTES);

If you prefer to write metrics in batches using pickle, you can use the PickledGraphite:

.. code-block:: java

final PickledGraphite pickledGraphite = new PickledGraphite(new InetSocketAddress("graphite.example.com", 2004));
final GraphiteReporter reporter = GraphiteReporter.forRegistry(registry)
                                                  .prefixedWith("web1.example.com")
                                                  .convertRatesTo(TimeUnit.SECONDS)
                                                  .convertDurationsTo(TimeUnit.MILLISECONDS)
                                                  .filter(MetricFilter.ALL)
                                                  .build(pickledGraphite);
reporter.start(1, TimeUnit.MINUTES);

File: docs/source/manual/healthchecks.rst Copy Chapter

.. _man-healthchecks:

#############
Health Checks
#############

Metrics also provides you with a consistent, unified way of performing application health checks. A
health check is basically a small self-test which your application performs to verify that a
specific component or responsibility is performing correctly.

To create a health check, extend the HealthCheck class:

.. code-block:: java

public class DatabaseHealthCheck extends HealthCheck {
    private final Database database;

    public DatabaseHealthCheck(Database database) {
        this.database = database;
    }

    @Override
    protected Result check() throws Exception {
        if (database.ping()) {
            return Result.healthy();
        }
        return Result.unhealthy("Can't ping database");
    }
}

In this example, we've created a health check for a Database class on which our application
depends. Our fictitious Database class has a #ping() method, which executes a safe test
query (e.g., SELECT 1). #ping() returns true if the query returns the expected result,
returns false if it returns something else, and throws an exception if things have gone
seriously wrong.

Our DatabaseHealthCheck, then, takes a Database instance and in its #check() method,
attempts to ping the database. If it can, it returns a healthy result. If it can't, it returns
an unhealthy result.

.. note::

Exceptions thrown inside a health check's ``#check()`` method are automatically caught and
turned into unhealthy results with the full stack trace.

To register a health check, either use a HealthCheckRegistry instance:

.. code-block:: java

registry.register("database", new DatabaseHealthCheck(database));

You can also run the set of registered health checks:

.. code-block:: java

for (Entry<String, Result> entry : registry.runHealthChecks().entrySet()) {
    if (entry.getValue().isHealthy()) {
        System.out.println(entry.getKey() + ": OK");
    } else {
        System.out.println(entry.getKey() + ": FAIL");
    }
}