Add descriptions for httpclients and other instrumentations

docs/instrumentation-list.yaml

@@ -77,6 +77,8 @@ libraries:
       - com.typesafe.akka:akka-actor_2.13:[2.5.23,2.6)
       - com.typesafe.akka:akka-actor_2.11:[2.5,)
   - name: akka-http-10.0
+    description: This instrumentation enables CLIENT and SERVER spans and metrics
+      for the Akka HTTP client and server.
     source_path: instrumentation/akka/akka-http-10.0
     scope:
       name: io.opentelemetry.akka-http-10.0
@@ -565,6 +567,8 @@ libraries:
         - name: url.full
           type: STRING
   - name: apache-httpclient-5.0
+    description: This instrumentation provides CLIENT spans and metrics for version
+      5 of the Apache HttpClient.
     source_path: instrumentation/apache-httpclient/apache-httpclient-5.0
     scope:
       name: io.opentelemetry.apache-httpclient-5.0
@@ -589,14 +593,76 @@ libraries:
           type: STRING
         - name: server.port
           type: LONG
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: error.type
+          type: STRING
+        - name: http.request.method
+          type: STRING
+        - name: http.request.method_original
+          type: STRING
+        - name: http.response.status_code
+          type: LONG
+        - name: network.protocol.version
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+        - name: url.full
+          type: STRING
   - name: apache-httpclient-5.2
+    description: This instrumentation provides a library integration that enables
+      CLIENT spans and metrics for the Apache HttpClient.
     source_path: instrumentation/apache-httpclient/apache-httpclient-5.2
     scope:
       name: io.opentelemetry.apache-httpclient-5.2
     target_versions:
       library:
       - org.apache.httpcomponents.client5:httpclient5:5.2.1
+    telemetry:
+    - when: default
+      metrics:
+      - name: http.client.request.duration
+        description: Duration of HTTP client requests.
+        type: HISTOGRAM
+        unit: s
+        attributes:
+        - name: http.request.method
+          type: STRING
+        - name: http.response.status_code
+          type: LONG
+        - name: network.protocol.version
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: error.type
+          type: STRING
+        - name: http.request.method
+          type: STRING
+        - name: http.request.method_original
+          type: STRING
+        - name: http.request.resend_count
+          type: LONG
+        - name: http.response.status_code
+          type: LONG
+        - name: network.protocol.version
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+        - name: url.full
+          type: STRING
   - name: apache-shenyu-2.4
+    description: |
+      This instrumentation does not emit telemetry on its own. Instead, it hooks into the Shenyu Context and extracts meta data in order to attach it to existing SERVER spans and HTTP server metrics.
     source_path: instrumentation/apache-shenyu-2.4
     scope:
       name: io.opentelemetry.apache-shenyu-2.4
@@ -605,11 +671,14 @@ libraries:
       - org.apache.shenyu:shenyu-web:[2.4.0,)
     configurations:
     - name: otel.instrumentation.apache-shenyu.experimental-span-attributes
-      description: Enables experimental span attributes for Apache Shenyu instrumentation.
+      description: |
+        Enables experimental `apache-shenyu.meta.` prefixed span attributes like `app-name`, `service-name`, `context-path`, `param-types`, `id`, `method-name`, `rpc-type`, `path`, and `rpc-ext`.
       type: boolean
       default: false
   armeria:
   - name: armeria-1.3
+    description: This instrumentation enables CLIENT spans and metrics for the Armeria
+      HTTP client and server.
     source_path: instrumentation/armeria/armeria-1.3
     scope:
       name: io.opentelemetry.armeria-1.3
@@ -618,7 +687,93 @@ libraries:
       - com.linecorp.armeria:armeria:[1.3.0,)
       library:
       - com.linecorp.armeria:armeria:1.3.0
