Typesafe Activator

Akka Tracing

Akka Tracing

Lev Khomich
December 25, 2014
akka spray tracing sample scala java

Set of examples showing you how to enable tracing in your Akka application. Template covers Scala and Java API and Spray integration. You will need to install Twitter's Zipkin using included script.

How to get "Akka Tracing" on your computer

There are several ways to get this template.

Option 1: Choose activator-akka-tracing in the Typesafe Activator UI.

Already have Typesafe Activator (get it here)? Launch the UI then search for activator-akka-tracing in the list of templates.

Option 2: Download the activator-akka-tracing project as a zip archive

If you haven't installed Activator, you can get the code by downloading the template bundle for activator-akka-tracing.

  1. Download the Template Bundle for "Akka Tracing"
  2. Extract the downloaded zip file to your system
  3. The bundle includes a small bootstrap script that can start Activator. To start Typesafe Activator's UI:

    In your File Explorer, navigate into the directory that the template was extracted to, right-click on the file named "activator.bat", then select "Open", and if prompted with a warning, click to continue:

    Or from a command line:

     C:\Users\typesafe\activator-akka-tracing> activator ui 
    This will start Typesafe Activator and open this template in your browser.

Option 3: Create a activator-akka-tracing project from the command line

If you have Typesafe Activator, use its command line mode to create a new project from this template. Type activator new PROJECTNAME activator-akka-tracing on the command line.

Option 4: View the template source

The creator of this template maintains it at https://github.com/levkhomich/activator-akka-tracing#master.

Option 5: Preview the tutorial below

We've included the text of this template's tutorial below, but it may work better if you view it inside Activator on your computer. Activator tutorials are often designed to be interactive.

Preview the tutorial


This tutorial will show you how to trace messages inside Akka system. You will be guided through the tracing basics, sampling, trace logging, hierarchical calls and spray integration. To see actual results you will need to have Zipkin installed. Don't worry, template contains script that installs and runs it.

Akka Tracing

It is an Akka distributed tracing extension which can be used as performance diagnostics and debugging tool. Distributed tracing approach used by Zipkin (which it is based on) provides synergy with akka-remote and akka-cluster. Extension integrates with Finagle services, Spray toolkit (covered in this template) and Play framework (see activator-akka-tracing).


Zipkin is a distributed tracing system that helps to gather timing data for all the disparate services. It manages both the collection and lookup of this data through a Collector and a Query service. Zipkin was modelled after the Google Dapper paper.

But it's better to see once:

Template overview

This template consists of several parts:

Before running examples you will need to run Zipkin server. This can be achieved by running template's sbt tasks, or by running "zipkin.Start" main class from Activator's run menu. On the first run, Zipkin will be cloned from it's official repo to project's dir, then, in 5-10 minutes, it will be built and ready to go. After server launch, you can press Stop button in Activator's UI (Zipkin will continue running in separate threads).

Use "zipkin.Stop" or corresponding SBT task to stop tracing server.

Short description of template's SBT tasks:

  • sbt zipkin-start launches zipkin-collector, zipkin-query and zipkin-web. Zipkin Web UI will be available at http://localhost:8080.
  • sbt zipkin-stop stops all running zipkin services.
  • sbt zipkin-update updates installed Zipkin.

Tracing overview

Every message's trace lifecycle consists of several stages:

  1. Sampling. Before actual trace is created, message needs to be successfully sampled. Such mechanism allows setup tracing extension to sample only some part of messages to reduce overhead when used in production environment.
  2. Annotating. Any (created) trace can be annotated by basic and binary annotations. Basic annotations contain timestamp and description and can be displayed in timeline. Binary annotations are key-value pairs attached to trace itself.
  3. Submitting. After some message was explicitly marked as response to traced message, corresponding trace is sent to (external) collector service. If response remains unspecified, trace will be sent anyway after some timeout. Any annotations written to already submitted trace are ignored.

Tracing API


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.


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());


Sampling is performed using trace.sample(msg, serviceName, rpcName) method. 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.

Trace annotations

There are several methods allowing you to annotate traces:

  1. trace.record(msg, annotation) - attaches string annotation to message trace timeline. Such annotations 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.


After you mark that message processing was finished by marking response with someMessage.asResponseTo(request) or, if you have no response, with trace.finish(request). Corresponding trace will be closed and submitted to collector service.

Project setup


Include extension to the list of your project's dependencies:

libraryDependencies += "com.github.levkhomich" %% "akka-tracing-core" % "0.4"

or, if you want to experiment with snapshot:

resolvers += "Sonatype snapshots" at "http://oss.sonatype.org/content/repositories/snapshots/"

libraryDependencies += "com.github.levkhomich" %% "akka-tracing-core" % "0.5-SNAPSHOT" changing()

Typesafe config

You will need to define collector's endpoint:

akka.tracing {
  host = "localhost"
  port = 9410 # default

Also you can setup extension to be initialized with actor system (it's not required, though):

akka.extensions += "com.github.levkhomich.akka.tracing.TracingExtension"


For more information about Akka Tracing Extension, please refer to project's github page and wiki.

For more information about Zipkin, you can explore Zipkin project page or ask questions in the Zipkin user group.

If you have any suggestions or want to ask about project, feel free to contact me via twitter.

comments powered by Disqus