finish metric emitting instrumentations

Author: jaydeluca

docs/instrumentation-list.yaml

@@ -556,7 +556,7 @@ libraries:
   dropwizard:
   - name: dropwizard-metrics-4.0
     description: |
-      The dropwizard-metrics instrumentation for the dropwizard/codahale metrics library produces OpenTelemetry compliant versions of the metrics generated by the MetricRegistry.
+      The dropwizard-metrics instrumentation for the dropwizard/codahale metrics library produces OpenTelemetry compliant versions of the metrics generated by the Dropwizard MetricRegistry.
       The Dropwizard metrics API does not have a concept of metric labels/tags/attributes, thus the data produced by this integration might be of very low quality, depending on how the API is used in the instrumented application.
     disabled_by_default: true
     source_path: instrumentation/dropwizard/dropwizard-metrics-4.0
@@ -1519,6 +1519,8 @@ libraries:
       - org.opensearch.client:opensearch-rest-client:[1.0,3.0)
   oracle:
   - name: oracle-ucp-11.2
+    description: The Oracle Universal Connection Pool (UCP) instrumentation generates
+      connection pool metrics.
     source_path: instrumentation/oracle-ucp-11.2
     scope:
       name: io.opentelemetry.oracle-ucp-11.2
@@ -1528,8 +1530,37 @@ libraries:
       library:
       - com.oracle.database.jdbc:ucp:11.2.0.4
       - com.oracle.database.jdbc:ojdbc8:12.2.0.1
+    metrics:
+    - name: db.client.connections.usage
+      description: The number of connections that are currently in state described
+        by the state attribute.
+      type: LONG_SUM
+      unit: connections
+      attributes:
+      - name: pool.name
+        type: STRING
+      - name: state
+        type: STRING
+    - name: db.client.connections.pending_requests
+      description: The number of pending requests for an open connection, cumulative
+        for the entire pool.
+      type: LONG_SUM
+      unit: requests
+      attributes:
+      - name: pool.name
+        type: STRING
+    - name: db.client.connections.max
+      description: The maximum number of open connections allowed.
+      type: LONG_SUM
+      unit: connections
+      attributes:
+      - name: pool.name
+        type: STRING
   oshi:
   - name: oshi
+    description: When the OSHI library is detected on the classpath, this instrumentation
+      will use the system class loader to load classes from the oshi-core jar that
+      are then used to generate system metrics.
     source_path: instrumentation/oshi
     scope:
       name: io.opentelemetry.oshi
@@ -1538,6 +1569,85 @@ libraries:
       - com.github.oshi:oshi-core:[5.3.1,)
       library:
       - com.github.oshi:oshi-core:5.3.1
+    configurations:
+    - name: otel.instrumentation.oshi.experimental-metrics.enabled
+      description: Enable the OSHI process metrics.
+      type: boolean
+      default: false
+    metrics:
+    - name: system.memory.utilization
+      description: System memory utilization
+      type: DOUBLE_GAUGE
+      unit: '1'
+      attributes:
+      - name: state
+        type: STRING
+    - name: system.network.packets
+      description: System network packets
+      type: LONG_SUM
+      unit: packets
+      attributes:
+      - name: device
+        type: STRING
+      - name: direction
+        type: STRING
+    - name: system.disk.operations
+      description: System disk operations
+      type: LONG_SUM
+      unit: operations
+      attributes:
+      - name: device
+        type: STRING
+      - name: direction
+        type: STRING
+    - name: runtime.java.cpu_time
+      description: Runtime Java CPU time
+      type: LONG_GAUGE
+      unit: ms
+      attributes:
+      - name: type
+        type: STRING
+    - name: runtime.java.memory
+      description: Runtime Java memory
+      type: LONG_SUM
+      unit: By
+      attributes:
+      - name: type
+        type: STRING
+    - name: system.disk.io
+      description: System disk IO
+      type: LONG_SUM
+      unit: By
+      attributes:
+      - name: device
+        type: STRING
+      - name: direction
+        type: STRING
+    - name: system.network.io
+      description: System network IO
+      type: LONG_SUM
+      unit: By
+      attributes:
+      - name: device
+        type: STRING
+      - name: direction
+        type: STRING
+    - name: system.memory.usage
+      description: System memory usage
+      type: LONG_SUM
+      unit: By
+      attributes:
+      - name: state
+        type: STRING
+    - name: system.network.errors
+      description: System network errors
+      type: LONG_SUM
+      unit: errors
+      attributes:
+      - name: device
+        type: STRING
+      - name: direction
+        type: STRING
   payara:
   - name: payara
     source_path: instrumentation/payara
