Gradle Example: Play
Below is an example for how to configure Cinnamon for Play metrics with Gradle.
Cinnamon supports Play 2.8 and greater.
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.
The URLs generated as part of your Lightbend platform credentials should not be committed to public source control repositories.
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:
plugins {
// 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:
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/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.