Benchmark Serverside

A lightweight, AI-readable server-side performance benchmark mod for NeoForge 1.21.1. Lightweight · Sampling-based CPU profiler · JSON/Text reports · No JavaScript rendering required

📖 English

Note: This mod has nothing to do with another Benchmark mod I developed.

Overview

Benchmark Serverside is a performance benchmark mod for Minecraft servers. It samples the server main thread (Server Thread) and exports a performance report as structured JSON (or a human-readable text summary) together with full server context — mod list, plugin list (on hybrid servers), server.properties configuration, system environment and live runtime state.

The report is designed to be directly consumed by large language models (LLM) such as DeepSeek / GPT, or by server admins, so that lag sources can be located and optimized quickly — no need for JavaScript-rendered profile viewers (e.g. Spark).

Features

• Lightweight sampling profiler — uses the ThreadMXBean-based sampling approach (not instrumentation), with a configurable interval (default 50 ms) and duration (default 60 s). Sampling overhead is negligible and only runs while a benchmark is active (/bcs start), so it never affects normal server operation.
• Full environment collection — gathers mod list, plugin list (best-effort on hybrid/Bukkit servers), server config (view-distance, simulation-distance, entity-broadcast-range-percentage, network-compression-threshold, max-players), Java/JVM info, OS, CPU cores, memory, disk space, worlds, online players and current TPS.
• Hotspot analysis — aggregates sampled call stacks into a Top-N hotspot list (self & inclusive sample counts with percentages) plus representative call stacks; also separates idle/waiting vs active samples so AI can distinguish "server is mostly sleeping" from "server is busy".
• AI-friendly JSON reports — self-explanatory field names (snake_case), saved to benchmark-reports/benchmark_<yyyyMMdd_HHmmss>.json.
• Simple command interface — /bcs command tree with OP level 4 permission.

Requirements

Installation

1. Download the built jar (benchmarkserverside-1.0.0.jar) and place it into the server's mods/ folder.
2. Start the server. The mod is server-side; the client jar is not required for dedicated servers.
3. Run /bcs start and wait, then check benchmark-reports/ for the generated report.

Commands

All sub-commands require OP level 4.

Configuration

Config file: config/benchmarkserverside-common.toml (created on first run).

Report Output

Reports are saved to benchmark-reports/ in the server root:

• benchmark_<yyyyMMdd_HHmmss>.json — structured report (preferred, AI-readable)
• benchmark_<yyyyMMdd_HHmmss>.txt — human-readable summary

The JSON report includes: timestamp, sampling_duration_seconds, server_info, environment, config, plugins, mods, runtime, and profiling_results (total/idle/active samples, top_hotspots with percentages, call_stacks).

Example (abridged):

{
  "timestamp": "2026-08-16T12:00:00Z",
  "sampling_duration_seconds": 60,
  "server_info": { "type": "NeoForge", "version": "21.1.241", "minecraft_version": "1.21.1", "worlds": ["minecraft:overworld"] },
  "environment": { "java_version": "21.0.2", "os": "Windows 10 10.0 (amd64)", "cpu_cores": 8, "total_memory_mb": 16260, "free_memory_mb": 4838, "disk_free_gb": 33.0 },
  "config": { "view_distance": 10, "simulation_distance": 10, "entity_broadcast_range_percentage": 100, "network_compression_threshold": 256, "max_players": 20 },
  "mods": [ { "id": "neoforge", "name": "NeoForge", "version": "21.1.241" } ],
  "runtime": { "online_players": 0, "tps": 20.0, "process_cpu_usage_percent": 0.5, "system_cpu_usage_percent": 15.6 },
  "profiling_results": {
    "total_samples": 1200, "idle_samples": 800, "active_samples": 400,
    "top_hotspots": [
      { "method": "net.minecraft.server.level.ServerLevel.tick()", "samples": 150, "percentage": 12.5 }
    ]
  }
}

How It Works

• A daemon thread periodically captures the server main thread's call stack via ThreadMXBean#getThreadInfo(threadId, maxDepth) (safe-point sampling — low overhead, statistically meaningful).
• Samples whose innermost frame is a JDK wait/sleep are classified as idle; the rest are active and used for hotspot statistics.
• When sampling finishes (automatically or via /bcs stop), the result is compiled and the report is written on the server thread.

