Merge branch 'master' of github.com:avaje/avaje-metrics

Author: rbygrave

.github/workflows/build.yml

@@ -17,14 +17,14 @@ jobs:
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Java
       uses: actions/setup-java@v2
       with:
         java-version: ${{ matrix.java_version }}
         distribution: 'zulu'
     - name: Maven cache
-      uses: actions/cache@v2
+      uses: actions/cache@v4
       env:
         cache-name: maven-cache
       with:

metrics-ebean/pom.xml

@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
   <parent>
     <artifactId>avaje-metrics-parent</artifactId>
     <groupId>io.avaje</groupId>
-    <version>9.4</version>
+    <version>9.5</version>
   </parent>
-  <modelVersion>4.0.0</modelVersion>
 
   <artifactId>avaje-metrics-ebean</artifactId>
 
@@ -24,14 +24,14 @@
     <dependency>
       <groupId>io.avaje</groupId>
       <artifactId>avaje-metrics</artifactId>
-      <version>9.4</version>
+      <version>9.5</version>
       <scope>provided</scope>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>13.11.0</version>
+      <version>14.10.0</version>
       <scope>provided</scope>
     </dependency>
 

metrics-graphite/pom.xml

@@ -4,11 +4,11 @@
   <parent>
     <artifactId>avaje-metrics-parent</artifactId>
     <groupId>io.avaje</groupId>
-    <version>9.4</version>
+    <version>9.5</version>
   </parent>
 
   <artifactId>avaje-metrics-graphite</artifactId>
-  <version>9.4</version>
+  <version>9.5</version>
 
   <properties>
     <surefire.useModulePath>false</surefire.useModulePath>
@@ -25,13 +25,13 @@
     <dependency>
       <groupId>io.avaje</groupId>
       <artifactId>avaje-metrics</artifactId>
-      <version>9.4</version>
+      <version>9.5</version>
     </dependency>
 
     <dependency>
       <groupId>io.ebean</groupId>
       <artifactId>ebean-api</artifactId>
-      <version>13.19.0</version>
+      <version>14.10.0</version>
       <optional>true</optional>
     </dependency>
 

metrics/pom.xml

@@ -3,7 +3,7 @@
   <parent>
     <groupId>io.avaje</groupId>
     <artifactId>avaje-metrics-parent</artifactId>
-    <version>9.4</version>
+    <version>9.5</version>
   </parent>
 
   <artifactId>avaje-metrics</artifactId>
@@ -20,6 +20,12 @@
       <version>1.0</version>
     </dependency>
 
+    <dependency>
+      <groupId>org.jspecify</groupId>
+      <artifactId>jspecify</artifactId>
+      <version>1.0.0</version>
+    </dependency>
+
     <dependency>
       <groupId>io.avaje</groupId>
       <artifactId>junit</artifactId>
@@ -30,14 +36,14 @@
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-core</artifactId>
-      <version>2.17.0</version>
+      <version>2.18.3</version>
       <scope>test</scope>
     </dependency>
 
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-databind</artifactId>
-      <version>2.17.0</version>
+      <version>2.18.3</version>
       <scope>test</scope>
     </dependency>
 

metrics/src/main/java/io/avaje/metrics/DScheduledTask.java