+    telemetry:
+    - when: default
+      metrics:
+      - name: http.client.request.duration
+        description: Duration of HTTP client requests.
+        type: HISTOGRAM
+        unit: s
+        attributes:
+        - name: http.request.method
+          type: STRING
+        - name: http.response.status_code
+          type: LONG
+        - name: network.protocol.version
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+      - name: http.server.request.duration
+        description: Duration of HTTP server requests.
+        type: HISTOGRAM
+        unit: s
+        attributes:
+        - name: http.request.method
+          type: STRING
+        - name: http.response.status_code
+          type: LONG
+        - name: http.route
+          type: STRING
+        - name: network.protocol.version
+          type: STRING
+        - name: url.scheme
+          type: STRING
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: error.type
+          type: STRING
+        - name: http.request.method
+          type: STRING
+        - name: http.response.status_code
+          type: LONG
+        - name: network.peer.address
+          type: STRING
+        - name: network.peer.port
+          type: LONG
+        - name: network.protocol.version
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+        - name: url.full
+          type: STRING
+      - span_kind: SERVER
+        attributes:
+        - name: client.address
+          type: STRING
+        - name: error.type
+          type: STRING
+        - name: http.request.method
+          type: STRING
+        - name: http.response.status_code
+          type: LONG
+        - name: http.route
+          type: STRING
+        - name: network.peer.address
+          type: STRING
+        - name: network.peer.port
+          type: LONG
+        - name: network.protocol.version
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+        - name: url.path
+          type: STRING
+        - name: url.query
+          type: STRING
+        - name: url.scheme
+          type: STRING
+        - name: user_agent.original
+          type: STRING
   - name: armeria-grpc-1.14
+    description: This instrumentation enables CLIENT spans and metrics for the Armeria
+      gRPC client and server.
     source_path: instrumentation/armeria/armeria-grpc-1.14
     scope:
       name: io.opentelemetry.armeria-grpc-1.14
@@ -627,19 +782,97 @@ libraries:
       - com.linecorp.armeria:armeria-grpc:[1.14.0,)
   async:
   - name: async-http-client-1.9
+    description: This instrumentation provides CLIENT spans and metrics for version
+      1 of the AsyncHttpClient (AHC) HTTP client.
     source_path: instrumentation/async-http-client/async-http-client-1.9
     scope:
       name: io.opentelemetry.async-http-client-1.9
     target_versions:
       javaagent:
       - com.ning:async-http-client:[1.9.0,)
+    telemetry:
+    - when: default
+      metrics:
+      - name: http.client.request.duration
+        description: Duration of HTTP client requests.
+        type: HISTOGRAM
+        unit: s
+        attributes:
+        - name: http.request.method
+          type: STRING
+        - name: http.response.status_code
+          type: LONG
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: error.type
+          type: STRING
+        - name: http.request.method
+          type: STRING
+        - name: http.request.method_original
+          type: STRING
+        - name: http.response.status_code
+          type: LONG
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+        - name: url.full
+          type: STRING
   - name: async-http-client-2.0
+    description: This instrumentation provides CLIENT spans and metrics for version
+      2 of the AsyncHttpClient (AHC) HTTP client.
     source_path: instrumentation/async-http-client/async-http-client-2.0
     scope:
       name: io.opentelemetry.async-http-client-2.0
     target_versions:
       javaagent:
       - org.asynchttpclient:async-http-client:[2.0.0,)
+    telemetry:
+    - when: default
+      metrics:
+      - name: http.client.request.duration
+        description: Duration of HTTP client requests.
+        type: HISTOGRAM
+        unit: s
+        attributes:
+        - name: http.request.method
+          type: STRING
+        - name: http.response.status_code
+          type: LONG
+        - name: network.protocol.version
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+      spans:
+      - span_kind: CLIENT
+        attributes:
+        - name: error.type
+          type: STRING
+        - name: http.request.method
+          type: STRING
+        - name: http.request.method_original
+          type: STRING
+        - name: http.response.status_code
+          type: LONG
+        - name: network.peer.address
+          type: STRING
+        - name: network.peer.port
+          type: LONG
+        - name: network.protocol.version
+          type: STRING
+        - name: server.address
+          type: STRING
+        - name: server.port
+          type: LONG
+        - name: url.full
+          type: STRING
   avaje:
   - name: avaje-jex-3.0
     description: |
@@ -1468,6 +1701,8 @@ libraries:
       default: false
   finagle:
   - name: finagle-http-23.11
+    description: |
+      This instrumentation for Finagle HTTP clients and servers ensures that telemetry is correctly generated by the underlying Netty instrumentation. It augments existing telemetry by bridging the gap between Finagle's abstractions and Netty's pipeline, primarily for context propagation.
     source_path: instrumentation/finagle-http-23.11
     scope:
       name: io.opentelemetry.finagle-http-23.11
@@ -1477,13 +1712,25 @@ libraries:
       - com.twitter:finagle-http_2.12:[23.11.0,]
   finatra:
   - name: finatra-2.9
