Merge pull request #14 from Cubxity/dev

Release 0.2.0

README.md

@@ -10,17 +10,33 @@ This project is licensed under [GNU AGPLv3](LICENSE)
 ![Grafana Dashboard](.github/assets/grafana.png)
 
 ## Compatbility
+**Server:**
 - 1.8+ Spigot servers
 - Velocity
 
+**Metrics:**
+- Prometheus
+- InfluxDB
+
 ## Features
 - Server metrics collection (TPS, MSPT, Players, Plugins)
 - World metrics collection (Entities, Chunks)
 - Events metrics collection (Player flow, chat, pings)
 - JVM metrics collection (Memory, CPU Load, Threads, Uptime)
-- Extensible API (Custom metrics, measurements, metrics driver) 
+- Extensible API (Custom metrics, samples, metrics driver) 
 - More features upcoming (Logging to ElasticSearch, etc)
 
+## Getting started
+Read the [wiki](https://github.com/Cubxity/UnifiedMetrics/wiki) for instructions.
+
+## Data visualization and analysis
+We recommend using [Grafana](https://grafana.com/) as it provides highly customizable diagrams.
+Grafana provides out-of-box support for Prometheus and InfluxDB.
+
+- Add Prometheus/InfluxDB datasource to Grafana
+- Import our [Prometheus dashboard](https://grafana.com/grafana/dashboards/14017) or [InfluxDB dashboard](https://grafana.com/grafana/dashboards/13860)
+- Configure the dashboard and set up alerts *(optional)*
+
 ## API
 Add `:unifiedmetrics-api` as a dependency (compileOnly/provided).
 
@@ -31,42 +47,3 @@ import dev.cubxity.plugins.metrics.api.UnifiedMetricsProvider
 
 val api = UnifiedMetricsProvider.get()
 ```
-
-## Installation
-
-- Add the plugin to your `plugins` folder.
-- Configure the plugin. (See [Configuration](#Configuration)).
-- Restart the server. **(NOTE: Reload is not supported and may cause issues)**
-
-## Configuration
-
-Currently, [InfluxDB](https://www.influxdata.com/) is required to collect metrics.
-We recommend using an internal network for InfluxDB.
-
-**config.toml**
-```toml
-[server]
-server = "main"
-
-[metrics]
-enabled = true
-driver = "influx"
-```
-
-**driver/influx.toml**
-```toml
-[influx]
-url = "http://influxdb:8086"
-bucket = "unifiedmetrics"
-username = "influx"
-password = "influx"
-interval = 10 # Interval in seconds
-```
-
-## Data visualization and analysis
-We recommend using [Grafana](https://grafana.com/) as it provides highly customizable diagrams.
-Grafana provides out-of-box support for InfluxDB.
-
-- Add InfluxDB datasource to Grafana
-- Import our [dashboard](https://grafana.com/grafana/dashboards/13860)
-- Configure the dashboard and set up alerts *(optional)*

api/src/main/kotlin/dev/cubxity/plugins/metrics/api/metric/Metric.kt

@@ -18,19 +18,23 @@
 
 package dev.cubxity.plugins.metrics.api.metric
 
-import dev.cubxity.plugins.metrics.api.UnifiedMetrics
-import dev.cubxity.plugins.metrics.api.metric.data.Measurement
+import dev.cubxity.plugins.metrics.api.metric.collector.MetricCollector
+import dev.cubxity.plugins.metrics.api.metric.data.MetricSample
 
-interface Metric<T : Measurement> {
- val isSync: Boolean
+interface Metric {
+ /**
+ * List of collectors associated with this metric.
+ */
+ val collectors: List<MetricCollector>
 
  fun initialize() {
  // Do nothing
  }
 
- fun getMeasurements(api: UnifiedMetrics): List<T>
-
  fun dispose() {
  // Do nothing
  }
-}
+}
+
+fun Metric.collect(): List<MetricSample> =
+ collectors.flatMap { it.collect() }

api/src/main/kotlin/dev/cubxity/plugins/metrics/api/metric/MetricsDriver.kt

@@ -21,7 +21,5 @@ package dev.cubxity.plugins.metrics.api.metric
 import java.io.Closeable
 
 interface MetricsDriver : Closeable {
- fun connect()
-
- fun scheduleTasks() {}
+ fun initialize()
 }

api/src/main/kotlin/dev/cubxity/plugins/metrics/api/metric/MetricsManager.kt

@@ -18,20 +18,21 @@
 
 package dev.cubxity.plugins.metrics.api.metric
 
-import dev.cubxity.plugins.metrics.api.metric.data.Point
+import dev.cubxity.plugins.metrics.api.metric.data.MetricSample
 
 interface MetricsManager {
- val metrics: List<Metric<*>>
+ val metrics: List<Metric>
 
  fun initialize()
 
- fun registerMetric(metric: Metric<*>)
+ fun registerMetric(metric: Metric)
 
- fun unregisterMetric(metric: Metric<*>)
+ fun unregisterMetric(metric: Metric)
 
  fun registerDriver(name: String, factory: MetricsDriverFactory)
 
- fun serializeMetrics(isSync: Boolean): List<Point>
-
  fun dispose()
-}
+}
+
+fun MetricsManager.collect(): List<MetricSample> =
+ metrics.flatMap { it.collect() }

api/src/main/kotlin/dev/cubxity/plugins/metrics/api/metric/collector/Counter.kt

@@ -0,0 +1,52 @@
+/*
+ * UnifiedMetrics is a fully-featured metrics collection plugin for Minecraft servers.
+ * Copyright (C) 2021 Cubxity
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package dev.cubxity.plugins.metrics.api.metric.collector
+
+import dev.cubxity.plugins.metrics.api.metric.data.CounterSample
+import dev.cubxity.plugins.metrics.api.metric.data.MetricSample
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * @param name name of the sample. Should end with '_total'
+ */
+class Counter(val name: String) : MetricCollector {
+ private val tags: MutableMap<String, String> = HashMap()
+ private val count = AtomicInteger()
+
+ override fun collect(): List<MetricSample> {
+ val sample = CounterSample(name, count.get().toDouble(), tags)
+ return listOf(sample)
+ }
+
+ fun inc() {
+ count.incrementAndGet()
+ }
+
+ fun dec() {
+ count.decrementAndGet()
+ }
+
+ operator fun plusAssign(delta: Int) {
+ count.addAndGet(delta)
+ }
+
+ operator fun minusAssign(delta: Int) {
+ count.addAndGet(-delta)
+ }
+}

api/src/main/kotlin/dev/cubxity/plugins/metrics/api/metric/collector/Gauge.kt

@@ -0,0 +1,56 @@
+/*
+ * UnifiedMetrics is a fully-featured metrics collection plugin for Minecraft servers.
+ * Copyright (C) 2021 Cubxity
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package dev.cubxity.plugins.metrics.api.metric.collector
+
+import dev.cubxity.plugins.metrics.api.metric.data.GaugeSample
+import dev.cubxity.plugins.metrics.api.metric.data.MetricSample
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * @param name name of the sample.
+ */
+class Gauge(val name: String) : MetricCollector {
+ private val tags: MutableMap<String, String> = HashMap()
+ private val count = AtomicInteger()
+
+ override fun collect(): List<MetricSample> {
+ val sample = GaugeSample(name, count.get().toDouble(), tags)
+ return listOf(sample)
+ }
+
+ fun set(value: Int) {
+ count.set(value)
+ }
+
+ fun inc() {
+ count.incrementAndGet()
+ }
+
+ fun dec() {
+ count.decrementAndGet()
+ }
+
+ operator fun plusAssign(delta: Int) {
+ count.addAndGet(delta)
+ }
+
+ operator fun minusAssign(delta: Int) {
+ count.addAndGet(-delta)
+ }
+}

api/src/main/kotlin/dev/cubxity/plugins/metrics/api/metric/collector/MetricCollector.kt

@@ -0,0 +1,33 @@
+/*
+ * UnifiedMetrics is a fully-featured metrics collection plugin for Minecraft servers.
+ * Copyright (C) 2021 Cubxity
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package dev.cubxity.plugins.metrics.api.metric.collector
+
+import dev.cubxity.plugins.metrics.api.metric.data.MetricSample
+
+const val NANOSECONDS_PER_SECOND: Double = 1E9
+const val MILLISECONDS_PER_SECOND: Double = 1E3
+
+interface MetricCollector {
+ /**
+ * Collects the metric and returns a list of samples.
+ *
+ * @return [List] of [MetricSample]
+ */
+ fun collect(): List<MetricSample>
+}

api/src/main/kotlin/dev/cubxity/plugins/metrics/api/metric/data/MetricSample.kt

@@ -0,0 +1,45 @@
+/*
+ * UnifiedMetrics is a fully-featured metrics collection plugin for Minecraft servers.
+ * Copyright (C) 2021 Cubxity
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package dev.cubxity.plugins.metrics.api.metric.data
+
+data class MetricSample(
+ val type: MetricType,
+ val name: String,
+ val value: Double,
+ val tags: Map<String, String> = emptyMap()
+)
+
+fun MetricSample(
+ type: MetricType,
+ name: String,
+ value: Number,
+ tags: Map<String, String> = emptyMap()
+): MetricSample = MetricSample(type, name, value.toDouble(), tags)
+
+fun CounterSample(name: String, value: Double, tags: Map<String, String> = emptyMap()): MetricSample =
+ MetricSample(MetricType.Counter, name, value, tags)
+
+fun CounterSample(name: String, value: Number, tags: Map<String, String> = emptyMap()): MetricSample =
+ MetricSample(MetricType.Counter, name, value, tags)
+
+fun GaugeSample(name: String, value: Double, tags: Map<String, String> = emptyMap()): MetricSample =
+ MetricSample(MetricType.Gauge, name, value, tags)
+
+fun GaugeSample(name: String, value: Number, tags: Map<String, String> = emptyMap()): MetricSample =
+ MetricSample(MetricType.Gauge, name, value, tags)

api/src/main/kotlin/dev/cubxity/plugins/metrics/api/metric/data/MetricType.kt

@@ -0,0 +1,28 @@
+/*
+ * UnifiedMetrics is a fully-featured metrics collection plugin for Minecraft servers.
+ * Copyright (C) 2021 Cubxity
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package dev.cubxity.plugins.metrics.api.metric.data
+
+/**
+ * Prometheus-compatible metric types. The Prometheus server does not yet make use of the type information.
+ */
+sealed class MetricType {
+ object Unknown : MetricType()
+ object Counter : MetricType()
+ object Gauge : MetricType()
+}

build.gradle.kts

@@ -20,15 +20,15 @@ import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
- kotlin("jvm") version "1.4.30"
- kotlin("kapt") version "1.4.30"
+ kotlin("jvm") version "1.4.31"
+ kotlin("kapt") version "1.4.31"
  id("com.github.johnrengelman.shadow") version "6.1.0" apply false
 }
 
 allprojects {
  group = "dev.cubxity.plugins"
  description = "Fully featured metrics collector agent for Minecraft servers."
- version = "0.1.2"
+ version = "0.2.0"
 
  repositories {
  mavenCentral()