Command/agent to monitor the status of Minecraft servers
go get github.com/itzg/go-mc-status
Subcommands:
flags describe all known top-level flags
help describe subcommands and their syntax
version Show version and exit
Subcommands for monitoring:
export-for-prometheus Registers an HTTP metrics endpoints for Prometheus export
gather-for-telegraf Periodically gathers to status of one or more Minecraft servers and sends metrics to telegraf over TCP using Influx line protocol
collect-otel Periodically collects to status of one or more Minecraft servers and sends metrics to an OpenTelemetry Collector using the gRPC protocol
Subcommands for status:
status Retrieves and displays the status of the given Minecraft server
status-bedrock Retrieves and displays the status of the given Minecraft Bedrock Dedicated server
To check the status of a Java edition server:
docker run -it --rm itzg/mc-monitor status --host mc.hypixel.net
To check the status of a Bedrock Dedicated server:
docker run -it --rm itzg/mc-monitor status-bedrock --host play.fallentech.io
where exit code will be 0 for success or 1 for failure.
Some Forge servers may cause a string length out of bounds
error during status messages due to how the FML2 protocol bundles the entire modlist for client compatibility check. If there are issues with status
failing when it otherwise should work, you can try out the experimental --use-mc-utils
flag below (enables the mcutils protocol library):
docker run -it --rm itzg/mc-monitor status --use-mc-utils --host play.fallentech.io
The following example is provided in examples/mc-monitor-telegraf
Given the telegraf config file:
[[inputs.socket_listener]]
service_address = "tcp://:8094"
[[outputs.file]]
files = ["stdout"]
...and a Docker composition of telegraf and mc-monitor services:
version: '3'
services:
telegraf:
image: telegraf:1.13
volumes:
- ./telegraf.conf:/etc/telegraf/telegraf.conf:ro
monitor:
image: itzg/mc-monitor
command: gather-for-telegraf
environment:
GATHER_INTERVAL: 10s
GATHER_TELEGRAF_ADDRESS: telegraf:8094
GATHER_SERVERS: mc.hypixel.net
The output of the telegraf service will show metric entries such as:
minecraft_status,host=mc.hypixel.net,port=25565,status=success response_time=0.172809649,online=51201i,max=90000i 1576971568953660767
minecraft_status,host=mc.hypixel.net,port=25565,status=success response_time=0.239236074,online=51198i,max=90000i 1576971579020125479
minecraft_status,host=mc.hypixel.net,port=25565,status=success response_time=0.225942383,online=51198i,max=90000i 1576971589006821324
When using the export-for-prometheus
subcommand, mc-monitor will serve a Prometheus exporter on port 8080, by default, that collects Minecraft server metrics during each scrape of /metrics
.
The sub-command accepts the following arguments, which can also be viewed using --help
:
-bedrock-servers host:port
one or more host:port addresses of Bedrock servers to monitor, when port is omitted 19132 is used (env EXPORT_BEDROCK_SERVERS)
-port int
HTTP port where Prometheus metrics are exported (env EXPORT_PORT) (default 8080)
-servers host:port
one or more host:port addresses of Java servers to monitor, when port is omitted 25565 is used (env EXPORT_SERVERS)
The following metrics are exported
minecraft_status_healthy
minecraft_status_response_time_seconds
minecraft_status_players_online_count
minecraft_status_players_max_count
with the labels
server_host
server_port
server_edition
:java
orbedrock
server_version
An example Docker composition is provided in examples/mc-monitor-prom, which was used to grab the following screenshot:
Open Telemetry is a vendor-agnostic way to receive, process and export telemetry data. In this context, monitoring a Minecraft Server with Open Telemetry requires a running Open Telemetry Collector to receive the exported data. An example on how to initialize it can be found in examples/mc-monitor-otel.
Once you run the mc-monitor application using the collect-otel
subcommand, mc-monitor will create the necessary [instrumentation]
(https://opentelemetry.io/docs/languages/go/instrumentation/#metrics) to export the metrics to the collector through the gRPC protocol.
The Collector will receive and process the data, sending the metrics to any of the supported backends. In our example, you will find the necessary configurations to export metrics through Prometheus.
The collect-otel
sub-command accepts the following arguments, which can also be viewed using --help
:
-servers host:port
one or more host:port addresses of Java servers to monitor, when port is omitted 25565 is used (env EXPORT_SERVERS)
-bedrock-servers host:port
one or more host:port addresses of Bedrock servers to monitor, when port is omitted 19132 is used (env EXPORT_BED_ROCK_SERVERS)
-interval duration
Collect and sends OpenTelemetry data at this interval (env EXPORT_INTERVAL) (default 10s)
-otel-collector-endpoint string
OpenTelemetry gRPC endpoint to export data (env EXPORT_OTEL_COLLECTOR_ENDPOINT) (default "localhost:4317")
-otel-collector-timeout duration
Timeout for collecting OpenTelemetry data (env EXPORT_OTEL_COLLECTOR_TIMEOUT) (default 35s)
The following metrics are exported
minecraft_status_healthy
minecraft_status_response_time_seconds
minecraft_status_players_online_count
minecraft_status_players_max_count
with the labels
server_host
server_port
server_edition
:java
orbedrock
server_version
An example Docker composition is provided in examples/mc-monitor-otel.