Gradle OpenTelemetry build plugin

Find the slowest parts of your build with the Gradle OpenTelemetry build plugin. This plugin instruments your build with OpenTelemetry traces and spans so you can visualize all tasks executed in your build, find where the build time is going, track build duration over time, etc. You'll get a trace for each build with a span for every task, so you can find and optimize the bottlenecks in your build.

The plugin will also show you the test duration breakdown per test class and test case:

And the plugin also attaches information about test failures so you can view those as well:

The plugin will also log out the trace ID at the end of your build so you can easily find the exact trace for your build:

OpenTelemetry spans and attributes

The plugin creates a single trace for each build, with an overall span for the build and child individual spans for each task. The plugin also creates individual span for each test executed in a Gradle task with the Test type.

Span attributes

The plugin adds the following attributes to the different spans it creates.

Root build span is named ${project.name}-build, for example this plugin's root span is named opentelemetry-gradle-plugin-build And the root span has the following attributes:

All spans (root span, task spans, etc.) have the following attributes:

Each task has a child span created from the root build. The task spans are named with the task path, for example :test And each task span has the following attributes:

And finally the plugin creates a child span off each Test type task for each test executed. The name of the per-test span is the full name of the test method. And the attributes on the per-test spans are:

Remote parent trace

Some CI execution systems such as Jenkins have support for creating a trace of the full CI execution, where the Gradle build is just part of that whole execution.

Starting with plugin version 1.12.0, the plugin will auto-detect these remote parent span and trace IDs when they are passed in as environment variables and make the Gradle build part of that overall trace.

By default, the plugin uses parent environment variables named SPAN_ID and TRACE_ID - and those can be configured if needed with plugin config parameters parentSpanIdEnvVarName and parentTraceIdEnvVarName.

URL for viewing trace

Starting with plugin version 1.14.0, you can specify the URL to view a trace in your OpenTelemetry backend and the plugin will substitute the trace ID and print out a convenient URL to quickly view the trace in your telemetry UI.

For any OpenTelemetry backend, you can pass the traceViewUrl config parameter to specify the URL to view a trace with {traceId} in the place where the plugin should substitute the trace ID for that build.

For example, for a local Jaeger instance with the UI running on port 16686:

openTelemetryBuild {
    endpoint = "http://localhost:4317"

    traceViewUrl = "http://localhost:16686/trace/{traceId}"
}

Then the plugin will print out the full URL to view the trace when the build completes:

OpenTelemetry build trace http://localhost:16686/trace/5a47e977c06a5d2a046d101fdedcb4ed

URLs for specific OpenTelemetry backends

As a convenience for known OpenTelemetry backends, you can specify the type of the backend with the traceViewType parameter and then you only need to include the base URL for viewing traces:

openTelemetryBuild {
    endpoint = "http://localhost:4317"

    traceViewType = com.atkinsondev.opentelemetry.build.TraceViewType.JAEGER
    traceViewUrl = "http://localhost:16686/"
}

Usage

Add plugin

To start using the plugin, first add the plugin to the plugins block in your build.gradle file:

plugins {
    id 'com.atkinsondev.opentelemetry-build' version "2.1.0"
}

Please see the Gradle plugin portal for the latest version of the plugin: https://plugins.gradle.org/plugin/com.atkinsondev.opentelemetry-build

Configure plugin

Then add a openTelemetryBuild block to your build.gradle file.

The only required configuration parameter is the server endpoint to send the OpenTelemetry data to.

openTelemetryBuild {
    endpoint = "https://<opentelemetry-server-domain>"
}

You can also add a map of headers to the data send to the OpenTelemetry server. Adding headers can be useful for passing things like an API key for authentication:

openTelemetryBuild {
    endpoint = "https://<opentelemetry-server-domain>"
    headers = ["X-API-Key": "<my-api-key>"]
}

Zipkin Exporter configuration

In addition to the standard gRPC or HTTP OpenTelemetry exporters, the plugin supports exporting to Zipkin.