@@ -65,6 +65,9 @@ public void start() {
 
   @Override
   public boolean cancel(boolean mayInterruptIfRunning) {
+    if (backgroundTask == null) {
+      return false;
+    }
     return this.backgroundTask.cancel(mayInterruptIfRunning);
   }
 

metrics/src/main/java/io/avaje/metrics/JvmMetrics.java

@@ -41,31 +41,91 @@ public interface JvmMetrics {
 
   /**
    * Register a metric for OS load.
+   *
+   * <h4>Base metrics</h4>
+   * <ul>
+   *   <li>jvm.os.loadAverage</li>
+   * </ul>
    */
   JvmMetrics registerJvmOsLoadMetric();
 
   /**
    * Register metrics for GC activity.
+   *
+   * <h4>Base metrics</h4>
+   * <ul>
+   *   <li>jvm.gc.time</li>
+   * </ul>
+   *
+   * <h4>Extra metrics with {@link #withDetails()} enabled</h4>
+   * <p>
+   *   count and time for each Garbage Collector being used.
+   * </p>
    */
   JvmMetrics registerJvmGCMetrics();
 
   /**
    * Register metrics for the total number of threads allocated.
+   *
+   * <h4>Base metrics</h4>
+   * <ul>
+   *   <li>jvm.threads.current</li>
+   * </ul>
+   *
+   * <h4>Extra metrics with {@link #withDetails()} enabled</h4>
+   * <ul>
+   *   <li>jvm.thread.daemon</li>
+   *   <li>jvm.threads.peak</li>
+   * </ul>
    */
   JvmMetrics registerJvmThreadMetrics();
 
   /**
    * Register metrics for heap and non-heap memory.
+   *
+   * <h4>Base metrics</h4>
+   * <ul>
+   *   <li>jvm.memory.heap.used</li>
+   *   <li>jvm.memory.heap.committed</li>
+   *   <li>jvm.memory.heap.max</li>
+   *   <li>jvm.memory.nonheap.used</li>
+   *   <li>jvm.memory.nonheap.committed</li>
+   *   <li>jvm.memory.nonheap.max</li>
+   * </ul>
    */
   JvmMetrics registerJvmMemoryMetrics();
 
   /**
    * Register metrics for VMRSS process memory (if supported on the platform).
+   *
+   * <h4>Base metrics</h4>
+   * <ul>
+   *   <li>jvm.memory.process.vmrss</li>
+   *   <li>jvm.memory.process.vmhwm</li>
+   * </ul>
    */
   JvmMetrics registerProcessMemoryMetrics();
 
   /**
    * Register CGroup metrics for CPU usage time, throttle time, requests and limits.
+   *
+   * <h4>Base metrics</h4>
+   * <ul>
+   *   <li>jvm.cgroup.cpu.requests</li>
+   *   <li>jvm.cgroup.cpu.limit (if a limit is applied)</li>
+   *   <li>jvm.cgroup.cpu.usageMicros</li>
+   *   <li>jvm.cgroup.cpu.throttleMicros</li>
+   *   <li>jvm.cgroup.memory.usage</li>
+   *   <li>jvm.cgroup.memory.limit/li>
+   *   <li>jvm.cgroup.memory.pctUsage/li>
+   * </ul>
+   *
+   * <h4>Extra metrics with {@link #withDetails()} enabled</h4>
+   * <ul>
+   *   <li>jvm.cgroup.cpu.numPeriod</li>
+   *   <li>jvm.cgroup.cpu.numThrottle</li>
+   *   <li>jvm.cgroup.cpu.pctThrottle/li>
+   * </ul>
    */
   JvmMetrics registerCGroupMetrics();
 

metrics/src/main/java/io/avaje/metrics/ScheduledTask.java

@@ -25,6 +25,7 @@ static Builder builder() {
 
   /**
    * Cancel the scheduled task.
+   * @return true if the task was cancelled otherwise false
    */
   boolean cancel(boolean mayInterruptIfRunning);
 

metrics/src/main/java/io/avaje/metrics/Timer.java

@@ -1,5 +1,7 @@
 package io.avaje.metrics;
 
+import org.jspecify.annotations.Nullable;
+
 import java.util.function.Supplier;
 
 /**
@@ -122,7 +124,7 @@ public interface Timer extends Metric {
   /**
    * Return the bucket range or empty string if not a bucket.
    */
-  String bucketRange();
+  @Nullable String bucketRange();
 
   /**
    * Statistics collected by Timer.
@@ -132,7 +134,7 @@ interface Stats extends Meter.Stats {
     /**
      * Return the bucket range for these statistics.
      */
-    default String bucketRange() {
+    default @Nullable String bucketRange() {
       return null;
     }
   }

metrics/src/main/java/io/avaje/metrics/core/BaseReportName.java

@@ -1,11 +1,12 @@
 package io.avaje.metrics.core;
 
 import io.avaje.metrics.Metric;
+import org.jspecify.annotations.Nullable;
 
 abstract class BaseReportName {
 
   final String name;
-  String reportName;
+  @Nullable String reportName;
 
   BaseReportName(String name) {
     this.name = name;

metrics/src/main/java/io/avaje/metrics/core/DBucketTimer.java

@@ -1,6 +1,7 @@
 package io.avaje.metrics.core;
 
 import io.avaje.metrics.Timer;
+import org.jspecify.annotations.Nullable;
 
 import java.util.function.Supplier;
 
@@ -27,7 +28,7 @@ public String toString() {
   }
 
   @Override
-  public String bucketRange() {
+  public @Nullable String bucketRange() {
     return null;
   }