JAXWS metadata (#14864)

Co-authored-by: Lauri Tulmin <[email protected]>

Author: jaydeluca

docs/contributing/documenting-instrumentation.md

@@ -83,6 +83,7 @@ instrumentation.
 Example:
 
 ```yaml
+display_name: "Example Instrumentation"
 description: "This instrumentation enables..."
 semantic_conventions:
   - HTTP_CLIENT_SPANS
@@ -117,6 +118,15 @@ additional_telemetry:
             type: "STRING"
 ```
 
+### Display Name (optional)
+
+Display name is mostly used for UI purposes, and has two main uses:
+
+- Providing a more user-friendly name for the instrumentation than the module name
+  (e.g., "Apache CXF JAX-RS 2.x" instead of "jaxrs-2.0-cxf-3.2").
+- Collapsing multiple related modules into a single display name
+  (e.g., "Akka Actors" for both "akka-actor-2.3" and "akka-actor-fork-join-2.5").
+
 ### Description (required)
 
 At a minimum, every instrumentation metadata file should include a `description`.
@@ -150,6 +160,13 @@ Some notes when writing descriptions:
   the description unless they are essential to understanding the purpose of the instrumentation.
 * It is not usually necessary to include specific library or framework version numbers in the
   description, unless that context is significant in some way.
+* When describing instrumentations with controller or view spans:
+  * Always explicitly state that controller/view spans are disabled by default
+  * Use the phrase "(controller spans are disabled by default)" or "(view spans are disabled by default)"
+  * When an instrumentation has both enabled-by-default features (like HTTP_ROUTE) and disabled-by-default
+    features (like CONTROLLER_SPANS or VIEW_SPANS), describe the enabled features first, then the disabled features
+  * Example: "This instrumentation enriches HTTP server spans with route information, and enables
+    controller spans for Apache CXF JAX-WS web services (controller spans are disabled by default)."
 
 
 ### Semantic Conventions
@@ -185,11 +202,13 @@ the relevant functionality descriptions.
 List of possible options:
 
 * `HTTP_ROUTE`: Instrumentation that enriches HTTP spans with route information
-* `EXPERIMENTAL_ONLY`: Instrumentation that is experimental and may not be stable
-* `CONTEXT_PROPAGATION`: Instrumentation that provides context propagation capabilities
+* `CONTEXT_PROPAGATION`: Instrumentation that propagates OpenTelemetry context across application or thread boundaries. This applies to:
+  * Inter-process/application context propagation: Passing context through headers between applications (HTTP, gRPC, messaging, etc.)
+  * Inter-thread context propagation: Passing context from one thread to another (executors, actors, reactive streams, etc.)
+  * Does not include standard single-threaded scope management or normal span creation patterns
 * `AUTO_INSTRUMENTATION_SHIM`: Instrumentation that adapts or bridges instrumentation from upstream libraries or frameworks
-* `CONTROLLER_SPANS`: Instrumentation that generates controller-level spans
-* `VIEW_SPANS`: Instrumentation that generates view-level spans
+* `CONTROLLER_SPANS`: Instrumentation that generates controller-level spans for controller/handler methods in web frameworks (disabled by default, experimental)
+* `VIEW_SPANS`: Instrumentation that generates view-level spans for view rendering such as templates or JSP (disabled by default, experimental)
 
 ### Library Link
 

docs/instrumentation-list.yaml

@@ -4772,34 +4772,108 @@ libraries:
           type: BOOLEAN
   jaxws:
   - name: jaxws-2.0
+    display_name: JAX-WS
+    description: |
+      This instrumentation enables controller spans for JAX-WS Provider implementations (controller spans are disabled by default).
+    library_link: https://github.com/jakartaee/jax-ws-api
+    features:
+    - CONTROLLER_SPANS
     source_path: instrumentation/jaxws/jaxws-2.0
     scope:
       name: io.opentelemetry.jaxws-2.0
     target_versions:
       javaagent:
       - javax.xml.ws:jaxws-api:[2.0,]
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller spans.
+      type: boolean
+      default: false
+    telemetry:
+    - when: otel.instrumentation.common.experimental.controller-telemetry.enabled=true
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
   - name: jaxws-2.0-axis2-1.6
+    display_name: Apache Axis2 1.6 JAX-WS 2.x
+    description: |
+      This instrumentation enriches HTTP server spans with route information, and enables controller spans for Apache Axis2 JAX-WS web services (controller spans are disabled by default).
+    library_link: https://axis.apache.org/axis2/java/core/
+    features:
+    - HTTP_ROUTE
+    - CONTROLLER_SPANS
     source_path: instrumentation/jaxws/jaxws-2.0-axis2-1.6
     scope:
       name: io.opentelemetry.jaxws-2.0-axis2-1.6
     target_versions:
       javaagent:
       - org.apache.axis2:axis2-jaxws:[1.6.0,)
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller spans.
+      type: boolean
+      default: false
+    telemetry:
+    - when: otel.instrumentation.common.experimental.controller-telemetry.enabled=true
+      spans:
+      - span_kind: INTERNAL
+        attributes: []
   - name: jaxws-cxf-3.0
+    display_name: Apache CXF 3.x JAX-WS
+    description: |
+      This instrumentation enriches HTTP server spans with route information, and enables controller spans for Apache CXF JAX-WS web services (controller spans are disabled by default).
+    library_link: https://cxf.apache.org/
+    features:
+    - HTTP_ROUTE
+    - CONTROLLER_SPANS
     source_path: instrumentation/jaxws/jaxws-cxf-3.0
     scope:
       name: io.opentelemetry.jaxws-cxf-3.0
     target_versions:
       javaagent:
       - org.apache.cxf:cxf-rt-frontend-jaxws:[3.0.0,)
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller spans.
+      type: boolean
+      default: false
+    telemetry:
+    - when: otel.instrumentation.common.experimental.controller-telemetry.enabled=true
+      spans:
+      - span_kind: INTERNAL
+        attributes: []
   - name: jaxws-jws-api-1.1
+    display_name: JWS API
+    description: |
+      This instrumentation enables controller spans for methods annotated with the @WebService annotation from the JWS API (controller spans are disabled by default).
+    library_link: https://github.com/jakartaee/jws-api
     disabled_by_default: true
+    features:
+    - CONTROLLER_SPANS
     source_path: instrumentation/jaxws/jaxws-jws-api-1.1
     scope:
       name: io.opentelemetry.jaxws-jws-api-1.1
     target_versions:
       javaagent:
       - javax.jws:javax.jws-api:[1.1,]
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller spans.
+      type: boolean
+      default: false
+    telemetry:
+    - when: otel.instrumentation.common.experimental.controller-telemetry.enabled=true
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
   - name: jaxws-metro-2.2
     source_path: instrumentation/jaxws/jaxws-metro-2.2
     scope:

instrumentation-docs/instrumentations.sh

@@ -119,6 +119,10 @@ readonly INSTRUMENTATIONS=(
   "jaxrs:jaxrs-3.0:jaxrs-3.0-jersey-3.0:javaagent:testExperimental"
   "jaxrs:jaxrs-3.0:jaxrs-3.0-resteasy-6.0:javaagent:test"
   "jaxrs:jaxrs-3.0:jaxrs-3.0-resteasy-6.0:javaagent:testExperimental"
+  "jaxws:jaxws-2.0:javaagent:test"
+  "jaxws:jaxws-2.0-axis2-1.6:javaagent:test"
+  "jaxws:jaxws-cxf-3.0:javaagent:test"
+  "jaxws:jaxws-jws-api-1.1:javaagent:test"
   "jetty-httpclient:jetty-httpclient-12.0:javaagent:test"
   "jetty-httpclient:jetty-httpclient-9.2:javaagent:test"
   "jodd-http-4.2:javaagent:test"

instrumentation-docs/readme.md

@@ -138,7 +138,6 @@ public class SpringWebInstrumentationModule extends InstrumentationModule
   * The specific functionality that the instrumentation provides
   * Options are:
     * HTTP_ROUTE
-    * EXPERIMENTAL_ONLY
     * CONTEXT_PROPAGATION
     * AUTO_INSTRUMENTATION_SHIM
     * CONTROLLER_SPANS

instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationFeature.java

@@ -11,7 +11,6 @@
  */
 public enum InstrumentationFeature {
   HTTP_ROUTE,
-  EXPERIMENTAL_ONLY,
   CONTEXT_PROPAGATION,
   AUTO_INSTRUMENTATION_SHIM,
   CONTROLLER_SPANS,

instrumentation/apache-httpasyncclient-4.1/metadata.yaml

@@ -4,3 +4,4 @@ library_link: https://hc.apache.org/index.html
 semantic_conventions:
   - HTTP_CLIENT_SPANS
   - HTTP_CLIENT_METRICS
+

instrumentation/jaxws/jaxws-2.0-axis2-1.6-testing/build.gradle.kts

@@ -16,11 +16,54 @@ muzzle {
   }
 }
 
+val axis2Version = "1.6.0"
+
 dependencies {
   bootstrap(project(":instrumentation:servlet:servlet-common:bootstrap"))
 
   library("org.apache.axis2:axis2-jaxws:1.6.0")
 
   compileOnly(project(":muzzle"))
   compileOnly("jakarta.servlet:jakarta.servlet-api:5.0.0")
+
+  testLibrary("org.apache.axis2:axis2-jaxws:$axis2Version")
+  testLibrary("org.apache.axis2:axis2-transport-http:$axis2Version")
+  testLibrary("org.apache.axis2:axis2-transport-local:$axis2Version")
+
+  testImplementation(project(":instrumentation:jaxws:jaxws-2.0-common-testing"))
+
+  testInstrumentation(project(":instrumentation:jaxws:jaxws-2.0:javaagent"))
+  testInstrumentation(project(":instrumentation:jaxws:jaxws-jws-api-1.1:javaagent"))
+  testInstrumentation(project(":instrumentation:jaxws:jaxws-2.0-axis2-1.6:javaagent"))
+
+  testInstrumentation(project(":instrumentation:servlet:servlet-3.0:javaagent"))
+  testInstrumentation(project(":instrumentation:jetty:jetty-8.0:javaagent"))
+
+  testImplementation("javax.xml.bind:jaxb-api:2.2.11")
+  testImplementation("com.sun.xml.bind:jaxb-core:2.2.11")
+  testImplementation("com.sun.xml.bind:jaxb-impl:2.2.11")
+
+  testImplementation("com.sun.xml.ws:jaxws-rt:2.2.8")
+  testImplementation("com.sun.xml.ws:jaxws-tools:2.2.8")
+
+  latestDepTestLibrary("org.apache.axis2:axis2-jaxws:1.+") // see jaxws-3.0-axis2-2.0-testing module
+  latestDepTestLibrary("org.apache.axis2:axis2-transport-http:1.+") // see jaxws-3.0-axis2-2.0-testing module
+  latestDepTestLibrary("org.apache.axis2:axis2-transport-local:1.+") // see jaxws-3.0-axis2-2.0-testing module
+}
+
+configurations.configureEach {
+  if (name.contains("test")) {
+    // axis has a dependency on servlet2 api, get rid of it - otherwise the servlet3 instrumentation
+    // will fail during tests
+    exclude("javax.servlet", "servlet-api")
+  }
+}
+
+tasks.withType<Test>().configureEach {
+  // required on jdk17
+  jvmArgs("--add-opens=java.base/java.lang=ALL-UNNAMED")
+  jvmArgs("-XX:+IgnoreUnrecognizedVMOptions")
+  jvmArgs("-Dotel.instrumentation.common.experimental.controller-telemetry.enabled=true")
+  systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+  systemProperty("metadataConfig", "otel.instrumentation.common.experimental.controller-telemetry.enabled=true")
 }