Implement a PoC jvm agent

This was coded with the help of Opus 4.8

Author: alexduf

build.sbt

@@ -1,5 +1,6 @@
 import play.sbt.routes.RoutesKeys
 import com.typesafe.sbt.web.SbtWeb.autoImport._
+import com.typesafe.sbt.packager.archetypes.JavaAppPackaging.autoImport._
 import com.gu.Dependencies._
 import com.gu.ProjectSettings._
 
@@ -14,6 +15,30 @@ https://support.snyk.io/hc/en-us/articles/9590215676189-Deeply-nested-Scala-proj
 ThisBuild / asciiGraphWidth := 999999999
 ThisBuild / scalaVersion := SCALA_VERSION
 
+/*
+ * Standalone JVM agent that records which Twirl templates are rendered at runtime.
+ *
+ * It is NOT a Play module: it's a plain, pure-Java project assembled into a shaded, self-contained
+ * jar (with a `Premain-Class` manifest entry) that gets attached to a host app via `-javaagent`.
+ * ByteBuddy is relocated under com.gu.shaded.bytebuddy so it can never clash with anything on an
+ * application's classpath (e.g. the byte-buddy that mockito pulls in for tests).
+ */
+val templateTrackerAgent = Project("template-tracker-agent", file("template-tracker-agent"))
+  .settings(
+    crossPaths := false, // pure Java: don't append a _2.13 suffix to the artifact
+    autoScalaLibrary := false, // pure Java: no scala-library dependency
+    libraryDependencies += byteBuddy,
+    assembly / assemblyJarName := "template-tracker-agent.jar",
+    assembly / assemblyShadeRules := Seq(
+      ShadeRule.rename("net.bytebuddy.**" -> "com.gu.shaded.bytebuddy.@1").inAll,
+    ),
+    assembly / packageOptions += Package.ManifestAttributes(
+      "Premain-Class" -> "com.gu.templatetracker.TemplateTrackerAgent",
+      "Can-Redefine-Classes" -> "true",
+      "Can-Retransform-Classes" -> "true",
+    ),
+  )
+
 val common = library("common")
   .settings(
     libraryDependencies ++= Seq(
@@ -99,7 +124,20 @@ val sport = application("sport")
     ),
   )
 
-val discussion = application("discussion").dependsOn(commonWithTests).aggregate(common)
+val discussion = application("discussion")
+  .dependsOn(commonWithTests)
+  .aggregate(common)
+  .settings(
+    // --- Twirl template usage tracker (PoC) ---
+    // Bundle the shaded agent jar into the packaged app under agent/, then have the generated
+    // native-packager start script attach it via -javaagent. ${app_home} is resolved by the start
+    // script at launch time, so this needs no change to the CDK/systemd launch config.
+    Universal / mappings += {
+      val agentJar = (templateTrackerAgent / assembly).value
+      agentJar -> "agent/template-tracker-agent.jar"
+    },
+    bashScriptExtraDefines += """addJava "-javaagent:${app_home}/../agent/template-tracker-agent.jar"""",
+  )
 
 val admin = application("admin")
   .dependsOn(commonWithTests)

project/Dependencies.scala

@@ -12,6 +12,10 @@ object Dependencies {
   val jerseyVersion = "1.19.4"
   val playJsonVersion = "3.0.6"
   val apacheCommonsLang = "org.apache.commons" % "commons-lang3" % "3.16.0"
+  // ByteBuddy powers the standalone template-tracker JVM agent (shaded at assembly time).
+  // Pinned to 1.15.x: later releases bundle Java 24 multi-release classes that the assembly
+  // shader can't read/relocate (harmless on our Java 21 runtime, but noisy and not cleanly shaded).
+  val byteBuddy = "net.bytebuddy" % "byte-buddy" % "1.15.11"
   val awsCloudwatch = "software.amazon.awssdk" % "cloudwatch" % awsVersion
   val awsDynamodb = "software.amazon.awssdk" % "dynamodb" % awsVersion
   val awsKinesis = "software.amazon.awssdk" % "kinesis" % awsVersion

project/plugins.sbt

@@ -11,6 +11,9 @@ addSbtPlugin("org.playframework" % "sbt-plugin" % "3.0.11")
 
 addSbtPlugin("com.github.sbt" % "sbt-native-packager" % "1.11.7")
 
+// Used to build the shaded, self-contained template-tracker JVM agent jar
+addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "2.3.1")
+
 addSbtPlugin("com.timushev.sbt" % "sbt-updates" % "0.6.4")
 
 addSbtPlugin("com.github.sbt" % "sbt-git" % "2.1.0")

template-tracker-agent/src/main/java/com/gu/templatetracker/RecordTemplateAdvice.java

