more modules and print description checklist

Author: jaydeluca

docs/instrumentation-list.yaml

@@ -470,8 +470,8 @@ libraries:
         - name: url.full
           type: STRING
   - name: apache-httpclient-4.0
-    description: This instrumentation provides CLIENT spans and metrics for versions
-      2 and 3 of the Apache HttpClient.
+    description: This instrumentation provides CLIENT spans and metrics for version
+      4 of the Apache HttpClient.
     source_path: instrumentation/apache-httpclient/apache-httpclient-4.0
     scope:
       name: io.opentelemetry.apache-httpclient-4.0
@@ -517,12 +517,53 @@ libraries:
         - name: url.full
           type: STRING
   - name: apache-httpclient-4.3
+    description: This instrumentation provides a library integration that enables
+      CLIENT spans and metrics for the Apache HttpClient.
     source_path: instrumentation/apache-httpclient/apache-httpclient-4.3
     scope:
       name: io.opentelemetry.apache-httpclient-4.3
     target_versions:
       library:
       - org.apache.httpcomponents:httpclient:[4.3,4.+)
+    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-httpclient-5.0
     source_path: instrumentation/apache-httpclient/apache-httpclient-5.0
     scope:
@@ -3000,6 +3041,8 @@ libraries:
       - jakarta.servlet:jakarta.servlet-api:[5.0.0,)
   spark:
   - name: spark-2.3
+    description: |
+      This instrumentation does not emit telemetry on its own. Instead, it extracts the HTTP route and attaches it to SERVER spans and HTTP server metrics.
     source_path: instrumentation/spark-2.3
     scope:
       name: io.opentelemetry.spark-2.3

instrumentation-docs/collect.sh

@@ -22,7 +22,8 @@ readonly INSTRUMENTATIONS=(
 #  "apache-dbcp-2.0:javaagent:test"
 #  "apache-dbcp-2.0:javaagent:testStableSemconv"
 #  "apache-httpclient:apache-httpclient-2.0:javaagent:test"
-  "apache-httpclient:apache-httpclient-4.0:javaagent:test"
+#  "apache-httpclient:apache-httpclient-4.0:javaagent:test"
+  "apache-httpclient:apache-httpclient-4.3:library:test"
 #  "apache-httpclient:apache-httpclient-5.0:javaagent:test"
 #  "apache-dubbo-2.7:javaagent:testDubbo"
 #  "c3p0-0.9:javaagent:test"

instrumentation-docs/src/main/java/io/opentelemetry/instrumentation/docs/DocGeneratorApplication.java

@@ -14,6 +14,7 @@
 import java.io.IOException;
 import java.nio.file.Files;
 import java.nio.file.Paths;
+import java.util.Comparator;
 import java.util.List;
 import java.util.Locale;
 import java.util.TreeMap;
@@ -82,6 +83,8 @@ private static void printStats(List<InstrumentationModule> modules) {
             getPercentage("configurations", withConfigurations, modules.size()));
 
     logger.info(stats);
+
+    logger.info(modulesWithDescriptions(modules));
   }
 
   private static String getClassificationStats(List<InstrumentationModule> modules) {
@@ -108,7 +111,7 @@ private static String getPercentage(String label, long numerator, long denominat
   }
 
   @SuppressWarnings("unused") // helper method used for project tracking
-  private static String listModules(List<InstrumentationModule> modules) {
+  private static String listAllModules(List<InstrumentationModule> modules) {
     // Create a checklist of all modules sorted by name
     return modules.stream()
         .map(InstrumentationModule::getInstrumentationName)
@@ -117,5 +120,22 @@ private static String listModules(List<InstrumentationModule> modules) {
         .collect(Collectors.joining("\n"));
   }
 
+  @SuppressWarnings("unused") // helper method used for project tracking
+  private static String modulesWithDescriptions(List<InstrumentationModule> modules) {
+    // Create a checklist of all modules sorted by name, checked if description is set
+    return modules.stream()
+        .sorted(Comparator.comparing(InstrumentationModule::getInstrumentationName))
+        .map(
+            module -> {
+              boolean hasDescription =
+                  module.getMetadata() != null
+                      && module.getMetadata().getDescription() != null
+                      && !module.getMetadata().getDescription().isEmpty();
+              String checkbox = hasDescription ? "- [x] " : "- [ ] ";
+              return checkbox + module.getInstrumentationName();
+            })
+        .collect(Collectors.joining("\n"));
+  }
+
   private DocGeneratorApplication() {}
 }

instrumentation/apache-httpclient/apache-httpclient-4.3/library/build.gradle.kts

@@ -11,3 +11,10 @@ dependencies {
 
   latestDepTestLibrary("org.apache.httpcomponents:httpclient:4.+") // see apache-httpclient-5.0 module
 }
+
+tasks {
+  test {
+    systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+    systemProperty("collectSpans", true)
+  }
+}

instrumentation/apache-httpclient/apache-httpclient-4.3/metadata.yaml

@@ -0,0 +1 @@
+description: This instrumentation provides a library integration that enables CLIENT spans and metrics for the Apache HttpClient.

instrumentation/spark-2.3/metadata.yaml

@@ -0,0 +1,3 @@
+description: > 
+  This instrumentation does not emit telemetry on its own. Instead, it extracts the HTTP route and
+  attaches it to SERVER spans and HTTP server metrics.

testing-common/src/main/java/io/opentelemetry/instrumentation/testing/LibraryTestRunner.java

@@ -20,6 +20,7 @@
 import io.opentelemetry.context.propagation.TextMapPropagator;
 import io.opentelemetry.contrib.baggage.processor.BaggageSpanProcessor;
 import io.opentelemetry.exporter.logging.LoggingSpanExporter;
+import io.opentelemetry.instrumentation.testing.internal.MetaDataCollector;
 import io.opentelemetry.sdk.OpenTelemetrySdk;
 import io.opentelemetry.sdk.common.CompletableResultCode;
 import io.opentelemetry.sdk.logs.SdkLoggerProvider;
@@ -39,6 +40,9 @@
 import io.opentelemetry.sdk.trace.SpanProcessor;
 import io.opentelemetry.sdk.trace.data.SpanData;
 import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
+import java.io.IOException;
+import java.net.URL;
+import java.nio.file.Paths;
 import java.time.Duration;
 import java.util.List;
 import java.util.concurrent.TimeUnit;
@@ -116,7 +120,19 @@ public void beforeTestClass() {
   }
 
   @Override
-  public void afterTestClass() {}
+  public void afterTestClass() throws IOException {
+    // Generates files in a `.telemetry` directory within the instrumentation module with all
+    // captured emitted metadata to be used by the instrumentation-docs Doc generator.
+    if (Boolean.getBoolean("collectMetadata")) {
+      URL resource = this.getClass().getClassLoader().getResource("");
+      if (resource == null) {
+        return;
+      }
+      String path = Paths.get(resource.getPath()).toString();
+
+      MetaDataCollector.writeTelemetryToFiles(path, metrics, tracesByScope);
+    }
+  }
 
   @Override
   public void clearAllExportedData() {