+    description: This instrumentation for the Finatra web framework augments the telemetry
+      generated by the underlying Netty instrumentation. It provides more specific,
+      high-level context, such as route information, to the spans generated by Netty.
     source_path: instrumentation/finatra-2.9
     scope:
       name: io.opentelemetry.finatra-2.9
     target_versions:
       javaagent:
       - com.twitter:finatra-http_2.11:[2.9.0,]
       - com.twitter:finatra-http_2.12:[2.9.0,]
+    telemetry:
+    - when: default
+      spans:
+      - span_kind: INTERNAL
+        attributes:
+        - name: code.function
+          type: STRING
+        - name: code.namespace
+          type: STRING
   geode:
   - name: geode-1.4
     source_path: instrumentation/geode-1.4
@@ -2194,6 +2441,8 @@ libraries:
       - org.apache.tomcat:tomcat-jasper:[7.0.19,10)
   kafka:
   - name: kafka-clients-0.11
+    description: |
+      This instrumentation provides messaging spans and metrics for Apache Kafka 0.11 clients. It automatically traces message production and consumption, propagates context, and emits metrics for production and consumption.
     source_path: instrumentation/kafka/kafka-clients/kafka-clients-0.11
     scope:
       name: io.opentelemetry.kafka-clients-0.11
@@ -2209,7 +2458,17 @@ libraries:
       description: Enables the capture of the experimental consumer attribute "kafka.record.queue_time_ms"
       type: boolean
       default: false
+    - name: otel.instrumentation.messaging.experimental.capture-headers
+      description: A comma-separated list of header names to capture as span attributes.
+      type: list
+      default: ''
+    - name: otel.instrumentation.messaging.experimental.receive-telemetry.enabled
+      description: Enables experimental receive telemetry for Kafka instrumentation.
+      type: boolean
+      default: false
   - name: kafka-clients-2.6
+    description: |
+      This instrumentation provides a library integeration that enables messaging spans and metrics for Apache Kafka 2.6+ clients.
     source_path: instrumentation/kafka/kafka-clients/kafka-clients-2.6
     scope:
       name: io.opentelemetry.kafka-clients-2.6
@@ -3965,6 +4224,10 @@ internal:
   source_path: instrumentation/internal/internal-reflection
   scope:
     name: io.opentelemetry.internal-reflection
+- name: opentelemetry-api-1.52
+  source_path: instrumentation/opentelemetry-api/opentelemetry-api-1.52
+  scope:
+    name: io.opentelemetry.opentelemetry-api-1.52
 - name: opentelemetry-instrumentation-api
   source_path: instrumentation/opentelemetry-instrumentation-api
   scope:

instrumentation-docs/collect.sh

@@ -10,6 +10,7 @@ readonly INSTRUMENTATIONS=(
   # <module path (colon-separated)> : <javaagent|library> : [ gradle-task-suffix ]
   "activej-http-6.0:javaagent:test"
   "akka:akka-http-10.0:javaagent:test"
+  "armeria:armeria-grpc-1.14:javaagent:test"
   "apache-httpasyncclient-4.1:javaagent:test"
   "alibaba-druid-1.0:javaagent:test"
   "alibaba-druid-1.0:javaagent:testStableSemconv"
@@ -82,6 +83,13 @@ readonly INSTRUMENTATIONS=(
   "elasticsearch:elasticsearch-transport-6.0:javaagent:elasticsearch7Test"
   "elasticsearch:elasticsearch-transport-6.0:javaagent:elasticsearch7TestStableSemconv"
   "elasticsearch:elasticsearch-transport-6.0:javaagent:elasticsearch7TestExperimental"
+  "apache-httpclient:apache-httpclient-5.2:library:test"
+  "armeria:armeria-1.3:javaagent:test"
+  "async-http-client:async-http-client-1.9:javaagent:test"
+  "async-http-client:async-http-client-2.0:javaagent:test"
+  "apache-dubbo-2.7:javaagent:testDubbo"
+  "finagle-http-23.11:javaagent:test"
+  "finatra-2.9:javaagent:test"
 )
 
 readonly COLIMA_INSTRUMENTATIONS=(

instrumentation/akka/akka-http-10.0/metadata.yaml

@@ -0,0 +1 @@
+description: This instrumentation enables CLIENT and SERVER spans and metrics for the Akka HTTP client and server.