sbt-atmos

sbt plugin for running Typesafe Console in development.

Supports tracing of Akka projects and Play projects.

Akka projects

Add plugin

This plugin requires sbt 0.12 or 0.13.

Add the sbt-atmos plugin to project/plugins.sbt. For example:

addSbtPlugin("com.typesafe.sbt" % "sbt-atmos" % "0.3.2")

Add the atmosSettings to the project. For a .sbt build, add a line with:

atmosSettings

For a full .scala build, add these settings to your project settings.

com.typesafe.sbt.SbtAtmos.atmosSettings

For example:

import sbt._
import sbt.Keys._
import com.typesafe.sbt.SbtAtmos.{ Atmos, atmosSettings }

object SampleBuild extends Build {
  lazy val sample = Project(
    id = "sample",
    base = file("."),
    settings = Defaults.defaultSettings ++ Seq(
      name := "Sample",
      scalaVersion := "2.10.2",
      libraryDependencies += "com.typesafe.akka" %% "akka-actor" % "2.2.0"
    )
  )
  .configs(Atmos)
  .settings(atmosSettings: _*)
}

A simple sample Akka project configured with the sbt-atmos plugin is included in this repository.

Trace dependencies

The sbt-atmos plugin will automatically add a library dependency which includes Aspectj aspects for the Akka dependency being used, providing Akka is listed as a library dependency of the project.

To explicitly specify the trace dependency, use the traceAkka helper method and pass the Akka version being used. For example, add a setting like this to your build:

traceAkka("2.2.1")

The full path to this method is:

com.typesafe.sbt.SbtAtmos.traceAkka

Run with Typesafe Console

To run your application with Typesafe Console there are extra versions of the run and run-main tasks. These use the same underlying settings for the regular run tasks, and also add the configuration needed to instrument your application, and start and stop Typesafe Console.

To run the default or discovered main class use:

atmos:run

To run a specific main class:

atmos:run-main org.something.MainClass

Trace configuration

It's possible to configure which actors in your application are traced, and at what sampling rates.

The underlying configuration uses the Typesafe Config library. A configuration file is automatically created by the sbt-atmos plugin.

There are sbt settings to adjust the tracing and sampling of actors. Trace configuration is based on actor paths. For example:

import com.typesafe.sbt.SbtAtmos.Atmos
import com.typesafe.sbt.SbtAtmos.AtmosKeys.{ traceable, sampling }

traceable in Atmos := Seq(
  "/user/someActor" -> true,  // trace this actor
  "/user/actors/*"  -> true,  // trace all actors in this subtree
  "*"               -> false  // other actors are not traced
)

sampling in Atmos := Seq(
  "/user/someActor" -> 1,     // sample every trace for this actor
  "/user/actors/*"  -> 100    // sample every 100th trace in this subtree
)

Note: The default settings are to collect all traces for all actors. For applications with heavier loads you should select specific parts of the application to trace.

Configuration subsections

Actor systems are configured for tracing based on the same configuration passed on actor system creation. This allows applications with multiple actor systems to have different trace configuration for each system, just like akka configuration. The sbt-atmos plugin will automatically add trace settings for the top-level configuration. If your application creates actor systems using configuration subsections, like

val config = ConfigFactory.load()
val system = ActorSystem("name", config.getConfig("subsection"))

then these configuration subsections need to be marked for tracing too. This can be done with the includeConfig setting. For example:

AtmosKeys.includeConfig in Atmos += "subsection"

Play projects

Add plugin

Supported Play versions are 2.1.4 (with sbt 0.12), and 2.2.0 (with sbt 0.13).

Add the sbt-atmos-play plugin to project/plugins.sbt. For example:

addSbtPlugin("com.typesafe.sbt" % "sbt-atmos-play" % "0.3.2")

Add the atmosPlaySettings to the project. For a .sbt build, add a line with:

atmosPlaySettings

For a full .scala build, add these settings to your project settings.

com.typesafe.sbt.SbtAtmosPlay.atmosPlaySettings

For example:

import sbt._
import sbt.Keys._
import play.Project._
import com.typesafe.sbt.SbtAtmosPlay.atmosPlaySettings

object ApplicationBuild extends Build {
  val appName    = "traceplay"
  val appVersion = "1.0"

  val main = play.Project(appName, appVersion).settings(atmosPlaySettings: _*)
}

A simple sample Play project configured with the sbt-atmos-play plugin is included in this repository.

Run with Typesafe Console

To run your Play application with Typesafe Console there is an alternative version of the run task. This uses the same underlying settings for the regular run task, and also adds the configuration needed to instrument your application, and start and stop Typesafe Console.

For Play 2.2, there is an alternative run task, which also traces the application and starts Typesafe Console:

atmos:run

For Play 2.1, there is an alternative run command:

atmos-run

More information

For more information see the documentation for the developer version of Typesafe Console.

Feedback

We welcome your feedback and ideas for using Typesafe Console for development.

You can send feedback to the Typesafe Console mailing list, or to Typesafe Support,

License

Typesafe Console is licensed under the Typesafe Subscription Agreement and is made available through the sbt-atmos plugin for development use only.

The code for the sbt-atmos plugin is open source software licensed under the Apache 2.0 License.

For more information see Typesafe licenses.

Contribution policy

Contributions via GitHub pull requests are gladly accepted from their original author. Before we can accept pull requests, you will need to agree to the Typesafe Contributor License Agreement online, using your GitHub account.