Metadata for the JAX-RS family (open-telemetry#14669)

Author: jaydeluca

docs/instrumentation-list.yaml

@@ -4251,75 +4251,328 @@ libraries:
       - io.javalin:javalin:[5.0.0,)
   jaxrs:
   - name: jaxrs-1.0
-    disabled_by_default: true
+    display_name: JAX-RS 1.x
+    description: |
+      This instrumentation enables spans for JAX-RS methods, and enriches existing HTTP server spans with route information.
+    library_link: https://javaee.github.io/javaee-spec/javadocs/javax/ws/rs/package-summary.html
     source_path: instrumentation/jaxrs/jaxrs-1.0
     scope:
       name: io.opentelemetry.jaxrs-1.0
     target_versions:
       javaagent:
       - javax.ws.rs:jsr311-api:[0.5,)
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller (INTERNAL) spans.
+      type: boolean
+      default: false
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
   - name: jaxrs-2.0-annotations
+    display_name: JAX-RS 2.x
+    description: |
+      This instrumentation enables spans for JAX-RS annotated methods, and enriches existing HTTP server spans with route information.
+    library_link: https://javaee.github.io/javaee-spec/javadocs/javax/ws/rs/package-summary.html
     source_path: instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-annotations
     scope:
       name: io.opentelemetry.jaxrs-2.0-annotations
     target_versions:
       javaagent:
       - javax.ws.rs:javax.ws.rs-api:[,]
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller (INTERNAL) spans.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.jaxrs.experimental-span-attributes
+      description: Enables the experimental `jaxrs.canceled` span attribute.
+      type: boolean
+      default: false
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
   - name: jaxrs-2.0-cxf-3.2
+    display_name: Apache CXF JAX-RS 2.x
+    description: |
+      This instrumentation enables spans for JAX-RS methods when using Apache CXF, and enriches existing HTTP server spans with route information.
+    library_link: https://cxf.apache.org/
     source_path: instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-cxf-3.2
     scope:
       name: io.opentelemetry.jaxrs-2.0-cxf-3.2
     target_versions:
       javaagent:
       - org.apache.tomee:openejb-cxf-rs:(8,)
       - org.apache.cxf:cxf-rt-frontend-jaxrs:[3.2,4)
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller (INTERNAL) spans.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.jaxrs.experimental-span-attributes
+      description: Enables the experimental `jaxrs.canceled` span attribute.
+      type: boolean
+      default: false
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
+    - when: otel.instrumentation.jaxrs.experimental-span-attributes=true
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
+        - name: jaxrs.canceled
+          type: BOOLEAN
   - name: jaxrs-2.0-jersey-2.0
+    display_name: Eclipse Jersey JAX-RS 2.x
+    description: |
+      This instrumentation enables spans for JAX-RS methods when using Jersey, and enriches existing HTTP server spans with route information.
+    library_link: https://eclipse-ee4j.github.io/jersey/
     source_path: instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-jersey-2.0
     scope:
       name: io.opentelemetry.jaxrs-2.0-jersey-2.0
     target_versions:
       javaagent:
       - org.glassfish.jersey.core:jersey-server:[2.0,3.0.0)
       - org.glassfish.jersey.containers:jersey-container-servlet:[2.0,3.0.0)
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller (INTERNAL) spans.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.jaxrs.experimental-span-attributes
+      description: Enables the experimental `jaxrs.canceled` span attribute.
+      type: boolean
+      default: false
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
+    - when: otel.instrumentation.jaxrs.experimental-span-attributes=true
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
+        - name: jaxrs.canceled
+          type: BOOLEAN
   - name: jaxrs-2.0-resteasy-3.0
+    display_name: JBoss RESTEasy JAX-RS 2.x
+    description: |
+      This instrumentation enables spans for JAX-RS methods when using RESTEasy, and enriches existing HTTP server spans with route information.
+    library_link: https://resteasy.dev/
     source_path: instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-resteasy-3.0
     scope:
       name: io.opentelemetry.jaxrs-2.0-resteasy-3.0
     target_versions:
       javaagent:
       - org.jboss.resteasy:resteasy-jaxrs:[3.0.0.Final,3.1.0.Final)
       - org.jboss.resteasy:resteasy-jaxrs:[3.5.0.Final,4)
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller (INTERNAL) spans.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.jaxrs.experimental-span-attributes
+      description: Enables the experimental `jaxrs.canceled` span attribute.
+      type: boolean
+      default: false
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
+    - when: otel.instrumentation.jaxrs.experimental-span-attributes=true
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
+        - name: jaxrs.canceled
+          type: BOOLEAN
   - name: jaxrs-2.0-resteasy-3.1
+    display_name: JBoss RESTEasy JAX-RS 2.x
+    description: |
+      This instrumentation enables spans for JAX-RS methods when using RESTEasy, and enriches existing HTTP server spans with route information.
+    library_link: https://resteasy.dev/
     source_path: instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-resteasy-3.1
     scope:
       name: io.opentelemetry.jaxrs-2.0-resteasy-3.1
     target_versions:
       javaagent:
       - org.jboss.resteasy:resteasy-jaxrs:[3.1.0.Final,3.5.0.Final)
       - org.jboss.resteasy:resteasy-core:[4.0.0.Final,6)
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller (INTERNAL) spans.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.jaxrs.experimental-span-attributes
+      description: Enables the experimental `jaxrs.canceled` span attribute.
+      type: boolean
+      default: false
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
+    - when: otel.instrumentation.jaxrs.experimental-span-attributes=true
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
+        - name: jaxrs.canceled
+          type: BOOLEAN
   - name: jaxrs-3.0-annotations
+    display_name: JAX-RS 3.x
+    description: |
+      This instrumentation enables spans for JAX-RS annotated methods, and enriches existing HTTP server spans with route information.
+    library_link: https://jakarta.ee/specifications/restful-ws/3.0/
     source_path: instrumentation/jaxrs/jaxrs-3.0/jaxrs-3.0-annotations
     scope:
       name: io.opentelemetry.jaxrs-3.0-annotations
     target_versions:
       javaagent:
       - jakarta.ws.rs:jakarta.ws.rs-api:[3.0.0,)
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller (INTERNAL) spans.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.jaxrs.experimental-span-attributes
+      description: Enables the experimental `jaxrs.canceled` span attribute.
+      type: boolean
+      default: false
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
   - name: jaxrs-3.0-jersey-3.0
+    display_name: Eclipse Jersey JAX-RS 3.x
+    description: |
+      This instrumentation enables spans for JAX-RS methods when using Jersey, and enriches existing HTTP server spans with route information.
+    library_link: https://eclipse-ee4j.github.io/jersey/
     source_path: instrumentation/jaxrs/jaxrs-3.0/jaxrs-3.0-jersey-3.0
     minimum_java_version: 11
     scope:
       name: io.opentelemetry.jaxrs-3.0-jersey-3.0
     target_versions:
       javaagent:
       - org.glassfish.jersey.core:jersey-server:[3.0.0,)
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller (INTERNAL) spans.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.jaxrs.experimental-span-attributes
+      description: Enables the experimental `jaxrs.canceled` span attribute.
+      type: boolean
+      default: false
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
+    - when: otel.instrumentation.jaxrs.experimental-span-attributes=true
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
+        - name: jaxrs.canceled
+          type: BOOLEAN
   - name: jaxrs-3.0-resteasy-6.0
+    display_name: JBoss RESTEasy JAX-RS 3.x
+    description: |
+      This instrumentation enables spans for JAX-RS methods when using RESTEasy, and enriches existing HTTP server spans with route information.
+    library_link: https://resteasy.dev/
     source_path: instrumentation/jaxrs/jaxrs-3.0/jaxrs-3.0-resteasy-6.0
     minimum_java_version: 11
     scope:
       name: io.opentelemetry.jaxrs-3.0-resteasy-6.0
     target_versions:
       javaagent:
       - org.jboss.resteasy:resteasy-core:[6.0.0.Final,)
+    configurations:
+    - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+      description: Enables the creation of experimental controller (INTERNAL) spans.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.jaxrs.experimental-span-attributes
+      description: Enables the experimental `jaxrs.canceled` span attribute.
+      type: boolean
+      default: false
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
+    - when: otel.instrumentation.jaxrs.experimental-span-attributes=true
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
+        - name: jaxrs.canceled
+          type: BOOLEAN
   jaxws:
   - name: jaxws-2.0
     source_path: instrumentation/jaxws/jaxws-2.0

instrumentation-docs/instrumentations.sh

@@ -159,6 +159,21 @@ readonly INSTRUMENTATIONS=(
   "influxdb-2.4:javaagent:testStableSemconv"
   "java-http-server:javaagent:test"
   "failsafe-3.0:library:test"
+  "jaxrs:jaxrs-1.0:javaagent:test"
+  "jaxrs:jaxrs-2.0:jaxrs-2.0-annotations:javaagent:test"
+  "jaxrs:jaxrs-2.0:jaxrs-2.0-cxf-3.2:javaagent:test"
+  "jaxrs:jaxrs-2.0:jaxrs-2.0-cxf-3.2:javaagent:testExperimental"
+  "jaxrs:jaxrs-2.0:jaxrs-2.0-jersey-2.0:javaagent:test"
+  "jaxrs:jaxrs-2.0:jaxrs-2.0-jersey-2.0:javaagent:testExperimental"
+  "jaxrs:jaxrs-2.0:jaxrs-2.0-resteasy-3.0:javaagent:test"
+  "jaxrs:jaxrs-2.0:jaxrs-2.0-resteasy-3.0:javaagent:testExperimental"
+  "jaxrs:jaxrs-2.0:jaxrs-2.0-resteasy-3.1:javaagent:test"
+  "jaxrs:jaxrs-2.0:jaxrs-2.0-resteasy-3.1:javaagent:testExperimental"
+  "jaxrs:jaxrs-3.0:jaxrs-3.0-annotations:javaagent:test"
+  "jaxrs:jaxrs-3.0:jaxrs-3.0-jersey-3.0:javaagent:test"
+  "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"
 )
 
 #  Some instrumentation test suites don't run ARM, so we use colima to run them in an x86_64

instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/parsers/TelemetryParser.java

@@ -19,7 +19,17 @@ class TelemetryParser {
           "io.opentelemetry.couchbase-2.6", Set.of("io.opentelemetry.couchbase-2.0"),
           // elasticsearch-rest-7.0 extends elasticsearch-api-client-7.16 with more attributes.
           "io.opentelemetry.elasticsearch-api-client-7.16",
-              Set.of("io.opentelemetry.elasticsearch-rest-7.0"));
+              Set.of("io.opentelemetry.elasticsearch-rest-7.0"),
+          // jaxrs instrumentations add attributes to the jaxrs-2.0-annotations scope.
+          "io.opentelemetry.jaxrs-2.0-cxf-3.2", Set.of("io.opentelemetry.jaxrs-2.0-annotations"),
+          "io.opentelemetry.jaxrs-2.0-jersey-2.0", Set.of("io.opentelemetry.jaxrs-2.0-annotations"),
+          "io.opentelemetry.jaxrs-2.0-resteasy-3.0",
+              Set.of("io.opentelemetry.jaxrs-2.0-annotations"),
+          "io.opentelemetry.jaxrs-2.0-resteasy-3.1",
+              Set.of("io.opentelemetry.jaxrs-2.0-annotations"),
+          "io.opentelemetry.jaxrs-3.0-jersey-3.0", Set.of("io.opentelemetry.jaxrs-3.0-annotations"),
+          "io.opentelemetry.jaxrs-3.0-resteasy-6.0",
+              Set.of("io.opentelemetry.jaxrs-3.0-annotations"));
 
   /**
    * Checks if the given telemetry scope is valid for the specified module scope.

instrumentation/jaxrs/jaxrs-1.0/javaagent/build.gradle.kts

@@ -35,4 +35,6 @@ tasks.withType<Test>().configureEach {
   // required on jdk17
   jvmArgs("--add-opens=java.base/java.lang=ALL-UNNAMED")
   jvmArgs("-XX:+IgnoreUnrecognizedVMOptions")
+
+  systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
 }

instrumentation/jaxrs/jaxrs-1.0/metadata.yaml

@@ -1 +1,10 @@
-disabled_by_default: true
+display_name: JAX-RS 1.x
+description: >
+  This instrumentation enables spans for JAX-RS methods, and enriches existing HTTP server spans
+  with route information.
+library_link: https://javaee.github.io/javaee-spec/javadocs/javax/ws/rs/package-summary.html
+configurations:
+  - name: otel.instrumentation.common.experimental.controller-telemetry.enabled
+    description: Enables the creation of experimental controller (INTERNAL) spans.
+    type: boolean
+    default: false

instrumentation/jaxrs/jaxrs-2.0/jaxrs-2.0-annotations/javaagent/build.gradle.kts

@@ -28,5 +28,7 @@ dependencies {
 tasks {
   withType<Test>().configureEach {
     jvmArgs("-Dotel.instrumentation.common.experimental.controller-telemetry.enabled=true")
+
+    systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
   }
 }