Add OSGi support for library instrumentation, API, and SDK extension artifacts

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### 📈 Enhancements
+
+- Published library, API, and SDK extension artifacts now carry OSGi bundle metadata, so they can be
+  consumed directly in OSGi runtimes without external wrapper bundles.
+  ([#18995](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/18995))
+
 ### ⚠️ Breaking changes to non-stable APIs
 
 - Changed the return type for `JmxTelemetry.start(...)` APIs.

conventions/build.gradle.kts

@@ -72,6 +72,8 @@ dependencies {
   implementation("org.spdx:spdx-gradle-plugin:0.11.0")
   // When updating, also update dependencyManagement/build.gradle.kts
   implementation("net.bytebuddy:byte-buddy-gradle-plugin:1.18.10")
+  // Generates OSGi bundle metadata for published library artifacts (see otel.osgi-conventions)
+  implementation("biz.aQute.bnd:biz.aQute.bnd.gradle:7.3.0")
   implementation("gradle.plugin.io.morethan.jmhreport:gradle-jmh-report:0.9.6")
   implementation("me.champeau.jmh:jmh-gradle-plugin:0.7.3")
   implementation("net.ltgt.gradle:gradle-errorprone-plugin:5.1.0")

conventions/src/main/kotlin/io/opentelemetry/instrumentation/gradle/OtelJavaExtension.kt

@@ -6,6 +6,7 @@
 package io.opentelemetry.instrumentation.gradle
 
 import org.gradle.api.JavaVersion
+import org.gradle.api.provider.ListProperty
 import org.gradle.api.provider.Property
 
 abstract class OtelJavaExtension {
@@ -14,7 +15,18 @@ abstract class OtelJavaExtension {
 
   abstract val maxJavaVersionForTests: Property<JavaVersion>
 
+  // When false, skips OSGi bundle metadata generation for a module that has otel.osgi-conventions
+  // applied (e.g. a library that can't be a clean bundle). Has no effect on modules that don't
+  // apply otel.osgi-conventions.
+  abstract val osgiEnabled: Property<Boolean>
+
+  // Extra packages added to Import-Package as optional imports (resolution:=optional), typically
+  // corresponding to compileOnly dependencies that are not present at runtime in an OSGi container.
+  abstract val osgiOptionalPackages: ListProperty<String>
+
   init {
     minJavaVersionSupported.convention(JavaVersion.VERSION_1_8)
+    osgiEnabled.convention(true)
+    osgiOptionalPackages.convention(emptyList())
   }
 }

conventions/src/main/kotlin/otel.library-instrumentation.gradle.kts

@@ -3,6 +3,7 @@ plugins {
 
   id("otel.jacoco-conventions")
   id("otel.java-conventions")
+  id("otel.osgi-conventions")
   id("otel.publish-conventions")
 }
 

conventions/src/main/kotlin/otel.osgi-conventions.gradle.kts

@@ -0,0 +1,41 @@
+import io.opentelemetry.instrumentation.gradle.OtelJavaExtension
+
+// Generates OSGi bundle metadata in the jar manifest so published library artifacts can be consumed
+// directly in OSGi runtimes. Apply only to modules published in the io.opentelemetry.instrumentation
+// group (library instrumentations, SDK extensions, and the API/annotation modules) - never to
+// shadowed javaagent artifacts.
+
+plugins {
+  `java-library`
+  id("biz.aQute.bnd.builder")
+}
+
+// Configured via tasks.named (not afterEvaluate): the action runs when the jar task is realized,
+// after each module's build script has set the otelJava properties below.
+tasks.named<Jar>("jar") {
+  val otelJava = project.the<OtelJavaExtension>()
+  if (otelJava.osgiEnabled.get()) {
+    bundle {
+      // javax.annotation.* is always an optional import; modules can add more (typically
+      // corresponding to compileOnly dependencies). The trailing "*" imports everything else.
+      val optionalPackages = mutableListOf("javax.annotation")
+      optionalPackages.addAll(otelJava.osgiOptionalPackages.get())
+      val importPackages =
+        optionalPackages.joinToString(",") { "$it.*;resolution:=optional" } + ",*"
+
+      bnd(
+        mapOf(
+          "-exportcontents" to "io.opentelemetry.*",
+          "Import-Package" to importPackages,
+          // Auto-generate Provide/Require-Capability headers from META-INF/services entries
+          // (including AutoService-generated providers such as the resources module's
+          // ResourceProvider) so a ServiceLoader mediator (e.g. SPI Fly) can bridge them.
+          "-metainf-services" to "auto",
+          // reproducible builds (https://github.com/bndtools/bnd/issues/3521)
+          "-noextraheaders" to "true",
+          "-snapshot" to "SNAPSHOT",
+        ),
+      )
+    }
+  }
+}

conventions/src/main/kotlin/otel.sdk-extension.gradle.kts

@@ -6,6 +6,7 @@ plugins {
 
   id("otel.jacoco-conventions")
   id("otel.java-conventions")
+  id("otel.osgi-conventions")
   id("otel.publish-conventions")
 }
 

dependencyManagement/build.gradle.kts

@@ -118,7 +118,17 @@ val DEPENDENCIES = listOf(
   "javax.validation:validation-api:2.0.1.Final",
   "org.snakeyaml:snakeyaml-engine:2.10",
   "org.elasticmq:elasticmq-rest-sqs_2.13:1.7.1",
-  "io.github.netmikey.logunit:logunit-jul:2.0.0"
+  "io.github.netmikey.logunit:logunit-jul:2.0.0",
+
+  // OSGi runtime verification (see :osgi-test). Versions track opentelemetry-java's osgi tests.
+  "org.apache.felix:org.apache.felix.framework:7.0.5",
+  "org.apache.aries.spifly:org.apache.aries.spifly.dynamic.bundle:1.3.7",
+  "org.osgi:osgi.core:8.0.0",
+  "org.osgi:org.osgi.test.junit5:1.3.0",
+  "org.osgi:org.osgi.test.assertj.framework:1.3.0",
+  "biz.aQute.bnd:biz.aQute.tester.junit-platform:7.3.0",
+  "org.junit.jupiter:junit-jupiter:5.14.4",
+  "org.junit.platform:junit-platform-launcher:1.14.4"
 )
 
 javaPlatform {

instrumentation-annotations-support/build.gradle.kts

@@ -2,6 +2,7 @@ plugins {
   id("otel.java-conventions")
   id("otel.nullaway-conventions")
   id("otel.jacoco-conventions")
+  id("otel.osgi-conventions")
   id("otel.publish-conventions")
 }
 

instrumentation-annotations/build.gradle.kts

@@ -1,6 +1,7 @@
 plugins {
   id("otel.java-conventions")
   id("otel.nullaway-conventions")
+  id("otel.osgi-conventions")
   id("otel.publish-conventions")
 
   id("otel.animalsniffer-conventions")

instrumentation-api-incubator/build.gradle.kts

@@ -2,6 +2,7 @@ plugins {
   id("otel.java-conventions")
   id("otel.animalsniffer-conventions")
   id("otel.jacoco-conventions")
+  id("otel.osgi-conventions")
   id("otel.publish-conventions")
   id("otel.nullaway-conventions")
 }

instrumentation-api/build.gradle.kts

@@ -4,6 +4,7 @@ plugins {
   id("otel.java-conventions")
   id("otel.animalsniffer-conventions")
   id("otel.jacoco-conventions")
+  id("otel.osgi-conventions")
   id("otel.publish-conventions")
   id("otel.jmh-conventions")
   id("otel.nullaway-conventions")

instrumentation/logback/logback-appender-1.0/library/build.gradle.kts

@@ -3,6 +3,12 @@ plugins {
   id("org.graalvm.buildtools.native")
 }
 
+otelJava {
+  // Logstash support is optional; the encoder is a compileOnly dependency and may be absent at
+  // runtime in an OSGi container.
+  osgiOptionalPackages.add("net.logstash.logback")
+}
+
 dependencies {
   compileOnly(project(":muzzle"))