@@ -0,0 +1,23 @@
+package com.gu.templatetracker;
+
+import net.bytebuddy.asm.Advice;
+
+/**
+ * The advice whose body ByteBuddy inlines at the entry of each instrumented template method.
+ *
+ * <p>Keep this minimal: only the {@link Advice.OnMethodEnter} method's bytecode is copied into the
+ * target. It must reference only types resolvable from the instrumented class's classloader - here
+ * just {@link TemplateTracker}, which is loaded by the system classloader (the {@code -javaagent}
+ * jar is appended to the system class path) and therefore visible to Play's child application
+ * classloader.
+ */
+public final class RecordTemplateAdvice {
+
+    private RecordTemplateAdvice() {}
+
+    @Advice.OnMethodEnter
+    public static void onEnter(@Advice.Origin("#t") String templateClassName) {
+        TemplateTracker.recordFirstSeen(templateClassName);
+    }
+}
+

template-tracker-agent/src/main/java/com/gu/templatetracker/TemplateTracker.java

@@ -0,0 +1,44 @@
+package com.gu.templatetracker;
+
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Holds the set of Twirl templates seen so far in this JVM and logs each one the first time it is
+ * rendered.
+ *
+ * <p>This class is loaded by the system classloader (it lives in the {@code -javaagent} jar) so it
+ * is shared across the whole application and visible to the woven {@code views.html.*} classes.
+ *
+ * <p>The PoC logs to stdout as a single structured JSON line so the ELK pipeline can pick it up.
+ * We intentionally do not use the application's {@code GuLogging}: that lives in the {@code common}
+ * module on Play's application classloader and is not (cleanly) reachable from an agent on the
+ * system classloader without coupling the two together. If we later productionise this, the
+ * delegate target can be swapped for a registry in {@code common} that emits via {@code GuLogging}
+ * + CloudWatch + S3/Athena.
+ */
+public final class TemplateTracker {
+
+    private static final Set<String> SEEN = ConcurrentHashMap.newKeySet();
+
+    private TemplateTracker() {}
+
+    public static void recordFirstSeen(String rawClassName) {
+        String template = normalise(rawClassName);
+        // After the first sighting of a template, `add` returns false and we do nothing further -
+        // so the hot path for high-traffic templates is a single concurrent-set membership check.
+        if (SEEN.add(template)) {
+            System.out.println(
+                "{\"marker\":\"TEMPLATE_FIRST_SEEN\",\"template\":\"" + template + "\"}");
+        }
+    }
+
+    /** Scala {@code object}s compile to a {@code Foo$} class; strip the trailing {@code $}. */
+    private static String normalise(String className) {
+        if (className != null && className.endsWith("$")) {
+            return className.substring(0, className.length() - 1);
+        }
+        return className;
+    }
+}
+

template-tracker-agent/src/main/java/com/gu/templatetracker/TemplateTrackerAgent.java

@@ -0,0 +1,46 @@
+package com.gu.templatetracker;
+
+import net.bytebuddy.agent.builder.AgentBuilder;
+import net.bytebuddy.asm.Advice;
+import net.bytebuddy.matcher.ElementMatchers;
+
+import java.lang.instrument.Instrumentation;
+
+/**
+ * A JVM agent that records, once per JVM, the first time each Twirl template is rendered.
+ *
+ * <p>It is wired into the host application via {@code -javaagent:.../template-tracker-agent.jar}
+ * (see the {@code discussion} module in {@code build.sbt}). The JVM calls {@link #premain} before
+ * the application's {@code main}, i.e. before Play boots and before any {@code views.html.*}
+ * template class is loaded - so every template is woven naturally as it is first class-loaded.
+ *
+ * <p>The instrumentation is deliberately tiny: it inlines a single call at the entry of each
+ * template's {@code apply}/{@code render} method, which delegates to {@link TemplateTracker} where a
+ * first-seen {@link java.util.Set} membership check makes every render after the first essentially free.
+ */
+public final class TemplateTrackerAgent {
+
+    private TemplateTrackerAgent() {
+    }
+
+    public static void premain(String args, Instrumentation instrumentation) {
+        System.out.println(
+            "{\"marker\":\"TEMPLATE_TRACKER_INIT\",\"message\":\"installing Twirl template usage tracker\"}");
+
+        new AgentBuilder.Default()
+            // Only consider compiled Twirl templates: classes under views.html.* that are
+            // subtypes of play.twirl.api.Template* (Template0..Template22). This excludes the
+            // many anonymous-function classes Scala generates inside a template
+            // (e.g. views.html.fragments.articleBody$$anonfun$...), which also live under
+            // views.html.* and also have an `apply` method, but are not templates.
+            .type(
+                ElementMatchers.<net.bytebuddy.description.type.TypeDescription>nameStartsWith("views.html.")
+                    .and(ElementMatchers.hasSuperType(ElementMatchers.nameStartsWith("play.twirl.api.Template"))))
+            .transform((builder, typeDescription, classLoader, module, protectionDomain) ->
+                builder.visit(
+                    Advice.to(RecordTemplateAdvice.class)
+                        .on(ElementMatchers.named("apply").or(ElementMatchers.named("render")))))
+            .installOn(instrumentation);
+    }
+}
+