@@ -2246,6 +2356,8 @@ libraries:
       - io.vertx:vertx-core:[3.0.0,4.0.0)
   vibur:
   - name: vibur-dbcp-11.0
+    description: Instrumentation for the vibur-dbcp library, which provides connection
+      pool metrics.
     source_path: instrumentation/vibur-dbcp-11.0
     scope:
       name: io.opentelemetry.vibur-dbcp-11.0
@@ -2254,6 +2366,24 @@ libraries:
       - org.vibur:vibur-dbcp:[11.0,)
       library:
       - org.vibur:vibur-dbcp:11.0
+    metrics:
+    - name: db.client.connections.usage
+      description: The number of connections that are currently in state described
+        by the state attribute.
+      type: LONG_SUM
+      unit: connections
+      attributes:
+      - name: pool.name
+        type: STRING
+      - name: state
+        type: STRING
+    - name: db.client.connections.max
+      description: The maximum number of open connections allowed.
+      type: LONG_SUM
+      unit: connections
+      attributes:
+      - name: pool.name
+        type: STRING
   wicket:
   - name: wicket-8.0
     source_path: instrumentation/wicket-8.0

instrumentation-docs/collect.sh

@@ -5,14 +5,24 @@
 
 set -euo pipefail
 
+# Oracle UCP won't run on Apple Silicon, so we need to use colima to run as x86_64
+if [[ "$(uname -m)" == "arm64" || "$(uname -m)" == "aarch64" ]]; then
+  colima start --arch x86_64 --memory 4
+  export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock
+  export DOCKER_HOST="unix://${HOME}/.colima/docker.sock"
+fi
+
 readonly INSTRUMENTATIONS=(
   # <module path (colon-separated)> : <javaagent|library> : [ gradle-task-suffix ]
+  "apache-dbcp-2.0:javaagent:test"
   "apache-httpclient:apache-httpclient-5.0:javaagent:test"
   "alibaba-druid-1.0:javaagent:test"
   "c3p0-0.9:javaagent:test"
-  "tomcat:tomcat-jdbc:javaagent:test"
   "hikaricp-3.0:javaagent:test"
-  "apache-dbcp-2.0:javaagent:test"
+  "tomcat:tomcat-jdbc:javaagent:test"
+  "oracle-ucp-11.2:javaagent:test"
+  "oshi:javaagent:test"
+  "vibur-dbcp-11.0:javaagent:test"
 )
 
 readonly TELEMETRY_DIR_NAME=".telemetry"
