JarCastingtrail-metrics
Trail Metrics offer a highly flexible way to gather metrics occurring along the execution of a process.
Introduction
When a function of a system is called, it is instructed to fulfil its use case by performing all operations necessary for that use case.
Upon finishing, the only information about the course of the process behind the function is the result returned by the function itself. All other information about that process is not of any interest for the caller, but might be highly valuable for business intelligence, administration or debugging purposes.
For example, the caller of the REST method addToCart(CardId cartId, ItemId itemId) does not need any information returned; the item just needs to be added to the shopping cart. But administration might want a level of response times for several sub functions called to monitor the systems latency when performing the operation. This scenario would just require plain metrics; a contextless, overall metric for the whole system would be enough.
But what if a certain customer files a complaint, that adding an item to his cart takes extremely long and sometimes even completely fails with a time out? Since a plain metric would be an average value, a single spike in latency of one sub-operation would not affect the respective monitored metric notably. And the logs of the method's application would just contain the server side message, that a client has unexpectedly ended a connection; since the operation was just long taking and caused no error on server side, it would be cumbersome to find out what went wrong.
That's where the trail comes in. The trail identifies an arbitrary set of coherent operations as a single process. So when metrics are written along that process, they become the MetricsTrail
In the example of the customer adding an item to the cart, all of the customers actions since he or she logged in might be done in the same trail. That way, when the timeout appears in the front end, an error report containing the trail's ID can be created. Using that ID, all metrics during that trail can be analyzed individually, revealing a spike in latency in a specific sub-operation when that specific user adds items to his cart.
Committing and Consuming Metrics
What is a Metric?
The Metric class is a simple POJO, consisting of:
- A freely selectable identifier, that will characterize the metric in the context it is committed in
- A type, which is one of:
- ALERT: a metric that simply alters the occurrence of a specific event, for example a user trying to authenticate with wrong credentials
- PHASE: a metric that defines the switch in phase, for example the transitions of a shopping cart from gathering products, to requesting an offer with combined prices from the seller, to a combined price being offered to customer
- METER: a metric that notifies about the exact amount a certain value has, for example the milliseconds a backend call required
- TREND: a metric that notifies about the change in amount a certain value underwent, for examle a -1/+1 every time a user found a help article useful
- A timestamp, which is auto-created
- A key->value map of attributes
How do I write Metrics to a MetricsTrail?
The MetricsTrail.commit() method accepts instances of the Metric class.
In order to have a MetricsTrail to write to anywhere in your application, use a support package that will begin MetricsTrail instances automatically, for example on incoming HTTP requests, in UI sessions, on cron task executiomns or where ever.
Most of these support packages use the ThreadLocal based approach of MetricsTrailSupport class, so writing metrics to a MetricsTrail becomes as easy as calling MetricsTrailSupport.commit() with a Metric instance as the parameter.
In case there is no suitable specialized support package, the MetricsTrailSupport can often be used as a base for custom implementations, as it only requires calls to MetricsTrailSupport.begin() and MetricsTrailSupport.end() to (un-)hook a MetricsTrail to the current thread.
How do I receive MetricsTrails?
The MetricsConsumer interface is used to create consumers to trails. The MetricsTrailConsumer class wraps an instance of MetricsConsumer, adding a whole of configurable standard functionality like:
- Asychronism with retry, so committing a metric to a consumer will never cause an exception in a committing thread
- Gates to hold back Metric instance committing to a trail until a certain type of Metric occurs
- Filters to prevent certain types of Metric instances to be committed to trails
MetricsTrailConsumer instances can be hooked directly to a MetricsTrail instance.
When using a support package, the consumer is often given to some kind of registry though which will ensure that the consumer is automatically hooked to all trails that are created. In case of MetricsTrailSupport for example, a simple MetricsTrailSupport.hook() call will hook a MetricsTrailConsumer to all thread based trails.
The adapter packages provide a lot of reference implementations for standard consumers of metrics, like logs, web services, databases and so on.
I have an application i want to integrate MetricTrails into, how do i get started?
First, choose all the support packages that fit your application, or hook the basic trail-metrics-support yourself. It will enable your application to create metrics in all situations that might occur. Then simply create as many metrics as required and commit them.
To consume the created metrics, refer to the adaptor packages for base implementations of consumers and choose as many as needed. Alternatively, implement the MetricsConsumer interface yourself.