specify context propagation and other definitions, update jaxws, remove experimental feature descriptor entirely

jaydeluca · jaydeluca · commit de335c165d24 · 2025-10-02T17:37:33.000-04:00
diff --git a/docs/contributing/documenting-instrumentation.md b/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
 
diff --git a/docs/instrumentation-list.yaml b/docs/instrumentation-list.yaml
@@ -4609,13 +4609,11 @@ libraries:
   jaxws:
   - name: jaxws-2.0
     display_name: JAX-WS
-    description: This instrumentation enables controller spans for JAX-WS Provider
-      implementations.
+    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
-    - CONTEXT_PROPAGATION
-    - EXPERIMENTAL_ONLY
     source_path: instrumentation/jaxws/jaxws-2.0
     scope:
       name: io.opentelemetry.jaxws-2.0
@@ -4627,25 +4625,14 @@ libraries:
       description: Enables the creation of experimental controller (INTERNAL) 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 enables controller spans for Apache Axis2 JAX-WS web services, and enriches HTTP server spans with route information.
+      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:
-    - CONTROLLER_SPANS
-    - CONTEXT_PROPAGATION
     - HTTP_ROUTE
-    - EXPERIMENTAL_ONLY
+    - CONTROLLER_SPANS
     source_path: instrumentation/jaxws/jaxws-2.0-axis2-1.6
     scope:
       name: io.opentelemetry.jaxws-2.0-axis2-1.6
@@ -4657,21 +4644,14 @@ libraries:
       description: Enables the creation of experimental controller (INTERNAL) 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 enables controller spans for Apache CXF JAX-WS web services, and enriches HTTP server spans with route information.
+      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:
-    - CONTROLLER_SPANS
-    - CONTEXT_PROPAGATION
     - HTTP_ROUTE
-    - EXPERIMENTAL_ONLY
+    - CONTROLLER_SPANS
     source_path: instrumentation/jaxws/jaxws-cxf-3.0
     scope:
       name: io.opentelemetry.jaxws-cxf-3.0
@@ -4683,20 +4663,14 @@ libraries:
       description: Enables the creation of experimental controller (INTERNAL) 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.
+      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
-    - CONTEXT_PROPAGATION
     source_path: instrumentation/jaxws/jaxws-jws-api-1.1
     scope:
       name: io.opentelemetry.jaxws-jws-api-1.1
@@ -4708,15 +4682,6 @@ libraries:
       description: Enables the creation of experimental controller (INTERNAL) 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:
diff --git a/instrumentation-docs/readme.md b/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
diff --git a/instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/internal/InstrumentationFeature.java b/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,
diff --git a/instrumentation/jaxws/jaxws-2.0-axis2-1.6/metadata.yaml b/instrumentation/jaxws/jaxws-2.0-axis2-1.6/metadata.yaml
@@ -1,13 +1,11 @@
 display_name: Apache Axis2 1.6 JAX-WS 2.x
 description: >
-  This instrumentation enables controller spans for Apache Axis2 JAX-WS web services, and enriches
-  HTTP server spans with route information.
+  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:
-  - CONTROLLER_SPANS
-  - CONTEXT_PROPAGATION
   - HTTP_ROUTE
-  - EXPERIMENTAL_ONLY
+  - CONTROLLER_SPANS
 configurations:
   - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
     description: Enables the creation of experimental controller (INTERNAL) spans.
diff --git a/instrumentation/jaxws/jaxws-2.0/metadata.yaml b/instrumentation/jaxws/jaxws-2.0/metadata.yaml
@@ -1,10 +1,10 @@
 display_name: JAX-WS
-description: This instrumentation enables controller spans for JAX-WS Provider implementations.
+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
-  - CONTEXT_PROPAGATION
-  - EXPERIMENTAL_ONLY
 configurations:
   - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
     description: Enables the creation of experimental controller (INTERNAL) spans.
diff --git a/instrumentation/jaxws/jaxws-cxf-3.0/metadata.yaml b/instrumentation/jaxws/jaxws-cxf-3.0/metadata.yaml
@@ -1,13 +1,11 @@
 display_name: Apache CXF 3.x JAX-WS
 description: >
-  This instrumentation enables controller spans for Apache CXF JAX-WS web services, and enriches
-  HTTP server spans with route information.
+  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:
-  - CONTROLLER_SPANS
-  - CONTEXT_PROPAGATION
   - HTTP_ROUTE
-  - EXPERIMENTAL_ONLY
+  - CONTROLLER_SPANS
 configurations:
   - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
     description: Enables the creation of experimental controller (INTERNAL) spans.
diff --git a/instrumentation/jaxws/jaxws-jws-api-1.1/metadata.yaml b/instrumentation/jaxws/jaxws-jws-api-1.1/metadata.yaml
@@ -1,11 +1,10 @@
 display_name: JWS API
 description: >
   This instrumentation enables controller spans for methods annotated with the @WebService
-  annotation from the JWS API.
+  annotation from the JWS API (controller spans are disabled by default).
 library_link: https://github.com/jakartaee/jws-api
 features:
   - CONTROLLER_SPANS
-  - CONTEXT_PROPAGATION
 configurations:
   - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
     description: Enables the creation of experimental controller (INTERNAL) spans.