@@ -52,8 +62,7 @@ parse_descriptor() {
     task_suffix="${parts[$((type_idx + 1))]}"
   fi
 
-  # Join everything *before* the type token with slashes to make
-  # instrumentation/<path>/...
+  # Join everything before the type token with slashes to make instrumentation/<path>/...
   local path_segments=("${parts[@]:0:type_idx}")
   local module_path="instrumentation/$(IFS=/; echo "${path_segments[*]}")"
 
@@ -71,7 +80,7 @@ delete_existing_telemetry() {
 }
 
 # Converts the three parsed parts into a Gradle task name.
-#   ex: instrumentation:foo:bar:javaagent:test
+# ex: instrumentation:foo:bar:javaagent:test
 build_gradle_task() {
   local module_path="$1"   # instrumentation/foo/bar
   local task_type="$2"     # javaagent | library
@@ -87,7 +96,7 @@ build_gradle_task() {
 
 # Cleans any stray .telemetry directories left in the repo.
 find_and_remove_all_telemetry() {
-  echo "🔍  Removing stray .telemetry directories..."
+  echo "Removing stray .telemetry directories..."
   find . -type d -name "$TELEMETRY_DIR_NAME" -exec rm -rf {} +
 }
 
@@ -98,7 +107,7 @@ for descriptor in "${INSTRUMENTATIONS[@]}"; do
   # Parse the descriptor into its components
   if ! read -r module_path task_type task_suffix \
         < <(parse_descriptor "$descriptor"); then
-    continue   # skip badly-formed descriptor
+    continue   # skip any badly formed descriptors
   fi
 
   # Make sure we’re starting fresh for this instrumentation
@@ -117,5 +126,7 @@ echo
   -PcollectMetadata=true \
   --rerun-tasks
 
+# uncomment the next line to remove all .telemetry directories
 #find_and_remove_all_telemetry
+
 echo "Telemetry file regeneration complete."

instrumentation/cassandra/cassandra-3.0/javaagent/build.gradle.kts

@@ -49,10 +49,6 @@ tasks {
     jvmArgs("-Dotel.semconv-stability.opt-in=database")
   }
 
-  test {
-    systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
-  }
-
   check {
     dependsOn(testStableSemconv)
   }

instrumentation/cassandra/cassandra-4.0/javaagent/build.gradle.kts

@@ -32,10 +32,6 @@ tasks {
     jvmArgs("-Dotel.semconv-stability.opt-in=database")
   }
 
-  test {
-    systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
-  }
-
   check {
     dependsOn(testStableSemconv)
   }

instrumentation/cassandra/cassandra-4.4/javaagent/build.gradle.kts

@@ -35,10 +35,6 @@ tasks {
     jvmArgs("-Dotel.semconv-stability.opt-in=database")
   }
 
-  test {
-    systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
-  }
-
   check {
     dependsOn(testStableSemconv)
   }

instrumentation/dropwizard/dropwizard-metrics-4.0/metadata.yaml

@@ -1,6 +1,6 @@
 description: >
   The dropwizard-metrics instrumentation for the dropwizard/codahale metrics library produces
-  OpenTelemetry compliant versions of the metrics generated by the MetricRegistry.
+  OpenTelemetry compliant versions of the metrics generated by the Dropwizard MetricRegistry.
 
   The Dropwizard metrics API does not have a concept of metric labels/tags/attributes, thus the data
   produced by this integration might be of very low quality, depending on how the API is used in the

instrumentation/oracle-ucp-11.2/javaagent/build.gradle.kts

@@ -29,6 +29,10 @@ tasks {
     jvmArgs("-Dotel.semconv-stability.opt-in=database")
   }
 
+  test {
+    systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+  }
+
   check {
     dependsOn(testStableSemconv)
   }

instrumentation/oracle-ucp-11.2/metadata.yaml

@@ -0,0 +1 @@
+description: The Oracle Universal Connection Pool (UCP) instrumentation generates connection pool metrics.

instrumentation/oshi/javaagent/build.gradle.kts

@@ -26,4 +26,8 @@ tasks {
   withType<Test>().configureEach {
     jvmArgs("-Dotel.instrumentation.oshi.experimental-metrics.enabled=true")
   }
+
+  test {
+    systemProperty("collectMetadata", findProperty("collectMetadata")?.toString() ?: "false")
+  }
 }

instrumentation/oshi/metadata.yaml

@@ -0,0 +1,6 @@
+description: When the OSHI library is detected on the classpath, this instrumentation will use the system class loader to load classes from the oshi-core jar that are then used to generate system metrics.
+configurations:
+  - name: otel.instrumentation.oshi.experimental-metrics.enabled
+    description: Enable the OSHI process metrics.
+    type: boolean
+    default: false