Gradle Example: Play

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

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
  • Gradle
  • Bintray credentials

Bintray credentials

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

Modifications

The modifications below are required to enable telemetry.

build.gradle

Add a build.gradle file with the following content:

plugins {
    id 'play'
}


repositories {
    mavenLocal()
}

repositories {
    maven {
        credentials {
            username 'your username'
            password 'your password'
        }
        mavenCentral()
        url = 'https://repo.lightbend.com/commercial-releases'
    }
}

model {
    components {
        play {
            platform play: '2.7.3', scala: '2.12', java: '1.8'
            injectedRoutesGenerator = true

            sources {
                twirlTemplates {
                    defaultImports = TwirlImports.SCALA
                }
            }
        }
    }
}

// Add the agent to a separate configuration so it doesn't add to the normal class path
configurations {
    agent
}

dependencies {
    play "com.typesafe.play:play-guice_2.12:2.7.3"
    play "com.typesafe.play:play-ahc-ws_2.12:2.7.3"

    agent group: 'com.lightbend.cinnamon', name: 'cinnamon-agent', version: '2.12.2'

    // Add the Cinnamon modules you want to use here below.
    play "com.lightbend.cinnamon:cinnamon-play_2.12:2.12.2"
    play "com.lightbend.cinnamon:cinnamon-chmetrics:2.12.2"
}

tasks.withType(CreateStartScripts) {
    defaultJvmOpts = ["-javaagent:${configurations.agent.singleFile}"]
}

application.conf

The configuration file 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 modified the files above you simply use Gradle to run the application:

> gradle stage
> ./build/stage/playBinary/bin/playBinary

If on Windows, run the playBinary.bat file found in the same folder.

The above command will start the application with Cinnamon enabled and you should see a similar output to this:

[INFO] [08/10/2019 17:40:24.628] [Cinnamon] Agent version <VERSION>
[INFO] [08/10/2019 17:40:24.777] [Cinnamon] Agent found Play version <VERSION>
...