Spark Web API

Spark Web API

A small plugin that will host a Web API for Spark.

This plugin is made for Paper. You are free to fork this on GitHub and port this to other mod loaders.

This README is a simplified version of the Project's GitHub README.

Installation

First, Install Spark to your Paper server. Even though Paper servers for Minecraft 1.21 and up has Spark built-in, a standalone plugin version is required for this plugin.

Then, Install Spark Web API. You generally would download the JAR with -all at the end of the file name.

When starting your server, Please remember to set the paper.preferSparkPlugin system property to true

Here's an example on how to do so:

java -Dpaper.preferSparkPlugin=true -jar paper-1.21-129.jar

Configuration

When starting the server for the first time with the plugin, The plugin will generate a config file. The config file allows you to change the port of the server, which routes are enabled, and add additional headers to responses.

port: 3000
routes:
  tps: true
  mspt: true
  sys_cpu: false
  proc_cpu: false
  gc: false
headers:
  enabled: false

API paths

/api/tps

Return the TPS of the past 10 seconds, 1 minute, 5 minutes, and 15 minutes.

Example Response:

{
  "tenSeconds": 19.999926688268733,
  "oneMinute": 20.000035730063832,
  "fiveMinutes": 20.00000458740105,
  "fifteenMinutes": 19.94021043987079
}

This route will return 500 Internal Server Error if Spark cannot get the TPS of the server.

/api/mspt

Returns the MSPT value for the past 10 seconds and 1 minute.

Example Response:

{
  "tenSeconds": {
    "min": 6.523605,
    "max": 2692.747083,
    "mean": 66.92731750515465,
    "median": 23.108289
  },
  "oneMinute": {
    "min": 6.523605,
    "max": 2692.747083,
    "mean": 66.92731750515465,
    "median": 23.108289
  }
}

This route will return 500 Internal Server Error if Spark cannot get the MSPT of the server.

/api/gc

Returns the information about the Garbage Collector.

Example Response:

{
  "G1 Young Generation": {
    "name": "G1 Young Generation",
    "frequency": 22328,
    "avgTime": 81,
    "totalCollections": 3,
    "totalTime": 243
  },
  "G1 Old Generation": {
    "name": "G1 Old Generation",
    "frequency": 0,
    "avgTime": 0,
    "totalCollections": 0,
    "totalTime": 0
  }
}

/api/cpu/sys

Returns the system CPU usage in percentage.

Example Response:

{
  "tenSeconds": 0.20461582280862525,
  "oneMinute": 0.31800215079510524,
  "fifteenMinutes": 0.39118254849183964
}

/api/cpu/proc

Returns the Minecraft process CPU usage in percentage.

Example Response:

{
  "tenSeconds": 0.025064927938294894,
  "oneMinute": 0.030417615615548597,
  "fifteenMinutes": 0.06684861042724896
}

License

This plugin is licensed under the MIT License.