Do You Have To Register Your Kamon

Metrics Module

The Kamon Metrics module is responsible of controlling the registration of entities existence tracked either by user code or by instrumentation provided with other Kamon modules, also as providing some necessary infrastructure similar filtering, configuring instrument factories and dispatching metrics subscriptions to all interested parties.

From a very general perspective, you can think of the Metrics module equally a big map total of entities and instruments associated with them that collects all the available information and sends it to subscribers on a stock-still interval, known equally a tick interval.

Entities

In the early stages of our Metrics module, we realized that the most common case when measuring the functioning of a given application is to have sets of metrics related to a single entity, and, many occurrences of the aforementioned prepare of metrics as similar entities exist in the application. For example, if you are monitoring a thread pool you will want to get the total number of threads, the active thread counts and the queue size (among other metrics, of class), and if you have five thread pools in your application you will want to get the exact same metrics set up for each thread puddle. In Kamon, that will interpret to having five entities with dissimilar names just with the same category of thread-pool, all sharing the same ready of metrics.

The regular operation of the Metrics module consists of basically two stages, as described in this simple diagram:

On the left, we have the real time recording side of the process where Entities work as the keys in that "big map" that we mentioned before, pointing to an entity recorder that contains all the metric instruments associated with that given entity. This is the mutable side of our Metrics infrastructure, where everything gets updated equally your application operates and its behavior is being measured. Upon every tick, the Metrics extension collects the metrics of all bachelor entity recorders and generates entity snapshots that correspond all the values recorded since the terminal tick. This side is completely immutable and safely shareable, in fact, all the parties (ordinarily backend modules) interested in the same entity volition receive the verbal same instances of the given entity snapshots (immutability FTW :D).

All entities have iii identifying backdrop:

a proper noun, that should be unique amidst entities in the same category. In the thread pools monitoring case mentioned above you might have a thread pool named "jdbc-pool" and another one named "netty-puddle" and both will have their own, separate entity recorders.
a category, that should be shared among similar entities. Following the example, both "jdbc-pool" and "netty-pool" have the same set of metrics (puddle size, number of agile threads, etc.) and should share the same category of "thread-pool".
tags, which are optional. The tags are a simple map of Cord keys to String values, used to provide dimensions that encode boosted data about the entity being tracked.

If you accept two entities with the same proper name and category but different tags then they are effectively two different entities in Kamon, each with its own, divide entity recorder. Typically, tags are used to provide additional data nigh the entity beingness measured; the most common example establish when talking most tags is that of trying to measure out how an application behaves when using algorithm "10" or algorithm "Y" to perform a certain job. You could only choose one of the algorithms randomly in your application and measure both of them with histograms named "some-chore" and accept a tag named "algorithm" with value "Ten" or "Y" depending on which algorithm was selected. Inside Kamon the tags wont have a big result, just if this information tin can be pushed to your metrics backend of selection information technology volition greatly increase your ability to piece and die with the available metrics.

Built-in Entity Recorders

If you are coming from using another metrics library it is very probable that yous are non used to the idea of having these groups of metrics (entity recorders) but rather simple and direct instruments like histograms, counters, gauges and so on. More than and so, sometimes you just want to measure a very simple feature of your application and grouping it with another metrics to create a new entity recorder just makes no sense; for these cases Kamon ships with entity recorders that contain a unmarried musical instrument (histogram, gauge, counter or min max counter) and are automatically managed past the metrics module.

Finer, you don't demand to know that these entity recorders exists as they are a detail implementation within Kamon, merely we mention it to brand clear the betoken that our metrics module works just with entities and entities have groups of metrics which, as in this case, might have simply a single metric inside. Delight accept a wait at the recording metrics section to larn how you can get a hold whatsoever of this recorders using the metrics module.

Defining your ain Entity Recorder

