Add descriptions for httpclients and other instrumentations (#14248)

jaydeluca · web-flow · commit 744474a6bb73 · 2025-07-22T13:00:46.000+03:00
diff --git a/docs/instrumentation-list.yaml b/docs/instrumentation-list.yaml
diff --git a/instrumentation-docs/collect.sh b/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=(
diff --git a/instrumentation/activej-http-6.0/metadata.yaml b/instrumentation/activej-http-6.0/metadata.yaml
@@ -1 +1 @@
-description: This instrumentation provides SERVER spans and metrics for the ActiveJ HTTP server.
+description: This instrumentation enables SERVER spans and metrics for the ActiveJ HTTP server.
diff --git a/instrumentation/akka/akka-http-10.0/metadata.yaml b/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.
diff --git a/instrumentation/apache-dbcp-2.0/metadata.yaml b/instrumentation/apache-dbcp-2.0/metadata.yaml
@@ -1,5 +1,5 @@
 description: >
-  This instrumentation provides database connection pools metrics for Apache DBCP.
+  This instrumentation enables database connection pools metrics for Apache DBCP.
 
   The instrumentation uses `MBeanRegistration` methods for lifecycle detection, therefore it
   only activates if the `BasicDataSource` is registered to an `MBeanServer`. If using Spring Boot,
diff --git a/instrumentation/apache-httpasyncclient-4.1/metadata.yaml b/instrumentation/apache-httpasyncclient-4.1/metadata.yaml
@@ -1 +1 @@
-description: This instrumentation provides CLIENT spans and metrics for the Apache HttpAsyncClient.
+description: This instrumentation enables CLIENT spans and metrics for the Apache HttpAsyncClient.
diff --git a/instrumentation/apache-httpclient/apache-httpclient-2.0/metadata.yaml b/instrumentation/apache-httpclient/apache-httpclient-2.0/metadata.yaml
@@ -1 +1 @@
-description: This instrumentation provides CLIENT spans and metrics for versions 2 and 3 of the Apache HttpClient.
+description: This instrumentation enables CLIENT spans and metrics for versions 2 and 3 of the Apache HttpClient.
diff --git a/instrumentation/apache-httpclient/apache-httpclient-4.0/metadata.yaml b/instrumentation/apache-httpclient/apache-httpclient-4.0/metadata.yaml
@@ -1 +1 @@
-description: This instrumentation provides CLIENT spans and metrics for version 4 of the Apache HttpClient.
+description: This instrumentation enables CLIENT spans and metrics for version 4 of the Apache HttpClient.
diff --git a/instrumentation/apache-httpclient/apache-httpclient-5.0/javaagent/build.gradle.kts b/instrumentation/apache-httpclient/apache-httpclient-5.0/javaagent/build.gradle.kts
@@ -23,5 +23,6 @@ tasks {
 
   test {
     systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+    systemProperty("collectSpans", true)
   }
 }
diff --git a/instrumentation/apache-httpclient/apache-httpclient-5.0/metadata.yaml b/instrumentation/apache-httpclient/apache-httpclient-5.0/metadata.yaml
@@ -0,0 +1 @@
+description: This instrumentation enables CLIENT spans and metrics for version 5 of the Apache HttpClient.
diff --git a/instrumentation/apache-httpclient/apache-httpclient-5.2/library/build.gradle.kts b/instrumentation/apache-httpclient/apache-httpclient-5.2/library/build.gradle.kts
@@ -7,3 +7,10 @@ plugins {
 dependencies {
   library("org.apache.httpcomponents.client5:httpclient5:5.2.1")
 }
+
+tasks {
+  test {
+    systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+    systemProperty("collectSpans", true)
+  }
+}
diff --git a/instrumentation/apache-httpclient/apache-httpclient-5.2/library/metadata.yaml b/instrumentation/apache-httpclient/apache-httpclient-5.2/library/metadata.yaml
@@ -0,0 +1 @@
+description: This instrumentation enables CLIENT spans and metrics for the Apache HttpAsyncClient.
diff --git a/instrumentation/apache-httpclient/apache-httpclient-5.2/metadata.yaml b/instrumentation/apache-httpclient/apache-httpclient-5.2/metadata.yaml
@@ -0,0 +1 @@
+description: This instrumentation provides a library integration that enables CLIENT spans and metrics for the Apache HttpClient.
diff --git a/instrumentation/apache-shenyu-2.4/javaagent/build.gradle.kts b/instrumentation/apache-shenyu-2.4/javaagent/build.gradle.kts
@@ -44,6 +44,10 @@ if (latestDepTest) {
 tasks.withType<Test>().configureEach {
   jvmArgs("-Dotel.instrumentation.apache-shenyu.experimental-span-attributes=true")
 
+  systemProperty("metaDataConfig", "otel.instrumentation.apache-shenyu.experimental-span-attributes=true")
+  systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+  systemProperty("collectSpans", true)
+
   // required on jdk17
   jvmArgs("--add-opens=java.base/java.lang=ALL-UNNAMED")
   jvmArgs("-XX:+IgnoreUnrecognizedVMOptions")
diff --git a/instrumentation/apache-shenyu-2.4/metadata.yaml b/instrumentation/apache-shenyu-2.4/metadata.yaml
@@ -1,5 +1,11 @@
+description: >
+  This instrumentation does not emit telemetry on its own. Instead, it augments existing SERVER
+  spans and HTTP server metrics with the HTTP route and Shenyu specific attributes.
 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 `app-name`,
+      `service-name`, `context-path`, `param-types`, `id`, `method-name`, `rpc-type`, `path` and
+      `rpc-ext`.
     type: boolean
     default: false
diff --git a/instrumentation/armeria/armeria-1.3/javaagent/build.gradle.kts b/instrumentation/armeria/armeria-1.3/javaagent/build.gradle.kts
@@ -27,5 +27,7 @@ dependencies {
 tasks {
   withType<Test>().configureEach {
     systemProperty("testLatestDeps", findProperty("testLatestDeps") as Boolean)
+    systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+    systemProperty("collectSpans", true)
   }
 }
diff --git a/instrumentation/armeria/armeria-1.3/metadata.yaml b/instrumentation/armeria/armeria-1.3/metadata.yaml
@@ -0,0 +1 @@
+description: This instrumentation enables CLIENT and SERVER spans and metrics for the Armeria HTTP client and server.
diff --git a/instrumentation/armeria/armeria-grpc-1.14/javaagent/build.gradle.kts b/instrumentation/armeria/armeria-grpc-1.14/javaagent/build.gradle.kts
@@ -53,3 +53,8 @@ afterEvaluate {
     add("testCompileProtoPath", platform(project(":dependencyManagement")))
   }
 }
+
+tasks.test {
+  systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+  systemProperty("collectSpans", true)
+}
diff --git a/instrumentation/armeria/armeria-grpc-1.14/metadata.yaml b/instrumentation/armeria/armeria-grpc-1.14/metadata.yaml
@@ -0,0 +1 @@
+description: This instrumentation enables CLIENT and SERVER spans and metrics for the Armeria gRPC client and server.
diff --git a/instrumentation/async-http-client/async-http-client-1.9/javaagent/build.gradle.kts b/instrumentation/async-http-client/async-http-client-1.9/javaagent/build.gradle.kts
@@ -27,5 +27,8 @@ tasks {
     jvmArgs("-XX:+IgnoreUnrecognizedVMOptions")
 
     systemProperty("testLatestDeps", findProperty("testLatestDeps") as Boolean)
+
+    systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+    systemProperty("collectSpans", true)
   }
 }
diff --git a/instrumentation/async-http-client/async-http-client-1.9/metadata.yaml b/instrumentation/async-http-client/async-http-client-1.9/metadata.yaml
@@ -0,0 +1 @@
+description: This instrumentation enables CLIENT spans and metrics for version 1 of the AsyncHttpClient (AHC) HTTP client.
diff --git a/instrumentation/async-http-client/async-http-client-2.0/javaagent/build.gradle.kts b/instrumentation/async-http-client/async-http-client-2.0/javaagent/build.gradle.kts
@@ -39,6 +39,9 @@ tasks.withType<Test>().configureEach {
   if (latestDepTest && testJavaVersion.isJava8) {
     enabled = false
   }
+
+  systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+  systemProperty("collectSpans", true)
 }
 
 // async-http-client 2.0.0 does not work with Netty versions newer than this due to referencing an
diff --git a/instrumentation/async-http-client/async-http-client-2.0/metadata.yaml b/instrumentation/async-http-client/async-http-client-2.0/metadata.yaml
@@ -0,0 +1 @@
+description: This instrumentation enables CLIENT spans and metrics for version 2 of the AsyncHttpClient (AHC) HTTP client.
diff --git a/instrumentation/camel-2.20/metadata.yaml b/instrumentation/camel-2.20/metadata.yaml
@@ -1,5 +1,5 @@
 description: >
-  This instrumentation provides tracing for Apache Camel 2.x applications by generating spans for
+  This instrumentation enables tracing for Apache Camel 2.x applications by generating spans for
   each route execution. For Camel versions 3.5 and newer, users should instead use the native
   'camel-opentelemetry' component provided directly by the Camel project.
 configurations:
diff --git a/instrumentation/elasticsearch/elasticsearch-api-client-7.16/metadata.yaml b/instrumentation/elasticsearch/elasticsearch-api-client-7.16/metadata.yaml
@@ -1,2 +1,2 @@
-description: This instrumentation provides client spans for Elasticsearch API client requests for
+description: This instrumentation enables client spans for Elasticsearch API client requests for
   version 7 of the client. Versions 8.10 and later have native support for OpenTelemetry.
diff --git a/instrumentation/elasticsearch/elasticsearch-rest-5.0/metadata.yaml b/instrumentation/elasticsearch/elasticsearch-rest-5.0/metadata.yaml
@@ -1,8 +1,8 @@
-description: This instrumentation provides tracing for Elasticsearch REST clients.
+description: This instrumentation enables tracing for Elasticsearch REST clients.
 configurations:
   - name: otel.instrumentation.elasticsearch.capture-search-query
     description: |
       Enable the capture of search query bodies. It is important to note that Elasticsearch queries
       may contain personal or sensitive information.
     type: boolean
-    default: false
+    default: false
diff --git a/instrumentation/elasticsearch/elasticsearch-rest-6.4/metadata.yaml b/instrumentation/elasticsearch/elasticsearch-rest-6.4/metadata.yaml
@@ -1,8 +1,8 @@
-description: This instrumentation provides tracing for Elasticsearch REST clients.
+description: This instrumentation enables tracing for Elasticsearch REST clients.
 configurations:
   - name: otel.instrumentation.elasticsearch.capture-search-query
     description: >
       Enable the capture of search query bodies. It is important to note that Elasticsearch queries
       may contain personal or sensitive information.
     type: boolean
-    default: false
+    default: false
diff --git a/instrumentation/elasticsearch/elasticsearch-rest-7.0/metadata.yaml b/instrumentation/elasticsearch/elasticsearch-rest-7.0/metadata.yaml
@@ -1,8 +1,8 @@
-description: This instrumentation provides tracing for Elasticsearch REST clients.
+description: This instrumentation enables tracing for Elasticsearch REST clients.
 configurations:
   - name: otel.instrumentation.elasticsearch.capture-search-query
     description: >
       Enable the capture of search query bodies. It is important to note that Elasticsearch queries
       may contain personal or sensitive information.
     type: boolean
-    default: false
+    default: false
diff --git a/instrumentation/elasticsearch/elasticsearch-transport-5.0/metadata.yaml b/instrumentation/elasticsearch/elasticsearch-transport-5.0/metadata.yaml
@@ -1,5 +1,5 @@
 description: >
-  This instrumentation provides client spans for Elasticsearch transport client requests. Each call
+  This instrumentation enables client spans for Elasticsearch transport client requests. Each call
   produces a span named after the Elasticsearch action, enriched with transport-specific attributes.
 configurations:
   - name: otel.instrumentation.elasticsearch.experimental-span-attributes
diff --git a/instrumentation/elasticsearch/elasticsearch-transport-5.3/metadata.yaml b/instrumentation/elasticsearch/elasticsearch-transport-5.3/metadata.yaml
@@ -1,5 +1,5 @@
 description: >
-  This instrumentation provides client spans for Elasticsearch transport client requests. Each call
+  This instrumentation enables client spans for Elasticsearch transport client requests. Each call
   produces a span named after the Elasticsearch action, enriched with transport-specific attributes.
 configurations:
   - name: otel.instrumentation.elasticsearch.experimental-span-attributes
diff --git a/instrumentation/elasticsearch/elasticsearch-transport-6.0/metadata.yaml b/instrumentation/elasticsearch/elasticsearch-transport-6.0/metadata.yaml
@@ -1,5 +1,5 @@
 description: >
-  This instrumentation provides client spans for Elasticsearch transport client requests. Each call
+  This instrumentation enables client spans for Elasticsearch transport client requests. Each call
   produces a span named after the Elasticsearch action, enriched with transport-specific attributes.
 configurations:
   - name: otel.instrumentation.elasticsearch.experimental-span-attributes
diff --git a/instrumentation/finagle-http-23.11/javaagent/build.gradle.kts b/instrumentation/finagle-http-23.11/javaagent/build.gradle.kts
@@ -44,5 +44,8 @@ tasks {
   test {
     jvmArgs("-Dotel.instrumentation.http.client.emit-experimental-telemetry=true")
     jvmArgs("-Dotel.instrumentation.http.server.emit-experimental-telemetry=true")
+    systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+    systemProperty("collectSpans", true)
+    systemProperty("metaDataConfig", "otel.instrumentation.http.client.emit-experimental-telemetry=true,otel.instrumentation.http.server.emit-experimental-telemetry=true")
   }
 }
diff --git a/instrumentation/finagle-http-23.11/metadata.yaml b/instrumentation/finagle-http-23.11/metadata.yaml
@@ -0,0 +1,4 @@
+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.
diff --git a/instrumentation/finatra-2.9/javaagent/build.gradle.kts b/instrumentation/finatra-2.9/javaagent/build.gradle.kts
@@ -85,6 +85,8 @@ tasks {
     // 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("collectSpans", true)
   }
 }
diff --git a/instrumentation/finatra-2.9/metadata.yaml b/instrumentation/finatra-2.9/metadata.yaml
@@ -0,0 +1 @@
+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.
diff --git a/instrumentation/kafka/kafka-clients/kafka-clients-0.11/metadata.yaml b/instrumentation/kafka/kafka-clients/kafka-clients-0.11/metadata.yaml
@@ -1,5 +1,5 @@
 description: >
-  This instrumentation provides messaging spans and metrics for Apache Kafka 0.11 clients.
+  This instrumentation enables 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.
 configurations:
   - name: otel.instrumentation.kafka.producer-propagation.enabled

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-description: This instrumentation provides SERVER spans and metrics for the ActiveJ HTTP server.`
	`1`	`+description: This instrumentation enables SERVER spans and metrics for the ActiveJ HTTP server.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+description: This instrumentation enables CLIENT and SERVER spans and metrics for the Akka HTTP client and server.`
Original file line number	Diff line number	Diff line change
`@@ -23,5 +23,6 @@ tasks {`
`23`	`23`
`24`	`24`	`test {`
`25`	`25`	`systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")`
	`26`	`+ systemProperty("collectSpans", true)`
`26`	`27`	`}`
`27`	`28`	`}`