The Annotation module provides a set of annotations that allow you to easily integrate Kamon's metrics and tracing facilities with your application.
The kamon-annotation module require you to start your application using the AspectJ Weaver Agent. Kamon will warn you at startup if you failed to do so.
Enabling Annotation Support
Besides starting your application with the AspectJ Weaver Agent, there are two additional steps required to use annotations. First you must add the
@EnableKamon annotation to the classes you would like to be scanned for any of the provided annotations, otherwise the rest of the annotations described bellow wont be able to work at all.
Manipulating Traces and Segments
Delimiting traces and segments are one of the most basic tasks you would want to perform to start monitoring your application using Kamon, and the
@Segment annotations allow you to do just that:
- @Trace: when a method is marked with this annotation a new Trace will be started every time the method is called and automatically finished once the method returns. Also, the generated
TraceContextbecomes the current context while the method is executing, making it possible to propagate it at will.
- @Segment: when a method is marked with this annotation a new Segment will be created only if there is a current
TraceContextwhile the annotated method is called.
Additionally to manipulating traces and segments, the
kamon-annotation module provides annotations that can be used to create Counters, Histograms and MinMaxCounters that are automatically updated as the annotated methods execute. These annotations are:
@Time: when a method is marked with this annotation Kamon will create a Histogram tracking the latency of each invocation to the method. Please keep in mind that in most situations you might want to use
@Segmentif you are tracking some functionality that is executed within a trace.
@Histogram: when a method is marked with this annotation Kamon will create a Histogram that stores the values returned every time the method is invoked. Obviously, only methods returning numeric values are accepted.
@Count: when a method is marked with this annotation Kamon will be create a Counter and automatically increment it every time the method is invoked.
@MinMaxCount: when a method is marked with this annotation Kamon will be create a MinMaxCounter and automatically increment it every time method is invoked and decremented when the method returns.
EL Expression Support
tags properties are evaluated as EL expressions for all annotations that manipulate instruments.
Annotations are not inherited, regardless of them being declared on a parent class or an implemented interface method. The root causes of that limitation, according to the JLS, are:
- Non-type annotations are not inherited,
- Annotations on types are only inherited if they have the @Inherited meta-annotation,
- Annotations on interfaces are not inherited irrespective to having the @Inherited meta-annotation.