:sparkles: Define extension point(s) for vendor-specific distributions of this plugin.

[ryandens]

Define an extension point for vendor-specific distributions of this plugin, with a working example serving as the opentelemetry-java-instrumentation javaagent plugin.

Configuration

Typed config Gradle plugin extensions exposed to their end-user for configuration properties. These properties could be configured agnostic to the distribution type of the application (docker image, WAR, tar/zip file, uber JAR) but could be mapped to specific configuration properties with an order of precedence in terms of what configuration mechanism is used to configure the java agent. For example, a distribution of this plugin for OpenTelemetry might expose an extension like

openTelemetry {
  exporter = Exporters.OTLP
}

If the user is packaging their application as an OCI image, it might be best to specify this option as the environment variable OTEL_TRACES_EXPORTER=otlp in the image's Container config. If it's being packaged as a zip file with a start script, java system properties templated into the start script might be best.

Default and required configuration properties

Distributions of this plugin should be able to provide default values for the configurations they expose. Ideally, those defaults could be derived from the semantics of their application distribution. For example, a Java Agent might have an opinionated configuration that can be calculated at compile-time, rather than runtime, based on how it's being deployed (e.g. a docker container) or what dependencies it's being deployed with (e.g. another Java Agent). Providing that context to plugin distribution authors to allow them to "calculate" configuration prior to runtime could be valuable to users and Java Agent distribution teams

In addition to default configuration properties, some configuration properties should be required to be specified. For example, the Hypertrace Java Agent has the required configuration property HT_SERVICE_NAME or -Dht.service.name. Failing the build prior to the assemble step when an invalid configuration is provided is a great feedback loop for users attempting to instrument their application with a Java Agent for the first time.

Sensitive configuration properties

Some configuration properties are required, but are sensitive and should therefore not be included in application distributions. For example, an API key for reporting data from the Java agent to a secured platform should not be included in a Docker image or a start script. Instead, this variable should be provided at runtime. This presents a slight challenge to this plugin, which encourages developers to attach the Java Agent to the Application Plugin's run task. We should provide a way to mark a property as sensitive such that even if the property can be resolved at distribution build time, it is not included in the artifacts built and is only available to tasks that run a java process.

Composable extension points

Some Java Agents are themselves distributions of Java Agents (often, OpenTelemetry). Our extension model should be designed so that these extension points are composable, meaning that a project like Hypertrace create a distribution of this plugin by composing and enhancing the OpenTelemetry distribution of this plugin. These distribution Java Agents often have other needs, like providing opinionated configuration of the underlying distribution.

Breaking Configuration Changes

Java Agents and their configurations change over time. We should define a best -practice around introducing those changes in a way that has the least impact to users. Should the distribution of the plugin be associated with a specific version of its java agent? Should it be associated with a specific range of versions? Is this a problem we're well-positioned to solve? Allow users to redefine configuration mappings?