Basically, annihilation that implements kamon.metric.EntityRecorder tin work every bit en entity recorder in Kamon and chances are that you will want to create your own entity recorders and personalize the manner you use Kamon accordingly to your needs. For such purpose Kamon offers the kamon.metric.GenericEntityRecorder base grade which facilitates the definition of entity recorders, it is not required for you lot to utilise this base grade but it is definitely the simplest style to create a custom entity recorder class. Here is a brief example of creating an thespian-like entity using the provided facilities (in fact, it's pretty much the same as the actor entity recorder provided with the kamon-akka module):

Scala
Coffee
                              class ActorMetrics(instrumentFactory: InstrumentFactory) extends GenericEntityRecorder(instrumentFactory) {   val timeInMailbox = histogram("time-in-mailbox", Time.Nanoseconds)   val processingTime = histogram("processing-time", Fourth dimension.Nanoseconds)   val mailboxSize = minMaxCounter("mailbox-size")   val errors = counter("errors") }  object ActorMetrics extends EntityRecorderFactory[ActorMetrics] {   def category: String = "thespian"   def createRecorder(instrumentFactory: InstrumentFactory): ActorMetrics = new ActorMetrics(instrumentFactory) }                                          
                                                /**    *  Also the inherent verbosity of Coffee, this code does exactly the aforementioned    *  as it's Scala counter part.    */   public static form ActorMetrics extends GenericEntityRecorder {     private final Histogram timeInMailbox;     private final Histogram processingTime;     private final MinMaxCounter mailboxSize;     private terminal Counter errors;      public ActorMetrics(InstrumentFactory instrumentFactory) {       super(instrumentFactory);        timeInMailbox = histogram("fourth dimension-in-mailbox", Time.Nanoseconds());       processingTime = histogram("processing-time", Time.Nanoseconds());       mailboxSize = minMaxCounter("mailbox-size");       errors = counter("errors");     }      public Histogram timeInMailbox() {       return timeInMailbox;     }      public Histogram processingTime() {       return processingTime;     }      public MinMaxCounter mailboxSize() {       render mailboxSize;     }      public Counter errors() {       render errors;     }      static concluding String Category = "thespian";     static terminal EntityRecorderFactory<ActorMetrics> Factory = new EntityRecorderFactory<ActorMetrics>() {        @Override       public String category() {         return Category;       }        @Override       public ActorMetrics createRecorder(InstrumentFactory instrumentFactory) {         return new ActorMetrics(instrumentFactory);       }     };   }                                          

The names provided when creating your histograms will exist the same names included in the entity snapshots sent to the subscribers interested in your entity. Additionally to the metric names, yous tin can provide further configuration to the instrument being created, similar in this case where we are specifying that the numbers that we plan to store in the timeInMailbox and processingTime metrics stand for fourth dimension in nanoseconds. If you don't provide any farther configuration then a prepare of default values will be used. Please read the Instrument Factory section for details on how the instruments are configured.

At present, you might exist asking yourself, what is that EntityRecoderFactory for? Well, with Kamon you volition never create an instance of the entity recorders yourself merely rather ask Kamon to create for your and Kamon will do it only if it is necessary. If you lot ask Kamon v times for the same entity and so a new entity recorder will exist created during the kickoff call and the same entity recorder volition be returned in all subsequent calls. Additionally, Kamon will provide your custom entity recorder with an instrument factory specifically configured for your entity's category, which allows you to later customize parameters of it'due south instruments from the configuration file. See the instruments factory department bellow to empathise how that works and also the recording metrics section to learn how to use your custom entity recorder.

Filtering Entities

We provide instrumentation for several libraries that volition automatically measure and record metrics for you lot, that'due south nice, but we know that there is no win on blindly monitoring every entity that shows up in your application, that'south why nosotros provide entity filters. The concept of filtering is very simple: for a given category a set of includes and excludes patterns are read from the configuration file and all entities that match at least 1 include pattern and do not match any exclude patterns volition be accepted. Additionally, the kamon.metric.track-unmatched-entities setting decides whether to track or not the entities that do not match any includes or excludes.

application.conf
                          kamon.metric.filters {   akka-dispatcher {     includes = [ "**" ]     excludes = [ ]   }    akka-histrion {     includes = [ "my-app/user/job-managing director", "my-app/user/worker-*" ]     excludes = [ "my-app/system/**", "my-app/user/worker-helper" ]   } }                                    

Equally shown in the example configuration file above, all filters are divers under the kamon.metric.filters.$category_name configuration key. With the case filters provided, all the entities with category akka-dispatcher will be included, only no entities with category akka-actor and a proper name matching the my-app/organisation/** pattern will e'er exist tracked by Kamon. To reach this filtering behavior all of the modules provided by Kamon that automatically annals entities with the metric module will programatically call Kamon.metrics.shouldTrack(..) to determine if the entity should be registered or not, and you lot can do that besides if desired.

The pattern matcher included in Kamon is a very simple implementation of GLOB pattern matcher that allows the post-obit constructs:

* match whatever number of characters up to the adjacent '/' character found in the entity name.
? match exactly one grapheme, other than '/'.
** friction match any number of characters, regardless of any '/' character found afterwards this wildcard.
verbal entity name match if no wildcards are provided.

Instrument Factories

Every bit you have noticed from the previous section, constructing a entity recorder based on the GenericEntityRecorder form provided by Kamon requires you to supply a InstrumentFactory which is responsible of creating the actual histograms, min-max-counters, gauges or counters that you lot will include in your entity recorder. When doing managed registration, Kamon will retrieve the correct instrument factory and supply information technology to your .createRecorder(..) implementation whereas if you are doing manual registration you will demand to find or create an instrument factory yourself. When the Metrics module starts it will read the available configurations and generate instrument factories that follow this order of priorities when configuring an instrument (top wins):

Any configuration provided nether the kamon.metric.instrument-settings.$category.$metric-proper noun configuration fundamental.
Any configuration provided by code when creating the entity recorder.
Default configurations for each instrument type in the kamon.metric.default-musical instrument-settings configuration key.

All three sources of settings will exist merged to define the actual configuration to be used for any given musical instrument created by Kamon.

For example, changing the refresh interval of the mailbox-size min-max-counter for actors, as divers in the example above we would need to provide the following configuration:

awarding.conf
                          kamon.metric.instrument-settings {   player.mailbox-size {     refresh-interval = 250 ms   } }                                    

Since no boosted settings were provided by lawmaking or configuration for this category/metric combination, the dynamic range settings volition exist the default values defined in the kamon.metric.default-instrument-settings.min-max-counter configuration key.