kamon.metric

Instrument that tracks a monotonically increasing value.

A distribution of values observed by an instrument. All Kamon distributions are based on the HdrHistogram and as such, they represent a distribution of values within a configured range and precision. By default, all instruments that generate distributions are configured to accept 1% error margin, meaning that all recorded values are adjusted to the bucket whose value is up to 1% away from the original value.

Distributions only expose data for non-empty buckets/percentiles.

Describes the dynamic range in which a histogram can operate. Kamon uses the HdrHistogram under the hood to power all histogram-based metrics and such implementation requires to setup a dynamic range in advance so that the necessary data structures can be created before hand, a DynamicRange instance provides the necessary settings to create those data structures. There are three defining characteristics in a Dynamic Range:

The lowest discernible value limits the smallest value that can be discerned within the range. E.g. if you are tracking latency for a range between 0 and 3.6e+12 (one hour in nanoseconds), it might be the case that you will never experience measurements below 1 microsecond, and thus, all buckets created to cover the range between 0 and 1000 nanoseconds are never used. Setting a lowest discernible value of 1000 will prevent the allocation of buckets for the range between 0 and 1000, saving a bit of space.

The highest trackable value sets the upper limit in the range covered by a Histogram. Any value bigger than this might not be recorded in a Histogram.

And finally, the number of significant value digits which define the precision with which the range will be covered. One significant value digit gives 10% error margin, two significant value digits give 1% error margin which is the default in Kamon and three significant value digits give 0.1% error margin. Even though it is possible to have even smaller error margin, it proves impractical to try to do so given the memory requirements of such configuration.

Instrument that tracks the latest observed value of a given measure.

Instrument that tracks the distribution of values within a configured range and precision.

Base user-facing API for all metric instruments in Kamon.

Utility class for handling groups of instruments that should be created and removed together. This becomes specially handy when using several instruments to track different aspects of the same component. For example, when tracking metrics on a thread pool you will want to request several instruments to track different aspects: the pool size, the number of submitted tasks, the queue size and so on, and all of those instruments should share common tags that are specific to the instrumented thread pool; additionally, once said thread pool is shutdown, all of those instruments should be removed together. This class makes it simpler to keep track of all of those related instruments and remove them together when necessary.

A MeasurementUnit is a simple representation of the dimension and magnitude of a quantity being measured, such as "Time in Seconds" or "Information in Kilobytes". The main use of these units is done by the metric instruments; when an instrument has a specified MeasurementUnit the reporters can apply scaling in case it's necessary to meet the backend's requirements.

Describes a property of a system to be measured, and contains all the necessary information to create the actual instrument instances used to measure and record said property. Practically, a Metric can be seen as a group instruments that measure different dimensions (via tags) of the same property of the system.

All instruments belonging to a given metric share the same settings and only differ from each other by the unique combination of tags used to create them.

Exposes APIs for creating metrics, using a MetricRegistry as the underlying source of those metrics. Not all possible combinations of parameters to build metrics are exposed through this interface, but it is expected to cover all the common cases.

Creates new metric instances taking default and custom settings into account. This class only handles the creation and configuration of metrics and does not do any effort on checking whether a metric has already been created or not; that kind of verification is handled on the Kamon metric registry.

Handles creation and snapshotting of metrics. If a metric is created twice, the very same instance will be returned. If an attempt to create an existent metric with different settings is made, the new settings are ignored in favor of those of the already registered metric.

Contains snapshots of all known instruments for a given metric. Instances of this class are meant to be exposed to metric reporters via the PeriodSnapshot.

Contains immutable snapshots of all metrics and the values recorded on their instruments for a given period of time.

Instrument that tracks the behavior of a variable that can increase and decrease over time. A range sampler keeps track of the observed minimum and maximum values for the tracked variable and is constantly recording and resetting those indicators to the current variable value to get the most descriptive possible approximation of the behavior presented by the variable.

When a snapshot is taken, this instrument generates a distribution of values observed which is guaranteed to have the minimum and maximum values of the observed variable as well as several samples across time since the last snapshot.

Describes the tagging operations that can be performed on an metric or instrument instance. The tags on the returned instrument are the result of combining any existent tags on the instrument with the newly provided tags, overriding previous tags if needed.

Since metrics do not have tags themselves (only instruments do), the returned instruments of tagging operations on metrics only have the provided tags.

Instrument that tracks the distribution of latency values within a configured range and precision. Timers are just a special case of histograms that provide special APIs dedicated to recording latency measurements.