Instrumentation

Marking traceable messages

Scala

All you need is to mark all traceable messages your system uses with TracingSupport trait and mix all actors from which you want to annotate your traces with ActorTracing.

Java

While you can access all tracing features from Java API, it can be confusing sometimes.

You have two options on how to mark your traceable messages:

• extend japi.TracingSupport
• implement BaseTracingSupport and it's methods as it done in japi.TracingSupport

To access extension itself, define trace field:

TracingExtensionImpl trace = (TracingExtensionImpl) TracingExtension.apply(context().system());

Additional steps

Play

TracingSettings should be mixed in to your application's global settings:

object Global extends TracingSettings

Use PlayActorTracing instead of ActorTracing. Additionally, you can mix PlayControllerTracing in to controllers to support tracing features.

Spray

Routes handling traced requests should be changed to use tracing directives.

Tracing directives are supplied by TracingDirectives trait. It should be mixed in to Spray service actor. Then you can use tracedHandleWith and tracedComplete directives which do exactly the same thing as original handleWith and complete but also enable tracing.

Firstly, both directives extract tracing headers from incoming HTTP request. Such headers can be set by zipkin-compatible service (Finagle, for example) and allow to continue external trace. Then, incoming request is sampled and passed into inner route. In case of tracedComplete, only requests with explicit tracing headers are processed (it doesn't have access to unmarshalled request), so tracedHandleWith should be preferred. After server response, trace is automatically finished.

Other

If you not using Play or Spray, sampling needs to be instrumented explicitly using trace.sample(msg, serviceName, rpcName). It's recommended to call this method right after message was received by your actor system. Sampling rate can be changed using akka.tracing.sample-rate config parameter or disabled by akka.tracing.enabled key.

Annotating traces

There are several methods allowing you to annotate traces:

1. trace.record(msg, annotation) - attaches string annotation to trace. Such annotation can be used by annotation filter in Web UI.
2. trace.recordKeyValue(msg, key, value) - annotates trace by key-value pair, where value can be represented by String, Short, Int, Long, Boolean, Double or Array[Byte]. This kind of annotations can be used by key-value filter in Web UI.
3. trace.recordException(msg, exception) - writes exception's stack trace to trace.

Customising names

Request's class simple name is used as a span name by default. You can change it by overriding BaseTracingSupport.spanName method. Service name written to span can be changed by overriding ActorTracing.serviceName.

Submitting

The extension submits spans related to specific messages only after they are marked with ServerSend annotation. It can be done by calling trace.record(msg, TracingAnnotations.ServerSend).

Examples

• activator template showing Play integration;
• activator template showing Scala and Java APIs, Spray integration;
• Spray integration
• Scala API
• Java API