Minecraft Observability

• Summary
• Configuration
  • :log
  • :prometheus
  • :mqtt
• Building
• License
• TODO

Summary

A PaperMC plugin that exports useful server metrics to {Prometheus, MQTT, stdout}. In principle, it was written to monitor the performance of our local hackerspace's Minecraft Server, but that has yet to be put into practice. It currently exposes:

• Average (last 1m) server TPS
• JVM statistics (memory usage, GC timings, etc)

Configuration

On first execution, the plugin should save to disk a configuration file in EDN format with contents similar to the following:

  {:publishers [{:kind :log}]
   :refresh-rate 20}

:refresh-rate is the delay, in ticks, between each report (under normal circunstances, a Minecraft server should run at around 20 ticks per second). :publishers is a list of maps specifying where to write reports to. Each publisher map contains a :kind specifying which kind of publisher this refers to, together with a set of publisher-specific parameter keys. Valid publishers include:

:log

  {:kind :log}

Logs the raw data to the Minecraft server console. It has no configurable options.

:prometheus

  {:kind :prometheus
   :port 1337}

Listens for HTTP connections on TCP :port, exposing metrics under /metrics in a Prometheus-compatible format.

:mqtt

  {:kind :mqtt
   :broker "tcp://localhost:1883"
   :topic "minecraft"
   :username "alyssa.phacker" :password "p4ssw0rd1337"}

Connects to :broker through the MQTT protocol using :username and :password, publishing performance data to :topic in JSON format. A report looks roughly like this (pretty-printed for readability):

  {
    "server": {
      "worlds": 3,
      "chunks": 768,
      "entities": 115,
      "tile-entities": 23,
      "players": 0,
      "tps": 20.000039777412447
    },
    "runtime": {
      "total-memory": 718798848,
      "free-memory": 431981560,
      "max-memory": 7471628288
    }
  }

Building

mc-observability is written in Clojure, targetting PaperMC 1.12.2. To build, install Leiningen and an appropriate JDK (8 or newer), then run lein uberjar. Copy target/observability-*-standalone.jar to your server's plugins folder.

There is no prebuilt binary available (yet).

License

mc-observability is licensed under MIT, see LICENSE on the root of this repository for more details.

TODO

• Elaborate
• Think of a better name