OverOps (Takipi)

We have partnered with OverOps (formerly Takipi) to provide a plugin with Lightbend Telemetry for Akka. In addition to processing metrics, OverOps handles events natively. When an event occurs, it triggers a snapshot of the stack trace, which is then made available in the OverOps dashboard.

Cinnamon dependency

Cinnamon dependencies for the OverOps plugin need to be included in your build. The Cinnamon modules are available in the Lightbend commercial releases repository. The OverOps SDK module is available in a separate repository.

Make sure you have set up your build to use the Cinnamon Agent.

Add the Takipi SDK repository to your build:

sbt
resolvers += "takipi-sdk" at "https://dl.bintray.com/takipi/maven"
Maven
<repository>
  <id>takipi-sdk</id>
  <name>Takipi SDK</name>
  <url>https://dl.bintray.com/takipi/maven</url>
</repository>
Gradle
repositories {
  maven {
    url "https://dl.bintray.com/takipi/maven"
  }
}

Add the Cinnamon Takipi dependency to your build:

sbt
libraryDependencies += "com.lightbend.cinnamon" %% "cinnamon-takipi" % "2.5.3"
Maven
<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-takipi_2.11</artifactId>
  <version>2.5.3</version>
</dependency>
Gradle
dependencies {
  compile group: "com.lightbend.cinnamon", name: cinnamon-takipi_2.11, version: "2.5.3"
}

Cinnamon configuration

Since your application could be creating thousands or even tens of thousands of actors, the default setting is to not instrument any actors. You need to select which actors to instrument in your Cinnamon configuration, which is the same configuration as used to configure your ActorSystem. The default configuration is in application.conf.

Note: Actors are not instrumented automatically. Actors must have instrumentation explicitly enabled in configuration.

A simple example configuration to instrument all actors in the system grouped by actor class looks like this:

cinnamon.akka {
  actors {
    "/user/*" {
      report-by = class
    }
  }
}

See configuration for more information about how Actor telemetry can be configured.

Running with OverOps

You need an account at OverOps. Sign up for one if you don’t already have this.

The OverOps dashboard has instructions for getting OverOps installed on machines. You can also follow the steps in the OverOps documentation.

Once OverOps is installed on a machine, the Takipi agent needs to be connected to a JVM. This is done by adding an extra argument on JVM startup:

-agentlib:TakipiAgent

Note The Cinnamon agent must also be added as an argument to the JVM. See instructions for how to configure this.

sbt process

To instrument Akka during development, the Takipi agent can be added to the sbt process. Depending on the sbt script you have installed, JVM arguments are normally set by adding an extra -J prefix. For example:

sbt -J-agentlib:TakipiAgent

By adding the Takipi agent to sbt, all in-process runs will be instrumented.

sbt run

The Takipi agent can be added to just the running of an application by configuring the run task. The run needs to be in a forked JVM so that startup arguments can be added. The following settings can be added to projects to connect the Takipi agent on run:

fork in run := true
javaOptions in run += "-agentlib:TakipiAgent"

Note: The run task provided by the Play sbt plugin, which supports quick reloads during development, does not support a forked run mode. Use the sbt-native-packager approach for attaching Takipi to Play applications during development.

sbt-native-packager

If you’re using sbt-native-packager to create distributions, then the following sbt setting can be used to enable the Takipi agent in the start script:

bashScriptExtraDefines += """addJava -agentlib:TakipiAgent"""

And this setting can be used to set the application name seen by Takipi:

bashScriptExtraDefines += s"""addJava -Dtakipi.name=${name.value}"""

To attach the Takipi agent to a staged distribution as needed, you can build the distribution with sbt stage and then start your application with an extra JVM argument for the Takipi agent. For example:

sbt stage
target/universal/stage/bin/<your-application-name> -J-agentlib:TakipiAgent

Maven options

To add the Takipi agent to Maven, include it in the Maven options environment variable:

export MAVEN_OPTS="$MAVEN_OPTS -agentlib:TakipiAgent"