open-telemetry · trask · Feb 20, 2023 · Feb 20, 2023 · Feb 20, 2023 · Feb 20, 2023
@@ -24,7 +24,7 @@ components:
     - trask
   jfr-events:
     - sfriberg
-  jfr-streaming:
+  jfr-metrics:
     - breedx-splk
     - jack-berg
     - kittylyst

@@ -29,7 +29,7 @@ component_names["aws-xray/"]="AWS X-Ray SDK support"
 component_names["aws-xray-propagator/"]="AWS X-Ray propagator"
 component_names["consistent-sampling/"]="Consistent sampling"
 component_names["jfr-events/"]="JFR events"
-component_names["jfr-streaming/"]="JFR streaming"
+component_names["jfr-metrics/"]="JFR metrics"
 component_names["jmx-metrics/"]="JMX metrics"
 component_names["maven-extension/"]="Maven extension"
 component_names["micrometer-meter-provider/"]="Micrometer MeterProvider"

@@ -4,7 +4,7 @@
 
 ## Version 1.22.0 (2023-01-17)
 
-### JFR streaming
+### JFR metrics
 
 - Add buffer handlers and implement buffer metrics
   ([#650](https://github.com/open-telemetry/opentelemetry-java-contrib/pull/650))
@@ -19,9 +19,9 @@ This module can be used to bridge OpenTelemetry metrics into the `prometheus-sim
 
 ## Version 1.21.0 (2022-12-15)
 
-### JFR streaming
+### JFR metrics
 
-- Update handlers in jfr-streaming to match spec
+- Update handlers in jfr-metrics to match spec
   ([#616](https://github.com/open-telemetry/opentelemetry-java-contrib/pull/616))
 
 ## Version 1.20.1 (2022-11-22)
@@ -38,7 +38,7 @@ This module can be used to bridge OpenTelemetry metrics into the `prometheus-sim
 - Move io.opentelemetry:opentelemetry-extension-aws to contrib
   ([#547](https://github.com/open-telemetry/opentelemetry-java-contrib/pull/547))
 
-### JFR streaming
+### JFR metrics
 
 - Thread count and classes loaded handlers
   ([#571](https://github.com/open-telemetry/opentelemetry-java-contrib/pull/571))
@@ -162,7 +162,7 @@ All components updated to target OpenTelemetry SDK 1.12.0.
 
 All components updated to target OpenTelemetry SDK 1.11.0.
 
-### JFR streaming
+### JFR metrics
 
 - Split up GC Handlers, add support for Parallel
   ([#201](https://github.com/open-telemetry/opentelemetry-java-contrib/pull/201))
@@ -248,9 +248,9 @@ All components updated to target OpenTelemetry SDK 1.9.1.
 - X-Ray Sampler: Match rule's HTTP path against http.url attribute if t
   ([#141](https://github.com/open-telemetry/opentelemetry-java-contrib/pull/141))
 
-### JFR streaming
+### JFR metrics
 
-- Tidy up jfr-streaming
+- Tidy up jfr-metrics
   ([#127](https://github.com/open-telemetry/opentelemetry-java-contrib/pull/127))
 - Fix units for some metrics
   ([#140](https://github.com/open-telemetry/opentelemetry-java-contrib/pull/140))
@@ -267,7 +267,7 @@ All components updated to target OpenTelemetry SDK 1.7.0.
 
 Moved from SDK repo.
 
-### JFR streaming - New 🌟
+### JFR metrics - New 🌟
 
 Listens for JFR events (using the Streaming API) and converts them to OpenTelemetry metrics.
 

@@ -1,10 +1,15 @@
 # OpenTelemetry Java Contrib
+
 [![Build](https://github.com/open-telemetry/opentelemetry-java-contrib/actions/workflows/build.yml/badge.svg)](https://github.com/open-telemetry/opentelemetry-java-contrib/actions/workflows/build.yml)
 
-This project is intended to provide helpful libraries and standalone OpenTelemetry-based utilities that don't fit
-the express scope of the [OpenTelemetry Java](https://github.com/open-telemetry/opentelemetry-java) or
-[Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) projects.  If you need an
-easier way to bring observability to remote JVM-based applications and workflows that isn't easily satisfied by an SDK
+This project is intended to provide helpful libraries and standalone OpenTelemetry-based utilities
+that don't fit
+the express scope of the [OpenTelemetry Java](https://github.com/open-telemetry/opentelemetry-java)
+or
+[Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation)
+projects. If you need an
+easier way to bring observability to remote JVM-based applications and workflows that isn't easily
+satisfied by an SDK
 feature or via instrumentation, this project is hopefully for you.
 
 ## Provided Libraries
@@ -13,7 +18,7 @@ feature or via instrumentation, this project is hopefully for you.
 * [AWS X-Ray SDK Support](./aws-xray/README.md)
 * [AWS X-Ray Propagator](./aws-xray-propagator/README.md)
 * [Consistent sampling](./consistent-sampling/README.md)
-* [JFR Streaming](./jfr-streaming/README.md)
+* [JFR Metrics](./jfr-metrics/README.md)
 * [JMX Metric Gatherer](./jmx-metrics/README.md)
 * [OpenTelemetry Maven Extension](./maven-extension/README.md)
 * [Runtime Attach](./runtime-attach/README.md)
@@ -37,16 +42,24 @@ $ ./gradlew clean
 
 ## Contributing
 
-The Java Contrib project was initially formed to provide methods of easy remote JMX metric gathering and reporting,
-which is actively in development.  If you have an idea for a similar use case in the metrics, traces, or logging
-domain we would be very interested in supporting it.  Please
-[open an issue](https://github.com/open-telemetry/opentelemetry-java-contrib/issues/new/choose) to share your idea or
-suggestion.  PRs are always welcome and greatly appreciated, but for larger functional changes a pre-coding introduction
-can be helpful to ensure this is the correct place and that active or conflicting efforts don't exist.
+The Java Contrib project was initially formed to provide methods of easy remote JMX metric gathering
+and reporting,
+which is actively in development. If you have an idea for a similar use case in the metrics, traces,
+or logging
+domain we would be very interested in supporting it. Please
+[open an issue](https://github.com/open-telemetry/opentelemetry-java-contrib/issues/new/choose) to
+share your idea or
+suggestion. PRs are always welcome and greatly appreciated, but for larger functional changes a
+pre-coding introduction
+can be helpful to ensure this is the correct place and that active or conflicting efforts don't
+exist.
 
 Triagers ([@open-telemetry/java-contrib-triagers](https://github.com/orgs/open-telemetry/teams/java-contrib-triagers)):
 
-- All [component owners](https://github.com/open-telemetry/opentelemetry-java-contrib/blob/main/.github/component_owners.yml) are given Triager permissions to this repository.
+-
+
+All [component owners](https://github.com/open-telemetry/opentelemetry-java-contrib/blob/main/.github/component_owners.yml)
+are given Triager permissions to this repository.
 
 Approvers ([@open-telemetry/java-contrib-approvers](https://github.com/orgs/open-telemetry/teams/java-contrib-approvers)):
 
@@ -64,7 +77,8 @@ Emeritus maintainers:
 
 - [Ryan Fitzpatrick](https://github.com/rmfitzpatrick), Splunk
 
-Learn more about roles in the [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md).
+Learn more about roles in
+the [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md).
 
 Thanks to all the people who already contributed!
 

@@ -0,0 +1,62 @@
+# JFR Metrics
+
+* Java 17 only.
+
+* Build it with `./gradlew :jfr-metrics:build`
+
+The main entry point is the `JfrTelemetry` class in the
+package `io.opentelemetry.contrib.jfr.metrics`:
+
+```java
+// Initialize JfrTelemetry
+JfrTelemetry jfrTelemetry=JfrTelemetry.create(openTelemetry);
+
+// Close JfrTelemetry to stop listening for JFR events
+    jfrTelemetry.close();
+```
+
+`JfrTelemetry` works by subscribing to certain JFR events, and using relevant bits of information
+from the events to produce telemetry data like metrics. The code is divided into "handlers", which
+listen for specific events and produce relevant telemetry. The handlers are organized into
+features (i.e `JfrFeature`), which represent a category of telemetry and can be toggled on and
+off. `JfrTelemetry` evaluates which features are enabled, and only listens for the events required
+by the handlers associated with those features.
+
+Enable or disable a feature as follows:
+
+```
+JfrTelemetry jfrTelemetry = JfrTelemetry.builder(openTelemetry)
+  .enableFeature(JfrFeature.BUFFER_METRICS)
+  .disableFeature(JfrFeature.LOCK_METRICS)
+  .build();
+```
+
+The following table describes the set of `JfrFeatures` available, whether each is enabled by
+default, and the telemetry each produces:
+
+<!-- DO NOT MANUALLY EDIT. Regenerate table following changes to instrumentation using ./gradlew generateDocs -->
+<!-- generateDocsStart -->
+
+| JfrFeature                | Default Enabled | Metrics                                                                                                                                                                                             |
+|---------------------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| BUFFER_METRICS            | false           | `process.runtime.jvm.buffer.count`, `process.runtime.jvm.buffer.limit`, `process.runtime.jvm.buffer.usage`                                                                                          |
+| CLASS_LOAD_METRICS        | false           | `process.runtime.jvm.classes.current_loaded`, `process.runtime.jvm.classes.loaded`, `process.runtime.jvm.classes.unloaded`                                                                          |
+| CONTEXT_SWITCH_METRICS    | true            | `process.runtime.jvm.cpu.context_switch`                                                                                                                                                            |
+| CPU_COUNT_METRICS         | true            | `process.runtime.jvm.cpu.limit`                                                                                                                                                                     |
+| CPU_UTILIZATION_METRICS   | false           | `process.runtime.jvm.cpu.utilization`, `process.runtime.jvm.system.cpu.utilization`                                                                                                                 |
+| GC_DURATION_METRICS       | false           | `process.runtime.jvm.gc.duration`                                                                                                                                                                   |
+| LOCK_METRICS              | true            | `process.runtime.jvm.cpu.longlock`                                                                                                                                                                  |
+| MEMORY_ALLOCATION_METRICS | true            | `process.runtime.jvm.memory.allocation`                                                                                                                                                             |
+| MEMORY_POOL_METRICS       | false           | `process.runtime.jvm.memory.committed`, `process.runtime.jvm.memory.init`, `process.runtime.jvm.memory.limit`, `process.runtime.jvm.memory.usage`, `process.runtime.jvm.memory.usage_after_last_gc` |
+| NETWORK_IO_METRICS        | true            | `process.runtime.jvm.network.io`, `process.runtime.jvm.network.time`                                                                                                                                |
+| THREAD_METRICS            | false           | `process.runtime.jvm.threads.count`                                                                                                                                                                 |
+
+<!-- generateDocsEnd -->
+
+## Component owners
+
+- [Ben Evans](https://github.com/kittylyst), Red Hat
+- [Jack Berg](https://github.com/jack-berg), New Relic
+- [Jason Plumb](https://github.com/breedx-splk), Splunk
+
+Learn more about component owners in [component_owners.yml](../.github/component_owners.yml).
@@ -5,8 +5,8 @@ plugins {
   id("otel.publish-conventions")
 }
 
-description = "OpenTelemetry JFR Streaming"
-otelJava.moduleName.set("io.opentelemetry.contrib.jfr.streaming")
+description = "OpenTelemetry JFR Metrics"
+otelJava.moduleName.set("io.opentelemetry.contrib.jfr.metrics")
 
 // Disable publishing test fixtures
 val javaComponent = components["java"] as AdhocComponentWithVariants
@@ -47,7 +47,7 @@ tasks.create("generateDocs", JavaExec::class) {
   group = "build"
   description = "Generate table for README.md"
   classpath = sourceSets.test.get().runtimeClasspath
-  mainClass.set("io.opentelemetry.contrib.jfr.streaming.GenerateDocs")
+  mainClass.set("io.opentelemetry.contrib.jfr.metrics.GenerateDocs")
   systemProperties.set("jfr.readme.path", project.projectDir.toString() + "/README.md")
 }
 tasks.getByName("build").dependsOn("generateDocs")

@@ -3,22 +3,22 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.contrib.jfr.streaming;
+package io.opentelemetry.contrib.jfr.metrics;
 
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.ATTR_ACTION;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.ATTR_G1_EDEN_SPACE;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.ATTR_G1_SURVIVOR_SPACE;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.ATTR_GC;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.BYTES;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.END_OF_MAJOR_GC;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.END_OF_MINOR_GC;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.METRIC_DESCRIPTION_COMMITTED;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.METRIC_DESCRIPTION_GC_DURATION;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.METRIC_DESCRIPTION_MEMORY;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.METRIC_DESCRIPTION_MEMORY_AFTER;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.METRIC_NAME_MEMORY;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.METRIC_NAME_MEMORY_AFTER;
-import static io.opentelemetry.contrib.jfr.streaming.internal.Constants.MILLISECONDS;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.ATTR_ACTION;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.ATTR_G1_EDEN_SPACE;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.ATTR_G1_SURVIVOR_SPACE;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.ATTR_GC;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.BYTES;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.END_OF_MAJOR_GC;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.END_OF_MINOR_GC;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.METRIC_DESCRIPTION_COMMITTED;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.METRIC_DESCRIPTION_GC_DURATION;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.METRIC_DESCRIPTION_MEMORY;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.METRIC_DESCRIPTION_MEMORY_AFTER;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.METRIC_NAME_MEMORY;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.METRIC_NAME_MEMORY_AFTER;
+import static io.opentelemetry.contrib.jfr.metrics.internal.Constants.MILLISECONDS;
 import static org.assertj.core.api.Assertions.assertThat;
 
 import io.opentelemetry.api.common.Attributes;

@@ -3,30 +3,30 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.contrib.jfr.streaming;
+package io.opentelemetry.contrib.jfr.metrics;
 
 import io.opentelemetry.api.OpenTelemetry;
 import io.opentelemetry.api.metrics.Meter;
-import io.opentelemetry.contrib.jfr.streaming.internal.GarbageCollection.G1GarbageCollectionHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.GarbageCollection.OldGarbageCollectionHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.GarbageCollection.YoungGarbageCollectionHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.RecordedEventHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.ThreadGrouper;
-import io.opentelemetry.contrib.jfr.streaming.internal.buffer.DirectBufferStatisticsHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.classes.ClassesLoadedHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.container.ContainerConfigurationHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.cpu.ContextSwitchRateHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.cpu.LongLockHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.cpu.OverallCPULoadHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.memory.CodeCacheConfigurationHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.memory.G1HeapSummaryHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.memory.MetaspaceSummaryHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.memory.ObjectAllocationInNewTLABHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.memory.ObjectAllocationOutsideTLABHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.memory.ParallelHeapSummaryHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.network.NetworkReadHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.network.NetworkWriteHandler;
-import io.opentelemetry.contrib.jfr.streaming.internal.threads.ThreadCountHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.GarbageCollection.G1GarbageCollectionHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.GarbageCollection.OldGarbageCollectionHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.GarbageCollection.YoungGarbageCollectionHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.RecordedEventHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.ThreadGrouper;
+import io.opentelemetry.contrib.jfr.metrics.internal.buffer.DirectBufferStatisticsHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.classes.ClassesLoadedHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.container.ContainerConfigurationHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.cpu.ContextSwitchRateHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.cpu.LongLockHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.cpu.OverallCPULoadHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.memory.CodeCacheConfigurationHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.memory.G1HeapSummaryHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.memory.MetaspaceSummaryHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.memory.ObjectAllocationInNewTLABHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.memory.ObjectAllocationOutsideTLABHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.memory.ParallelHeapSummaryHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.network.NetworkReadHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.network.NetworkWriteHandler;
+import io.opentelemetry.contrib.jfr.metrics.internal.threads.ThreadCountHandler;
 import java.io.IOException;
 import java.lang.management.ManagementFactory;
 import java.util.ArrayList;
@@ -36,7 +36,7 @@
 import java.util.function.Predicate;
 
 final class HandlerRegistry {
-  private static final String SCOPE_NAME = "io.opentelemetry.contrib.jfr.streaming";
+  private static final String SCOPE_NAME = "io.opentelemetry.contrib.jfr.metrics";
   private static final String SCOPE_VERSION = readVersion();
 
   private HandlerRegistry() {}

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.contrib.jfr.streaming;
+package io.opentelemetry.contrib.jfr.metrics;
 
 /**
  * Enumeration of JFR features, which can be toggled on or off via {@link JfrTelemetryBuilder}.