Gradle Example: Play

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

Background

When developing Play applications with Gradle, it is very convenient to use Play’s development runPlay command. However, because of the way the runPlay 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 (we recommend AdoptOpenJDK 8 or 11)
• Gradle
• Commercial credentials

Commercial credentials

To gain access to Lightbend Telemetry you must have a Lightbend subscription and Lightbend account.

Once you have logged in, the Lightbend platform credentials guide contains instructions for configuring your sbt, maven or gradle project to access Lightbend’s commercial dependencies, including Telemetry. If you have previously used a username and password to configure your commercial credentials, the guide will instruct you how to update to using the new scheme.

If you do not have a Lightbend subscription, please contact us to request an evaluation.

Modifications

The modifications below are required to enable telemetry.

build.gradle

Add a build.gradle file with the following content:

copyplugins {
    // See Gradle Play Plugin docs:
    // https://gradle.github.io/playframework/
    id 'org.gradle.playframework' version '0.9'
}

repositories {
    mavenCentral()
    mavenLocal()
    // maven {
    //	   Generate your Lightbend commercial repositories config for gradle at:
    //	     https://www.lightbend.com/account/lightbend-platform/credentials
    // 	   url = '...'
    // }
}

// Gradle Play Plugin only supports Play 2.4.x, 2.5.x, and 2.6.x versions.
def PlayVersion = "2.6.25"

play {
    platform {
        playVersion = PlayVersion
        scalaVersion = '2.12'
        javaVersion = JavaVersion.VERSION_1_8
    }
    injectedRoutesGenerator = true
}

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

dependencies {
    implementation "com.typesafe.play:play-guice_2.12:$PlayVersion"
    implementation "com.typesafe.play:play-ahc-ws_2.12:$PlayVersion"

    // Lightbend Telemetry (Cinnamon) agent
    agent group: 'com.lightbend.cinnamon', name: 'cinnamon-agent', version: '2.17.5'

    // Add the Lightbend Telemetry (Cinnamon) modules you want to use here below.
    implementation "com.lightbend.cinnamon:cinnamon-play_2.12:2.17.5"
    implementation "com.lightbend.cinnamon:cinnamon-chmetrics:2.17.5"
}

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:

copycinnamon.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/main/bin/main

If on Windows, run the main.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] [02/24/2020 14:34:14.158] [Cinnamon] Agent version 2.13.2
[INFO] [02/24/2020 14:34:14.324] [Cinnamon] Agent found Play version: 2.6.25
[INFO] [02/24/2020 14:34:14.324] [Cinnamon] Agent found Scala version: 2.12.10
[INFO] [02/24/2020 14:34:14.363] [Cinnamon] Agent found Play-AHC-WS version: 2.6.25
[INFO] [02/24/2020 14:34:14.375] [Cinnamon] Agent found Scala Futures version: 2.12.10
[INFO] [02/24/2020 14:34:14.618] [Cinnamon] Agent found Java Futures version: 1.8.0_242
...
2/24/20 2:34:20 PM =============================================================

-- Gauges ----------------------------------------------------------------------
metrics.akka.systems.application.dispatchers.akka_actor_default-dispatcher.active-threads
             value = 2
metrics.akka.systems.application.dispatchers.akka_actor_default-dispatcher.parallelism
             value = 12
metrics.akka.systems.application.dispatchers.akka_actor_default-dispatcher.pool-size
             value = 12
metrics.akka.systems.application.dispatchers.akka_actor_default-dispatcher.queued-tasks
             value = 0
metrics.akka.systems.application.dispatchers.akka_actor_default-dispatcher.running-threads
             value = 8
metrics.akka.systems.application.dispatchers.akka_io_pinned-dispatcher.active-threads
             value = 1
metrics.akka.systems.application.dispatchers.akka_io_pinned-dispatcher.pool-size
             value = 1
metrics.akka.systems.application.dispatchers.akka_io_pinned-dispatcher.running-threads
             value = 0
metrics.cinnamon.play.2_6_25.agent.2_13_2.java.1_8_0_242.scala.2_12_10.akka.2_5_26.versions
             value = 1

-- Histograms ------------------------------------------------------------------
metrics.akka-http.systems.application.http-servers.127_0_0_1_9000.request-methods.GET.request-paths._.endpoint-response-time
             count = 34248
               min = 181875
               max = 3896796
              mean = 450522.87
...

Play configuration

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