Merge pull request #45 from Automattic/improve_documentation

Improve documentation and naming
Automattic · Mar 29, 2024 · 42b3b25 · 42b3b25
2 parents 198d4a5 + 3af05e8
commit 42b3b25
Show file tree

Hide file tree

Showing 7 changed files with 58 additions and 24 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,11 @@
 # measure-builds Gradle Plugin [![Pre Merge Checks](https://github.com/cortinico/kotlin-gradle-plugin-template/workflows/Pre%20Merge%20Checks/badge.svg)](https://github.com/cortinico/kotlin-gradle-plugin-template/actions?query=workflow%3A%22Pre+Merge+Checks%22)
 
-Gradle Plugin for reporting build metrics into internal Automattic systems.
+Gradle Plugin for reporting build metrics at the end of the build.
+
+## Features
+- Add own, custom reporters and send metrics to any system
+- Configuration Cache compatibility
+- Gradle Enterprise integration - optionally attach Gradle Scan Id to the metrics
 
 ## Setup
 
@@ -11,24 +16,34 @@ plugins {
 }
 
 // build.gradle
+import com.automattic.android.measure.reporters.MetricsReport
+import com.automattic.android.measure.reporters.SlowSlowTasksMetricsReporter
+
 plugins {
     id "com.automattic.android.measure-builds" version "latest_tag"
 }
 
 measureBuilds {
-    automatticProject.set(com.automattic.android.measure.MeasureBuildsExtension.AutomatticProject.WooCommerce)
-    attachGradleScanId.set(true) // `false`, if no Enterprise plugin applied OR don't want to attach build scan id 
+    enable = true
+    attachGradleScanId = true // `false`, if no Enterprise plugin applied OR don't want to attach build scan id
+    onBuildMetricsReadyListener { MetricsReport metricsReport ->
+        // Use ready reporters
+        SlowSlowTasksMetricsReporter.report(metricsReport)
+        
+        // or add your own reporters here or use 
+        MyCustomReporter.report(metricsReport)
+    }
 }
 ```
 
 ## Configuration
 
-| Property           | Required? | Description                                                                                                                                                       |
-|--------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| automatticProject  | yes       | Project that will determine event name                                                                                                                            |
-| attachGradleScanId | yes       | Upload metrics after build scan is published, with build scan id attached. If `false`, metrics will be uploaded upon build finish, without build scan id attached |
-| enable             | no        | Enable plugin (def: `false`)                                                                                                                                      |
-| obfuscateUsername  | no        | Obfuscate system username with SHA-1 (def: `false`)                                                                                                               | 
+| Property                    | Default | Description                                                                                                                                                       |
+|-----------------------------|----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| enable                      | `false` | Enable plugin                                                                                                                                      |
+| onBuildMetricsReadyListener |    | Callback to be called when build metrics are ready to be reported. Use this to add your own reporters. |
+| attachGradleScanId          | `false` | Upload metrics after build scan is published, with build scan id attached. If `false`, metrics will be uploaded upon build finish, without build scan id attached |
+| obfuscateUsername           | `false` | Obfuscate system username with SHA-1                                                                                                               | 
 
 ## Demo
 

diff --git a/measure-builds/src/main/java/com/automattic/android/measure/BuildTimePlugin.kt b/measure-builds/src/main/java/com/automattic/android/measure/BuildTimePlugin.kt
@@ -35,12 +35,12 @@ class BuildTimePlugin @Inject constructor(
             project.extensions.create("measureBuilds", MeasureBuildsExtension::class.java, project)
 
         val metricsDispatcher = InMemoryMetricsReporter
-        metricsDispatcher.buildMetricsPreparedAction = extension.buildMetricsPreparedAction
+        metricsDispatcher.buildMetricsPreparedAction = extension.buildMetricsReadyAction
 
         val encodedUser: String = UsernameProvider.provide(project, extension)
 
         project.afterEvaluate {
-            if (extension.enable.convention(false).get() == true) {
+            if (extension.enable.get() == true) {
                 val configurationProvider: Provider<Boolean> = project.providers.of(
                     ConfigurationPhaseObserver::class.java
                 ) { }
@@ -82,7 +82,7 @@ class BuildTimePlugin @Inject constructor(
         val attachGradleScanId = extension.attachGradleScanId
         buildScanExtension?.buildScanPublished {
             runBlocking {
-                if (extensionEnable.get() == true && attachGradleScanId.get()) {
+                if (extensionEnable.get() && attachGradleScanId.get()) {
                     analyticsReporter.report(InMemoryReport, it.buildScanId)
                 }
             }

diff --git a/measure-builds/src/main/java/com/automattic/android/measure/MeasureBuildsExtension.kt b/measure-builds/src/main/java/com/automattic/android/measure/MeasureBuildsExtension.kt
@@ -3,22 +3,40 @@ package com.automattic.android.measure
 import com.automattic.android.measure.reporters.MetricsReport
 import org.gradle.api.Action
 import org.gradle.api.Project
+import org.gradle.api.logging.Logging.getLogger
 import org.gradle.api.provider.Property
 
 abstract class MeasureBuildsExtension(project: Project) {
 
     private val objects = project.objects
 
-    val enable: Property<Boolean> = objects.property(Boolean::class.java)
+    /**
+     * Enable or disable the plugin.
+     */
+    val enable: Property<Boolean> = objects.property(Boolean::class.java).convention(false)
 
-    val obfuscateUsername: Property<Boolean> = objects.property(Boolean::class.java)
+    /**
+     * Enable or disable obfuscation of the username. If `true`, the username will be obfuscated by SHA-1.
+     */
+    val obfuscateUsername: Property<Boolean> =
+        objects.property(Boolean::class.java).convention(false)
 
     @Suppress("UNCHECKED_CAST")
-    internal val buildMetricsPreparedAction: Property<Action<MetricsReport>> =
-        objects.property(Action::class.java) as Property<Action<MetricsReport>>
+    internal val buildMetricsReadyAction: Property<Action<MetricsReport>> =
+        (objects.property(Action::class.java) as Property<Action<MetricsReport>>).convention(
+            Action {
+                getLogger(MeasureBuildsExtension::class.java).warn(
+                    "No action has been set for buildMetricsPrepared. " +
+                        "Metrics will not be reported."
+                )
+            }
+        )
 
-    fun buildMetricsPrepared(action: Action<MetricsReport>) {
-        buildMetricsPreparedAction.set(action)
+    /**
+     * Action to be executed when the build metrics are ready.
+     */
+    fun onBuildMetricsReadyListener(action: Action<MetricsReport>) {
+        buildMetricsReadyAction.set(action)
     }
 
     /**
@@ -27,7 +45,8 @@ abstract class MeasureBuildsExtension(project: Project) {
      * Gradle Build Scan id to metrics.
      *
      * If `false`, then metrics will be sent at build finish by
-     * @see io.github.wzieba.tracks.plugin.analytics.BuildFinishedFlowAction
+     * @see [com.automattic.android.measure.lifecycle.BuildFinishedFlowAction].
      */
-    val attachGradleScanId: Property<Boolean> = objects.property(Boolean::class.java)
+    val attachGradleScanId: Property<Boolean> =
+        objects.property(Boolean::class.java).convention(false)
 }
diff --git a/measure-builds/src/main/java/com/automattic/android/measure/providers/UsernameProvider.kt b/measure-builds/src/main/java/com/automattic/android/measure/providers/UsernameProvider.kt
@@ -10,7 +10,7 @@ object UsernameProvider {
         val user = project.providers.systemProperty("user.name").get()
 
         val encodedUser: String = user.let {
-            if (extension.obfuscateUsername.getOrElse(false) == true) {
+            if (extension.obfuscateUsername.get() == true) {
                 EncodingGroovyMethods.digest(it, "SHA-1")
             } else {
                 it

diff --git a/...ds/src/test/java/com/automattic/android/measure/BuildTimePluginConfigurationCacheTests.kt b/...ds/src/test/java/com/automattic/android/measure/BuildTimePluginConfigurationCacheTests.kt
@@ -100,7 +100,7 @@ class BuildTimePluginConfigurationCacheTests {
             measureBuilds {
                 enable.set(true)
                 attachGradleScanId.set(false)
-                buildMetricsPrepared{
+                onBuildMetricsReadyListener {
                     val buildPath = buildPathProperty.get()
                     com.automattic.android.measure.reporters.LocalMetricsReporter.report(this, buildPath)
                     com.automattic.android.measure.reporters.SlowSlowTasksMetricsReporter.report(this)

diff --git a/measure-builds/src/test/java/com/automattic/android/measure/BuildTimePluginTest.kt b/measure-builds/src/test/java/com/automattic/android/measure/BuildTimePluginTest.kt
@@ -183,7 +183,7 @@ class BuildTimePluginTest {
                      measureBuilds {
                          ${if (enable != null) "enable.set($enable)" else ""}
                          attachGradleScanId.set($attachGradleScanId)
-                         buildMetricsPrepared{
+                         onBuildMetricsReadyListener {
                               val buildPath = buildPathProperty.get()
                               com.automattic.android.measure.reporters.LocalMetricsReporter.report(this, buildPath)
                               com.automattic.android.measure.reporters.SlowSlowTasksMetricsReporter.report(this)

diff --git a/measure-builds/src/test/java/com/automattic/android/measure/GroovyConfigurationTest.kt b/measure-builds/src/test/java/com/automattic/android/measure/GroovyConfigurationTest.kt
@@ -25,7 +25,7 @@ class GroovyConfigurationTest {
             measureBuilds {
                 enable = true
                 attachGradleScanId = false
-                buildMetricsPrepared { MetricsReport report -> 
+                onBuildMetricsReadyListener { MetricsReport report -> 
                     SlowSlowTasksMetricsReporter.report(report)
                     LocalMetricsReporter.report(report, buildDir.absolutePath)
                 }