Metadata for runtime telemetry

.github/scripts/instrumentations.sh

@@ -245,6 +245,7 @@ readonly INSTRUMENTATIONS=(
   "rocketmq:rocketmq-client-4.8:javaagent:testExperimental"
   "rocketmq:rocketmq-client-5.0:javaagent:test"
   "rocketmq:rocketmq-client-5.0:javaagent:testExperimental"
+  "runtime-telemetry:library:check"
   "servlet:servlet-2.2:javaagent:test"
   "servlet:servlet-3.0:javaagent-testing:test"
   "servlet:servlet-5.0:jetty12-testing:test"

docs/instrumentation-list.yaml

@@ -12524,13 +12524,359 @@ libraries:
         - name: messaging.system
           type: STRING
   runtime:
+  - name: runtime-telemetry
+    description: |
+      This instrumentation enables JVM runtime metrics using JMX (Java 8+) and JFR (Java 17+) to monitor CPU, memory, garbage collection, threads, classes, buffer pools, and file descriptors.
+    semantic_conventions:
+    - JVM_RUNTIME_METRICS
+    library_link: https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/runtime-telemetry
+    source_path: instrumentation/runtime-telemetry
+    scope:
+      name: io.opentelemetry.runtime-telemetry
+    has_standalone_library: true
+    configurations:
+    - name: otel.instrumentation.runtime-telemetry.emit-experimental-metrics
+      description: Enables the capture of experimental JVM runtime metrics.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.runtime-telemetry.experimental.prefer-jfr
+      description: |
+        Prefers JFR over JMX for metrics where both collection methods are available (Java 17+).
+      type: boolean
+      default: false
+    - name: otel.instrumentation.runtime-telemetry.experimental.package-emitter.enabled
+      description: Enables creating events for JAR libraries used by the application.
+      type: boolean
+      default: false
+    - name: otel.instrumentation.runtime-telemetry.experimental.package-emitter.jars-per-second
+      description: The number of JAR files processed per second by the package emitter.
+      type: int
+      default: 10
+    telemetry:
+    - when: Java17
+      metrics:
+      - name: jvm.buffer.count
+        description: Number of buffers in the pool.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: '{buffer}'
+        attributes:
+        - name: jvm.buffer.pool.name
+          type: STRING
+      - name: jvm.buffer.memory.limit
+        description: Measure of total memory capacity of buffers.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.buffer.pool.name
+          type: STRING
+      - name: jvm.buffer.memory.used
+        description: Measure of memory used by buffers.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.buffer.pool.name
+          type: STRING
+      - name: jvm.class.count
+        description: Number of classes currently loaded.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: '{class}'
+        attributes: []
+      - name: jvm.class.loaded
+        description: Number of classes loaded since JVM start.
+        instrument: counter
+        data_type: LONG_SUM
+        unit: '{class}'
+        attributes: []
+      - name: jvm.class.unloaded
+        description: Number of classes unloaded since JVM start.
+        instrument: counter
+        data_type: LONG_SUM
+        unit: '{class}'
+        attributes: []
+      - name: jvm.cpu.count
+        description: Number of processors available to the Java virtual machine.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: '{cpu}'
+        attributes: []
+      - name: jvm.cpu.longlock
+        description: Long lock times
+        instrument: histogram
+        data_type: HISTOGRAM
+        unit: s
+        attributes: []
+      - name: jvm.cpu.recent_utilization
+        description: Recent CPU utilization for the process as reported by the JVM.
+        instrument: gauge
+        data_type: DOUBLE_GAUGE
+        unit: '1'
+        attributes: []
+      - name: jvm.cpu.time
+        description: CPU time used by the process as reported by the JVM.
+        instrument: counter
+        data_type: DOUBLE_SUM
+        unit: s
+        attributes: []
+      - name: jvm.gc.duration
+        description: Duration of JVM garbage collection actions.
+        instrument: histogram
+        data_type: HISTOGRAM
+        unit: s
+        attributes:
+        - name: jvm.gc.action
+          type: STRING
+        - name: jvm.gc.name
+          type: STRING
+      - name: jvm.memory.committed
+        description: Measure of memory committed.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.memory.pool.name
+          type: STRING
+        - name: jvm.memory.type
+          type: STRING
+      - name: jvm.memory.init
+        description: Measure of initial memory requested.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.memory.pool.name
+          type: STRING
+        - name: jvm.memory.type
+          type: STRING
+      - name: jvm.memory.limit
+        description: Measure of max obtainable memory.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.memory.pool.name
+          type: STRING
+        - name: jvm.memory.type
+          type: STRING
+      - name: jvm.memory.used
+        description: Measure of memory used.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.memory.pool.name
+          type: STRING
+        - name: jvm.memory.type
+          type: STRING
+      - name: jvm.memory.used_after_last_gc
+        description: Measure of memory used, as measured after the most recent garbage
+          collection event on this pool.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.memory.pool.name
+          type: STRING
+        - name: jvm.memory.type
+          type: STRING
+      - name: jvm.system.cpu.utilization
+        description: Recent CPU utilization for the whole system as reported by the
+          JVM.
+        instrument: gauge
+        data_type: DOUBLE_GAUGE
+        unit: '1'
+        attributes: []
+      - name: jvm.thread.count
+        description: Number of executing platform threads.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: '{thread}'
+        attributes:
+        - name: jvm.thread.daemon
+          type: BOOLEAN
+        - name: jvm.thread.state
+          type: STRING
+    - when: default
+      metrics:
+      - name: jvm.buffer.count
+        description: Number of buffers in the pool.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: '{buffer}'
+        attributes:
+        - name: jvm.buffer.pool.name
+          type: STRING
+      - name: jvm.buffer.memory.limit
+        description: Measure of total memory capacity of buffers.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.buffer.pool.name
+          type: STRING
+      - name: jvm.buffer.memory.used
+        description: Measure of memory used by buffers.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.buffer.pool.name
+          type: STRING
+      - name: jvm.class.count
+        description: Number of classes currently loaded.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: '{class}'
+        attributes: []
+      - name: jvm.class.loaded
+        description: Number of classes loaded since JVM start.
+        instrument: counter
+        data_type: LONG_SUM
+        unit: '{class}'
+        attributes: []
+      - name: jvm.class.unloaded
+        description: Number of classes unloaded since JVM start.
+        instrument: counter
+        data_type: LONG_SUM
+        unit: '{class}'
+        attributes: []
+      - name: jvm.cpu.count
+        description: Number of processors available to the Java virtual machine.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: '{cpu}'
+        attributes: []
+      - name: jvm.cpu.recent_utilization
+        description: Recent CPU utilization for the process as reported by the JVM.
+        instrument: gauge
+        data_type: DOUBLE_GAUGE
+        unit: '1'
+        attributes: []
+      - name: jvm.cpu.time
+        description: CPU time used by the process as reported by the JVM.
+        instrument: counter
+        data_type: DOUBLE_SUM
+        unit: s
+        attributes: []
+      - name: jvm.file_descriptor.count
+        description: Number of open file descriptors as reported by the JVM.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: '{file_descriptor}'
+        attributes: []
+      - name: jvm.file_descriptor.limit
+        description: Measure of max open file descriptors as reported by the JVM.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: '{file_descriptor}'
+        attributes: []
+      - name: jvm.gc.duration
+        description: Duration of JVM garbage collection actions.
+        instrument: histogram
+        data_type: HISTOGRAM
+        unit: s
+        attributes:
+        - name: jvm.gc.action
+          type: STRING
+        - name: jvm.gc.cause
+          type: STRING
+        - name: jvm.gc.name
+          type: STRING
+      - name: jvm.memory.committed
+        description: Measure of memory committed.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.memory.pool.name
+          type: STRING
+        - name: jvm.memory.type
+          type: STRING
+      - name: jvm.memory.init
+        description: Measure of initial memory requested.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.memory.pool.name
+          type: STRING
+        - name: jvm.memory.type
+          type: STRING
+      - name: jvm.memory.limit
+        description: Measure of max obtainable memory.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.memory.pool.name
+          type: STRING
+        - name: jvm.memory.type
+          type: STRING
+      - name: jvm.memory.used
+        description: Measure of memory used.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.memory.pool.name
+          type: STRING
+        - name: jvm.memory.type
+          type: STRING
+      - name: jvm.memory.used_after_last_gc
+        description: Measure of memory used, as measured after the most recent garbage
+          collection event on this pool.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: By
+        attributes:
+        - name: jvm.memory.pool.name
+          type: STRING
+        - name: jvm.memory.type
+          type: STRING
+      - name: jvm.system.cpu.load_1m
+        description: Average CPU load of the whole system for the last minute as reported
+          by the JVM.
+        instrument: gauge
+        data_type: DOUBLE_GAUGE
+        unit: '{run_queue_item}'
+        attributes: []
+      - name: jvm.system.cpu.utilization
+        description: Recent CPU utilization for the whole system as reported by the
+          JVM.
+        instrument: gauge
+        data_type: DOUBLE_GAUGE
+        unit: '1'
+        attributes: []
+      - name: jvm.thread.count
+        description: Number of executing platform threads.
+        instrument: updowncounter
+        data_type: LONG_SUM
+        unit: '{thread}'
+        attributes:
+        - name: jvm.thread.daemon
+          type: BOOLEAN
+        - name: jvm.thread.state
+          type: STRING
   - name: runtime-telemetry-java17
+    description: |
+      DEPRECATED: This instrumentation enables JVM runtime metrics using JFR (Java 17+). Use the unified runtime-telemetry module instead, which provides both JMX and JFR support.
+    semantic_conventions:
+    - JVM_RUNTIME_METRICS
+    library_link: https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/runtime-telemetry/runtime-telemetry-java17
     source_path: instrumentation/runtime-telemetry/runtime-telemetry-java17
     minimum_java_version: 17
     scope:
       name: io.opentelemetry.runtime-telemetry-java17
     has_standalone_library: true
   - name: runtime-telemetry-java8
+    description: |
+      DEPRECATED: This instrumentation enables JVM runtime metrics using JMX (Java 8+). Use the unified runtime-telemetry module instead, which provides both JMX and JFR support.
+    semantic_conventions:
+    - JVM_RUNTIME_METRICS
+    library_link: https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/runtime-telemetry/runtime-telemetry-java8
     source_path: instrumentation/runtime-telemetry/runtime-telemetry-java8
     scope:
       name: io.opentelemetry.runtime-telemetry-java8

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

@@ -55,7 +55,9 @@ class TelemetryParser {
             entry("io.opentelemetry.couchbase-3.2", singleton("com.couchbase.client.jvm")),
             entry("io.opentelemetry.couchbase-3.4", singleton("com.couchbase.client.jvm")),
             // servlet-5.0 tests use jetty-12.0 instrumentation
-            entry("io.opentelemetry.servlet-5.0", singleton("io.opentelemetry.jetty-12.0")));
+            entry("io.opentelemetry.servlet-5.0", singleton("io.opentelemetry.jetty-12.0")),
+            // runtime-telemetry library tests use a meter named "test"
+            entry("io.opentelemetry.runtime-telemetry", singleton("test")));
   }
 
   /**