To export to Zipkin, set the exporterMode plugin configuration parameter to OpenTelemetryExporterMode.ZIPKIN and set the endpoint to be your Zipkin server API endpoint, similar to the following:

openTelemetryBuild {
    endpoint = "https://yourzipkinserver.com/api/v2/spans"
    serviceName = "appname-build"
    exporterMode = com.atkinsondev.opentelemetry.build.OpenTelemetryExporterMode.ZIPKIN
}

All configuration options

** Required

Compatibility

The plugin is compatible with Java 17+ and Gradle versions 7.3 and higher.

Limitations

• Incompatible with the configuration cache. This plugin uses a BuildListener.buildFinished event, which isn't compatible with the configuration cache

Examples

Jaeger

Example of running a Jaeger instance locally and publishing build traces to it:

Run Jaeger via Docker and enable the OpenTelemetry collector with COLLECTOR_OTLP_ENABLED=true:

docker run --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  jaegertracing/all-in-one:1.57

Configure the plugin in build.gradle to point at the gRPC endpoint running on port 4317 in the local Jaeger instance:

plugins {
  id 'com.atkinsondev.opentelemetry-build' version "2.1.0"
}

openTelemetryBuild {
    endpoint = "http://localhost:4317"
}

Then to view the build traces in your local Jaeger instance:

1. Go to the Jaeger UI that is running on http://localhost:16686
2. Select the service "gradle-builds"
3. Click "Find Traces"
4. Select one of the traces

Changelog

• 2.1.0
  • Upgrading to OpenTelemetry 1.43.0
• 2.0.0
  • Breaking change: plugin now requires Java 17+ and Gradle 7.3+
  • Upgrading to Kotlin 1.9.24 and Gradle 8.10.2
• 1.14.0
  • Adding support for logging the URL to view the build's trace with traceViewUrl
• 1.13.0
  • Adding support for nested test spans in new parameter nestedTestSpans which defaults to true
• 1.12.0
  • Fix for publishing traces when parent trace information is present
• 1.10.0
  • Moving the error message string to the error_message attribute and making error be a boolean to render errors correctly in the Jaeger UI
  • Fixed problem where invalid parent span/trace ID error messages were logged when no parent or span IDs were set
  • Updating to OpenTelemetry 1.36.0, Gradle 8.7, and Kotlin 1.9.22
• 1.9.1
  • Fixing version in user-agent string
• 1.9.0
  • Upgrading to Gradle 8.5 and Kotlin 1.9.20 (Gradle/Kotlin compatibility matrix)
• 1.8.0
  • Upgrading to OpenTelemetry 1.33.0
• 1.7.1
  • Fix the support for remote parent span and trace IDs
• 1.7.0
  • Adding support for taking in remote parent span and trace IDs from systems like Jenkins for including this plugin's traces as part of an overall part trace
• 1.6.1
  • Downgrading Kotlin 1.7.10 to match the Kotlin version bundled with Gradle 7.6 (Gradle compatibility matrix)
• 1.6.0
  • Adding support for custom telemetry attributes (thanks @kpriemchenko !)
  • Upgrading to OpenTelemetry 1.29.0 and Kotlin 1.9.0
• 1.5.0
  • Upgrading to OpenTelemetry 1.22.0 and Kotlin 1.8.0
• 1.4.0
  • Upgrading to OpenTelemetry 1.20.0 and Kotlin 1.7.21
• 1.3.1
  • Using baggage to put attributes project.name, gradle.version, and system.is_ci on all spans the plugin creates
• 1.3.0
  • Added support for Zipkin exporter. Upgrading to OpenTelemetry 1.19.0
• 1.2.1
  • Fix formatting of user-agent string
• 1.2.0
  • Disable the plugin gracefully if there is an error parsing the headers config
• 1.1.2
  • Adding task type to task span attribute task.type
• 1.1.1
  • Adding task names from Gradle execution as build.task.names attribute to root span
• 1.1.0
  • Upgrading to OpenTelemetry SDK 1.18.0
• 1.0.1
  • Adding system.is_ci attribute to root build span
• 1.0.0
  • Initial release