Scala Java Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
project
src
.gitignore
.travis.yml
CONTRIBUTING.md
LICENSE
README.md
build.sbt
travis-test.sh
version.sbt

README.md

Annotation Module Build Status

Gitter

kamon-annotation Maven Central

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 @Trace and @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 TraceContext becomes 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 TraceContext while the annotated method is called.

Manipulating Instruments

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 @Segment if 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

The name and tags properties are evaluated as EL expressions for all annotations that manipulate instruments.

Limitations

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.