<commit_before>.. _manual-core:

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

.. highlight:: text

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

* 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`.
* :ref:`man-core-healthchecks`
* Reporting metrics values via :ref:`JMX <man-core-reporters-jmx>`, the
  :ref:`console <man-core-reporters-console>`, and :ref:`CSV <man-core-reporters-csv>` files.

All metrics are created via either the ``Metrics`` class or a ``MetricsRegistry``. If your
application is running alongside other applications in a single JVM instance (e.g., multiple WARs
deployed to an application server), you should use per-application ``MetricsRegistry`` instances. If
your application is the sole occupant of the JVM instance (e.g., a Dropwizard_ application), feel
free to use the ``static`` factory methods on ``Metrics``.

.. _Dropwizard: http://dropwizard.codahale.com/

For this documentation, we'll assume you're using ``Metrics``, but the interfaces are much the same.

.. _man-core-names:

Metric Names
============

Each metric has a unique *metric name*, which consists of four pieces of information:

Group
  The top-level grouping of the metric. When a metric belongs to a class, this defaults to the
  class's *package name* (e.g., ``com.example.proj.auth``).
Type
  The second-level grouping of the metric. When a metric belongs to a class, this defaults to the
  class's *name* (e.g., ``SessionStore``).
Name
  A short name describing the metric's purpose (e.g., ``session-count``).
Scope
  An optional name describing the metric's scope. Useful for when you have multiple instances of a
  class.

The factory methods on ``Metrics`` and ``MetricsRegistry`` will accept either class/name,
class/name/scope, or ``MetricName`` instances with arbitrary inputs.


.. _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

    Metrics.newGauge(SessionStore.class, "cache-evictions", new Gauge<Integer>() {
        @Override
        public Integer value() {
            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
----------

Given that many third-party library often expose metrics only via JMX, Metrics provides the
``JmxGauge`` 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

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

.. todo:: document RatioGauge

.. todo:: document PercentGauge

.. _man-core-counters:

Counters
========

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

.. code-block:: java

    final Counter evictions = Metrics.newCounter(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:<commit_msg>Added docs for ratio and percent gauges.<commit_after>.. _manual-core:

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

.. highlight:: text

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

* 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`.
* :ref:`man-core-healthchecks`
* Reporting metrics values via :ref:`JMX <man-core-reporters-jmx>`, the
  :ref:`console <man-core-reporters-console>`, and :ref:`CSV <man-core-reporters-csv>` files.

All metrics are created via either the ``Metrics`` class or a ``MetricsRegistry``. If your
application is running alongside other applications in a single JVM instance (e.g., multiple WARs
deployed to an application server), you should use per-application ``MetricsRegistry`` instances. If
your application is the sole occupant of the JVM instance (e.g., a Dropwizard_ application), feel
free to use the ``static`` factory methods on ``Metrics``.

.. _Dropwizard: http://dropwizard.codahale.com/

For this documentation, we'll assume you're using ``Metrics``, but the interfaces are much the same.

.. _man-core-names:

Metric Names
============

Each metric has a unique *metric name*, which consists of four pieces of information:

Group
  The top-level grouping of the metric. When a metric belongs to a class, this defaults to the
  class's *package name* (e.g., ``com.example.proj.auth``).
Type
  The second-level grouping of the metric. When a metric belongs to a class, this defaults to the
  class's *name* (e.g., ``SessionStore``).
Name
  A short name describing the metric's purpose (e.g., ``session-count``).
Scope
  An optional name describing the metric's scope. Useful for when you have multiple instances of a
  class.

The factory methods on ``Metrics`` and ``MetricsRegistry`` will accept either class/name,
class/name/scope, or ``MetricName`` instances with arbitrary inputs.


.. _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

    Metrics.newGauge(SessionStore.class, "cache-evictions", new Gauge<Integer>() {
        @Override
        public Integer value() {
            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
----------

Given that many third-party library often expose metrics only via JMX, Metrics provides the
``JmxGauge`` 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

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


Ratio Gauges
------------

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;
        }

        public double getNumerator() {
            return hits.oneMinuteRate();
        }

        public double getDenominator() {
            return calls.oneMinuteRate();
        }
    }

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

Percent Gauges
--------------

A percent gauge is a ratio gauge where the result is normalized to a value between 0 and 100. It has
the same interface as a ratio gauge.

.. _man-core-counters:

Counters
========

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

.. code-block:: java

    final Counter evictions = Metrics.newCounter(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:
{'fraction_non_alphanumeric': 0.12026862026862027, 'fraction_numerical': 0.0017094017094017094, 'mean_word_length': 3.731946851530907, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3279486', 'n_tokens_mistral': 2386, 'n_tokens_neox': 2296, 'n_words': 932}