DOCSEARCHbyAlgolia
Submit Docs

Talaiot Gradle Plugin

repository·master·Indexed 20 days ago

https://github.com/cdsap/talaiot

A Gradle plugin for monitoring build performance by recording task and build durations. Talaiot uses a plugin-based architecture to publish timing data and custom metrics to time-series databases and storage systems, including InfluxDB, InfluxDB2 (Flux), Elasticsearch, RethinkDB, Prometheus PushGateway, and JSON. It features task and module filtering, execution time thresholds, and a pre-configured Docker image containing Grafana and InfluxDB for observability.

Tokens
10.2K
Snippets
33
Records
45
Agent score
69%

What's inside Talaiot

  1. Overview of Talaiot

    master

    Talaiot is an extensible library for the Gradle Build System designed to record build and task durations. It helps teams identify build bottlenecks by capturing timing data and enriching every record with default or custom metrics.

    Talaiot uses a plugin-based architecture to publish this data to various systems such as InfluxDB, Elasticsearch, or RethinkDB.

  2. Use the Talaiot Docker Image

    master

    Talaiot provides a Docker image based on the philhawthorne/docker-influxdb-grafana project. This image is pre-configured for observability tasks and includes the following built-in features:

    • Grafana: Includes a newer version of Grafana than the base image.
    • InfluxDB: Automatically populates a default database named tracking.
    • Provisioning: Includes pre-provisioned Grafana Dashboards and Data Sources to facilitate immediate use.

  3. Set up a local observability stack with Docker

    master

    To visualize Talaiot data using Grafana and InfluxDB, you can run a pre-configured Docker image that includes a default database, provisioned dashboards, and a default InfluxDB datasource.

    Run the following command to start the stack:

    • Port 3003: Grafana
    • Port 8083: InfluxDB
    • Port 8086: InfluxDB
    • Port 22022: SSH

    Access Grafana at http://localhost:3003 (default credentials: root/root).

    docker run -d \
  -p 3003:3003 \
  -p 3004:8083 \
  -p 8086:8086 \
  -p 22022:22 \
  -v /var/lib/influxdb \
  -v /var/lib/grafana \
  cdsap/talaiot:latest

  4. Populate Talaiot data using the provided script

    master

    After starting the Docker stack, the dashboards will appear empty. To populate them with sample data, use the provided script which utilizes the gradle-profiler to trigger multiple builds based on a predefined scenario.

    Execute the script from the repository root:

    bash scripts/populate.sh

    Once the script completes, you can view the results in the following Grafana dashboards:

    • Android Task Tracking: http://localhost:3003/d/F9jppxQiz/android-task-tracking?orgId=1
    • Task Cache Info: http://localhost:3003/d/WlpZEBRMz/task-cache-info?orgId=1
    bash scripts/populate.sh

  5. Use Talaiot Snapshots

    master

    If you need to use snapshot versions of Talaiot, you must add the Sonatype OSS repository to your buildscript and append -SNAPSHOT to the version string.

    // Repository setup
