Add a basic API for retrieving spark statistics

8 files changed, 531 insertions, 0 deletions

diff --git a/spark-api/src/main/java/me/lucko/spark/api/Spark.java b/spark-api/src/main/java/me/lucko/spark/api/Spark.java
new file mode 100644
index 0000000..1f4ee64
--- /dev/null
+++ b/spark-api/src/main/java/me/lucko/spark/api/Spark.java
@@ -0,0 +1,79 @@
+/*
+ * This file is part of spark.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package me.lucko.spark.api;
+
+import me.lucko.spark.api.gc.GarbageCollector;
+import me.lucko.spark.api.statistic.misc.DoubleAverageInfo;
+import me.lucko.spark.api.statistic.types.DoubleStatistic;
+import me.lucko.spark.api.statistic.types.GenericStatistic;
+import me.lucko.spark.api.statistic.StatisticWindow;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
+
+import java.util.Map;
+
+/**
+ * The spark API.
+ */
+public interface Spark {
+
+    /**
+     * Gets the CPU usage statistic for the current process.
+     *
+     * @return the CPU process statistic
+     */
+    @NonNull DoubleStatistic<StatisticWindow.CpuUsage> cpuProcess();
+
+    /**
+     * Gets the CPU usage statistic for the overall system.
+     *
+     * @return the CPU system statistic
+     */
+    @NonNull DoubleStatistic<StatisticWindow.CpuUsage> cpuSystem();
+
+    /**
+     * Gets the ticks per second statistic.
+     *
+     * <p>Returns {@code null} if the statistic is not supported.</p>
+     *
+     * @return the ticks per second statistic
+     */
+    @Nullable DoubleStatistic<StatisticWindow.TicksPerSecond> tps();
+
+    /**
+     * Gets the milliseconds per tick statistic.
+     *
+     * <p>Returns {@code null} if the statistic is not supported.</p>
+     *
+     * @return the milliseconds per tick statistic
+     */
+    @Nullable GenericStatistic<DoubleAverageInfo, StatisticWindow.MillisPerTick> mspt();
+
+    /**
+     * Gets the garbage collector statistics.
+     *
+     * @return the garbage collector statistics
+     */
+    @NonNull @Unmodifiable Map<String, GarbageCollector> gc();
+
+}
diff --git a/spark-api/src/main/java/me/lucko/spark/api/SparkProvider.java b/spark-api/src/main/java/me/lucko/spark/api/SparkProvider.java
new file mode 100644
index 0000000..a93c27d
--- /dev/null
+++ b/spark-api/src/main/java/me/lucko/spark/api/SparkProvider.java
@@ -0,0 +1,53 @@
+/*
+ * This file is part of spark.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package me.lucko.spark.api;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Singleton provider for {@link Spark}.
+ */
+public final class SparkProvider {
+
+    private static Spark instance;
+
+    /**
+     * Gets the singleton spark API instance.
+     *
+     * @return the spark API instance
+     */
+    public static @NonNull Spark get() {
+        Spark instance = SparkProvider.instance;
+        if (instance == null) {
+            throw new IllegalStateException("spark has not loaded yet!");
+        }
+        return instance;
+    }
+
+    static void set(Spark impl) {
+        SparkProvider.instance = impl;
+    }
+
+    private SparkProvider() {
+        throw new AssertionError();
+    }
+
+}
diff --git a/spark-api/src/main/java/me/lucko/spark/api/gc/GarbageCollector.java b/spark-api/src/main/java/me/lucko/spark/api/gc/GarbageCollector.java
new file mode 100644
index 0000000..b2c8801
--- /dev/null
+++ b/spark-api/src/main/java/me/lucko/spark/api/gc/GarbageCollector.java
@@ -0,0 +1,73 @@
+/*
+ * This file is part of spark.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package me.lucko.spark.api.gc;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * Statistics about a garbage collector.
+ *
+ * <p>All time durations are measured in milliseconds.</p>
+ */
+public interface GarbageCollector {
+
+    /**
+     * Gets the name of the garbage collector.
+     *
+     * @return the name
+     */
+    @NonNull String name();
+
+    /**
+     * Gets the total number of collections performed.
+     *
+     * @return the total number of collections
+     */
+    long totalCollections();
+
+    /**
+     * Gets the total amount of time spent performing collections.
+     *
+     * <p>Measured in milliseconds.</p>
+     *
+     * @return the total time spent collecting
+     */
+    long totalTime();
+
+    /**
+     * Gets the average amount of time spent performing each collection.
+     *
+     * <p>Measured in milliseconds.</p>
+     *
+     * @return the average collection time
+     */
+    double avgTime();
+
+    /**
+     * Gets the average frequency at which collections are performed.
+     *
+     * <p>Measured in milliseconds.</p>
+     *
+     * @return the average frequency of collections
+     */
+    long avgFrequency();
+
+}
diff --git a/spark-api/src/main/java/me/lucko/spark/api/statistic/Statistic.java b/spark-api/src/main/java/me/lucko/spark/api/statistic/Statistic.java
new file mode 100644
index 0000000..26af8e1
--- /dev/null
+++ b/spark-api/src/main/java/me/lucko/spark/api/statistic/Statistic.java
@@ -0,0 +1,46 @@
+/*
+ * This file is part of spark.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package me.lucko.spark.api.statistic;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * A statistic for which a rolling average in various windows is recorded.
+ *
+ * @param <W> the window type
+ */
+public interface Statistic<W extends Enum<W> & StatisticWindow> {
+
+    /**
+     * Gets the statistic name.
+     *
+     * @return the statistic name
+     */
+    @NonNull String name();
+
+    /**
+     * Gets the windows used for rolling averages.
+     *
+     * @return the windows
+     */
+    @NonNull W[] getWindows();
+
+}
diff --git a/spark-api/src/main/java/me/lucko/spark/api/statistic/StatisticWindow.java b/spark-api/src/main/java/me/lucko/spark/api/statistic/StatisticWindow.java
new file mode 100644
index 0000000..cfae9dd
--- /dev/null
+++ b/spark-api/src/main/java/me/lucko/spark/api/statistic/StatisticWindow.java
@@ -0,0 +1,104 @@
+/*
+ * This file is part of spark.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package me.lucko.spark.api.statistic;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.jetbrains.annotations.NotNull;
+
+import java.time.Duration;
+
+/**
+ * A window in which a statistic is recorded as a rolling average.
+ */
+public interface StatisticWindow {
+
+    /**
+     * Gets the length of the window as a {@link Duration}.
+     *
+     * @return the length of the window
+     */
+    @NonNull Duration length();
+
+    /**
+     * The {@link StatisticWindow} used for CPU usage.
+     */
+    enum CpuUsage implements StatisticWindow {
+
+        SECONDS_10(Duration.ofSeconds(10)),
+        MINUTES_1(Duration.ofMinutes(1)),
+        MINUTES_15(Duration.ofMinutes(15));
+
+        private final Duration value;
+
+        CpuUsage(Duration value) {
+            this.value = value;
+        }
+
+        @Override
+        public @NotNull Duration length() {
+            return this.value;
+        }
+    }
+
+    /**
+     * The {@link StatisticWindow} used for TPS.
+     */
+    enum TicksPerSecond implements StatisticWindow {
+
+        SECONDS_5(Duration.ofSeconds(5)),
+        SECONDS_10(Duration.ofSeconds(10)),
+        MINUTES_1(Duration.ofMinutes(1)),
+        MINUTES_5(Duration.ofMinutes(5)),
+        MINUTES_15(Duration.ofMinutes(15));
+
+        private final Duration value;
+
+        TicksPerSecond(Duration value) {
+            this.value = value;
+        }
+
+        @Override
+        public @NotNull Duration length() {
+            return this.value;
+        }
+    }
+
+    /**
+     * The {@link StatisticWindow} used for MSPT.
+     */
+    enum MillisPerTick implements StatisticWindow {
+
+        SECONDS_10(Duration.ofSeconds(10)),
+        MINUTES_1(Duration.ofMinutes(1));
+
+        private final Duration value;
+
+        MillisPerTick(Duration value) {
+            this.value = value;
+        }
+
+        @Override
+        public @NotNull Duration length() {
+            return this.value;
+        }
+    }
+
+}
diff --git a/spark-api/src/main/java/me/lucko/spark/api/statistic/misc/DoubleAverageInfo.java b/spark-api/src/main/java/me/lucko/spark/api/statistic/misc/DoubleAverageInfo.java
new file mode 100644
index 0000000..0f882de
--- /dev/null
+++ b/spark-api/src/main/java/me/lucko/spark/api/statistic/misc/DoubleAverageInfo.java
@@ -0,0 +1,75 @@
+/*
+ * This file is part of spark.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package me.lucko.spark.api.statistic.misc;
+
+/**
+ * Statistics for a recorded double value.
+ */
+public interface DoubleAverageInfo {
+
+    /**
+     * Gets the mean value.
+     *
+     * @return the mean
+     */
+    double mean();
+
+    /**
+     * Gets the max value.
+     *
+     * @return the max
+     */
+    double max();
+
+    /**
+     * Gets the min value.
+     *
+     * @return the min
+     */
+    double min();
+
+    /**
+     * Gets the median value.
+     *
+     * @return the median
+     */
+    default double median() {
+        return percentile(0.50d);
+    }
+
+    /**
+     * Gets the 95th percentile value.
+     *
+     * @return the 95th percentile
+     */
+    default double percentile95th() {
+        return percentile(0.95d);
+    }
+
+    /**
+     * Gets the average value at a given percentile.
+     *
+     * @param percentile the percentile, as a double between 0 and 1.
+     * @return the average value at the given percentile
+     */
+    double percentile(double percentile);
+
+}
diff --git a/spark-api/src/main/java/me/lucko/spark/api/statistic/types/DoubleStatistic.java b/spark-api/src/main/java/me/lucko/spark/api/statistic/types/DoubleStatistic.java
new file mode 100644
index 0000000..ab26b7b
--- /dev/null
+++ b/spark-api/src/main/java/me/lucko/spark/api/statistic/types/DoubleStatistic.java
@@ -0,0 +1,50 @@
+/*
+ * This file is part of spark.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package me.lucko.spark.api.statistic.types;
+
+import me.lucko.spark.api.statistic.Statistic;
+import me.lucko.spark.api.statistic.StatisticWindow;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * A {@link Statistic} with a {@code double} value.
+ *
+ * @param <W> the window type
+ */
+public interface DoubleStatistic<W extends Enum<W> & StatisticWindow> extends Statistic<W> {
+
+    /**
+     * Polls the current value of the statistic in the given window.
+     *
+     * @param window the window
+     * @return the value
+     */
+    double poll(@NonNull W window);
+
+    /**
+     * Polls the current values of the statistic in all windows.
+     *
+     * @return the values
+     */
+    double[] poll();
+
+}
diff --git a/spark-api/src/main/java/me/lucko/spark/api/statistic/types/GenericStatistic.java b/spark-api/src/main/java/me/lucko/spark/api/statistic/types/GenericStatistic.java
new file mode 100644
index 0000000..2c27c05
--- /dev/null
+++ b/spark-api/src/main/java/me/lucko/spark/api/statistic/types/GenericStatistic.java
@@ -0,0 +1,51 @@
+/*
+ * This file is part of spark.
+ *
+ *  Copyright (c) lucko (Luck) <luck@lucko.me>
+ *  Copyright (c) contributors
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package me.lucko.spark.api.statistic.types;
+
+import me.lucko.spark.api.statistic.Statistic;
+import me.lucko.spark.api.statistic.StatisticWindow;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+
+/**
+ * A {@link Statistic} with a generic (non-primitive) type.
+ *
+ * @param <T> the generic value type
+ * @param <W> the window type
+ */
+public interface GenericStatistic<T, W extends Enum<W> & StatisticWindow> extends Statistic<W> {
+
+    /**
+     * Polls the current value of the statistic in the given window.
+     *
+     * @param window the window
+     * @return the value
+     */
+    T poll(@NonNull W window);
+
+    /**
+     * Polls the current values of the statistic in all windows.
+     *
+     * @return the values
+     */
+    T[] poll();
+
+}