Building from Source

git clone https://github.com/youyiMC/Benchmark-Serverside.git
cd Benchmark-Serverside
# Windows
gradlew.bat build
# macOS / Linux
./gradlew build

The built jar will be in build/libs/benchmarkserverside-1.0.0.jar.

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

The original NeoForged MDK template files remain under the MIT license as noted in TEMPLATE_LICENSE.txt.

📖 中文版

注意：这个模组和我开发的另一个Benchmark模组没有任何关联！

简介

Benchmark Serverside 是一个面向 Minecraft 服务器的轻量级性能基准测试（Benchmark）模组。它对服务器主线程（Server Thread）进行采样，并将性能报告以结构化 JSON（或人类可读的纯文本摘要）的形式导出，同时附带完整的服务器上下文——模组列表、插件列表（混合端）、server.properties 配置、系统环境与实时运行状态。

报告专门设计为可供大语言模型（如 DeepSeek、GPT）直接阅读分析，也可供服主快速定位卡顿根源——无需像 Spark 那样依赖 JavaScript 渲染的报告。

功能特性

• 轻量级采样型 Profiler —— 基于 ThreadMXBean 的采样（Sampling）方式而非仪器（Instrumentation），采样间隔（默认 50 ms）与时长（默认 60 s）均可配置。仅在 /bcs start 后才开始采样，平时零开销，绝不干扰服务器正常运行。
• 全面的环境采集 —— 模组列表、插件列表（混合端/Bukkit 尽力而为）、服务器配置（视距、模拟距离、实体广播范围、网络压缩阈值、最大玩家数）、Java/JVM 信息、操作系统、CPU 核心、内存、磁盘、世界列表、在线玩家与当前 TPS。
• 热点分析 —— 将采样调用栈聚合成 Top N 热点列表（自耗/总耗采样数及占比）并附带代表性调用栈；同时区分空闲/等待与活跃样本，便于 AI 判断“服务器主要在睡眠”还是“服务器正忙”。
• AI 友好的 JSON 报告 —— 字段名自解释（snake_case），保存于 benchmark-reports/benchmark_<yyyyMMdd_HHmmss>.json。
• 简洁的指令接口 —— /bcs 指令树，需要 OP 4 级权限。

环境要求

安装方法

1. 将构建好的 jar（benchmarkserverside-1.0.0.jar）放入服务器的 mods/ 文件夹。
2. 启动服务器。本模组为服务端模组，专用服务器无需客户端文件。
3. 执行 /bcs start 开始采样，等待结束后在 benchmark-reports/ 目录查看生成的报告。

指令说明

所有子指令均需 OP 4 级权限。

配置说明

配置文件：config/benchmarkserverside-common.toml（首次运行自动生成）。

报告输出

报告默认保存在服务器根目录下的 benchmark-reports/ 文件夹中：

• benchmark_<yyyyMMdd_HHmmss>.json —— 结构化报告（首选，AI 可读）
• benchmark_<yyyyMMdd_HHmmss>.txt —— 人类可读的纯文本摘要

JSON 报告包含：timestamp、sampling_duration_seconds、server_info、environment、config、plugins、mods、runtime 与 profiling_results（总/空闲/活跃样本、带占比的 top_hotspots、call_stacks）。

工作原理

• 守护线程通过 ThreadMXBean#getThreadInfo(threadId, maxDepth) 周期性抓取服务器主线程调用栈（安全点采样，开销极小，统计意义上足以定位热点）。
• 栈顶帧命中 JDK 等待/睡眠方法的样本被归类为空闲，其余为活跃样本，用于热点统计。
• 采样结束（自动或 /bcs stop）后，结果被编译并在服务器主线程上写入报告文件。

从源码构建

git clone https://github.com/youyiMC/Benchmark-Serverside.git
cd Benchmark-Serverside
# Windows
gradlew.bat build
# macOS / Linux
./gradlew build

构建产物位于 build/libs/benchmarkserverside-1.0.0.jar。

许可证

本项目基于 GNU General Public License v3.0 开源，详见 LICENSE 文件。

原始 NeoForged MDK 模板文件仍按 MIT 许可证授权，详见 TEMPLATE_LICENSE.txt。