maven ( url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/") )

// Standard Plugin Snapshot
classpath("io.github.cdsap:talaiot:<latest version>-SNAPSHOT")

// Individual Plugin Snapshot
classpath("io.github.cdsap.talaiot.plugin:base:<latest version>-SNAPSHOT")

  6. Install the Talaiot Standard Plugin

    master

    To use all Talaiot features, install the standard plugin. You can use the modern Gradle plugins DSL or the legacy buildscript application method in either Kotlin or Groovy.

    ### Kotlin (Plugins DSL)
```kotlin
plugins {
  id("io.github.cdsap.talaiot") version "<latest version>"
}

    Kotlin (Legacy)

    buildscript {
  repositories {
    gradlePluginPortal()
  }
  dependencies {
    classpath("io.github.cdsap:talaiot:<latest version>")
  }
}

apply(plugin = "io.github.cdsap.talaiot")

    Groovy (Plugins DSL)

    plugins {
  id "io.github.cdsap.talaiot" version "<latest version>"
}

    Groovy (Legacy)

    buildscript {
  repositories {
    gradlePluginPortal()
  }
  dependencies {
    classpath "io.github.cdsap:talaiot:<latest version>"
  }
}

apply plugin: "io.github.cdsap.talaiot"

  7. Filter tasks, modules, and execution thresholds

    master

    Talaiot allows you to filter which tasks and modules are tracked and published. You can also filter based on execution time thresholds.

    Task and Module Filtering:

    • tasks: Use excludes or includes to filter specific tasks.
    • modules: Use excludes or includes to filter specific modules.
    • threshold: Use minExecutionTime to only report tasks that meet a minimum time requirement.

    Publishing Logic Filters: These settings can skip the entire publishing process:

    • build.success: Skip publishing based on whether the build succeeded.
    • build.requestedTasks: Skip publishing based on the tasks requested by the user.
    filter {
    tasks {
        excludes = arrayOf("preDebugBuild", "processDebugResources")
    }
    modules {
        excludes = arrayOf(":app")
    }
    threshold {
        minExecutionTime = 10
    }
    build {
        success = true
        requestedTasks {
            includes = arrayOf(":app:assemble.*")
            excludes = arrayOf(":app:generate.*")
        }
    }
}

  8. Ignore Talaiot execution based on environment

    master

    Use the ignoreWhen block to prevent Talaiot from publishing results based on environment properties. A common use case is to disable tracking when running on a CI server.

    Properties:

    • envName: The name of the environment property to check.
    • envValue: The value required to trigger the ignore logic.
    talaiot {
    ignoreWhen {
        envName = "CI"
        envValue = "true"
    }
}

  9. Understand OutputPublisher task reporting

    master

    When publishTaskMetrics is enabled, the OutputPublisher processes the ExecutionReport to show a summary of tasks.

    • Sorting: Tasks are sorted based on the configured Order (ASC or DESC).
    • Visual Representation: The publisher uses a visual 'shrug' bar (¯\_(ツ)_/¯) to represent the relative duration of tasks. The length of the bar is proportional to the task's duration relative to the longest task in the list.
    • Time Formatting: Task durations are automatically formatted for readability:
      • Values < 1000ms are shown as Xms.
      • Values < 60000ms are shown as Xsec.
      • Larger values are shown as Xmin.
    • Output Format: Each line typically follows the pattern: [Visual Bar] [Task Name]: [Formatted Duration] : [Task State].

  10. Install an Individual Talaiot Plugin (Example)

    master

    Below are examples of how to install the base plugin using both Kotlin and Groovy.

    ### Kotlin (Plugins DSL)
```kotlin
plugins {
  id("io.github.cdsap.talaiot.plugin.base") version "<latest version>"
}

    Kotlin (Legacy)

    buildscript {
  repositories {
    gradlePluginPortal()
  }
  dependencies {
    classpath("io.github.cdsap.talaiot.plugin:base:<latest version>")
  }
}

apply(plugin = "io.github.cdsap.talaiot.plugin.base")

    Groovy (Plugins DSL)

    plugins {
  id "io.github.cdsap.talaiot.plugin.base" version "<latest version>"
}

    Groovy (Legacy)

    buildscript {
  repositories {
    gradlePluginPortal()
  }
  dependencies {
    classpath "io.github.cdsap.talaiot.plugin:base:<latest version>"
  }
}

apply plugin: "io.github.cdsap.talaiot.plugin.base"

  11. Run the Talaiot sample project

    master

    The sample directory contains a complete Gradle project demonstrating Talaiot usage, including custom publishers and metric definitions. To build the sample project, navigate to the directory and use the Gradle wrapper:

    cd sample
./gradlew assemble

  12. Add custom metrics to Talaiot

    master

    You can include extra information in the build and task data by adding custom metrics. You can add pre-defined metric objects, or define build and task metrics directly using key-value pairs.

    Available methods:

    • customMetrics(...): Add custom Metric objects (e.g., HostnameMetric()).
    • customBuildMetrics(key to value): Define metrics for the overall build.
    • customTaskMetrics(key to value): Define metrics for individual tasks.
    talaiot {
    metrics {
        // Add custom Metric objects
        customMetrics(
            MyCustomMetric(),
            HostnameMetric()
        )

        // Define build metrics directly
        customBuildMetrics(
            "kotlinVersion" to $kotlinVersion,
            "javaVersion" to $javaVersion
        )
        // Define task metrics directly
        customTaskMetrics(
            "customProperty" to $value
        )
    }
}