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 Kanela Agent.
The Kamon Annotation module is currently available for Scala 2.11, 2.12 and 2.13.
Supported releases and dependencies are shown below.
| kamon-annotation | status | jdk | scala |
|---|---|---|---|
| 2.0.1 | stable | 1.8+ | 2.11, 2.12, 2.13 |
To get started with SBT, simply add the following to your build.sbt file:
libraryDependencies += "io.kamon" %% "kamon-annotation-api" % "2.0.1"It is necessary to tell Kamon where to search for annotated classes using the kanela.modules.annotation.within configuration
setting. For example, if you want to process annotations on all classes withing the my.company package, the following
settings should be added to your application.conf file:
kanela.modules.annotation {
within += "my.company.*"
}
Creating Spans is one of the most basic tasks you would want to perform to start monitoring your application using Kamon
and the @Trace annotation allow you to do just that:
-
@Trace: Creates a new Span every time the method is called and automatically finished once the method returns. If the annotated method returns a Scala Future or a CompletionStage, the Span will be finished when the Future/CompletionStage finishes.
-
@CustomizeInnerSpan: Tells Kamon to use the provided customizations when any Span is created within the Scope of the annotated method. This is specially useful when you want to customize the operation name of Spans that are automatically created by Kamon (e.g. customizing JDBC operation names)
Additionally to manipulating Spans, this module can automatically track metrics as the annotated methods execute. The available annotations are:
-
@Count: Creates a Counter that tracks invocations of the annotated method.
-
@Time: Creates a Timer that tracks the latency of each invocation of the annotated method. If the annotated method returns a Scala Future or a CompletionStage, the Timer will be stopped when the Future/CompletionStage finishes.
-
@Histogram: Creates a Histogram that tracks the values returned by the annotated method. Obviously, only methods returning numeric values are accepted.
-
@Gauge: Creates a Gauge that tracks the last returned value by the annotated method.
-
@TrackConcurrency: Creates a Range Sampler that is incremented when the annotated method starts executing and decremented when it finishes. If the annotated method returns a Scala Future or a CompletionStage, the Timer will be stopped when the Future/CompletionStage finishes.
The name and 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.