Add a basic API for retrieving spark statistics

5 files changed, 326 insertions, 0 deletions

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();
+
+}