sbt Example: Play

Below is an example for how to configure Cinnamon for Play metrics.

Note: Cinnamon supports Play 2.6 and greater.

Background

When developing Play applications it is very convenient to use Play’s development run command. However, because of the way the run command is implemented it is not possible to use Lightbend Telemetry in combination with this command. Instead you have to build the Play application as a distribution and run that - more information about this here below.

Prerequisites

The following must be installed for these instructions to work:

  • Java
  • sbt
  • Bintray credentials

Bintray credentials

Follow these instructions to set up your Bintray credentials for sbt.

Configuration

Start off by adding Cinnamon to the project/plugins.sbt file:

addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.6.15")

addSbtPlugin("com.lightbend.cinnamon" % "sbt-cinnamon" % "2.9.2")

credentials += Credentials(Path.userHome / ".lightbend" / "commercial.credentials")

resolvers += Resolver.url("lightbend-commercial",
  url("https://repo.lightbend.com/commercial-releases"))(Resolver.ivyStylePatterns)

Make sure that the credentials setting points to where you chose to create the commercial credentials file.

The next step is to amend the build.sbt to contain Cinnamon:

lazy val root = (project in file(".")).enablePlugins(PlayScala, Cinnamon)

libraryDependencies ++= Seq(
  Cinnamon.library.cinnamonCHMetrics, // only needed to use the Console reporter
  Cinnamon.library.cinnamonPlay
)

Finally you should ensure that you have a configuration file (conf/application.conf) that instructs Cinnamon on how to instrument Play. The example below enables all available Play metrics and logs output using the Console reporter:

cinnamon.application = "hello-play-telemetry"

cinnamon.play.http {

  // Create server metrics for all servers and all paths
  servers {
    "*:*" {
      paths {
        "*" {
          metrics = on
        }
      }
    }
  }

  // Create client metrics for all servers and all paths
  clients {
    "*:*" {
      paths {
        "*" {
          metrics = on
        }
      }
    }
  }
}

cinnamon.chmetrics {
  reporters += console-reporter
}

Running

When you have configured your Play application in accordance with the instructions here above you can run it. As previously explained you cannot use sbt run with the Cinnamon Agent. We still urge you to use the run command during development of the Play application. This is one of the things that make Play a true development friendly environment. When you want to test your application with telemetry you can do so with this command:

sbt runProd

Play configuration

The Play metrics can be configured to a detailed level. See the Play metrics configuration for more details.