TickScope — 用于 Prometheus 和 Grafana 的 Minecraft 监控
从 1.x 升级: 2.0 版本更改了若干指标名称,并将刻持续时间(tick duration)和延迟(ping)的单位改为秒。请使用 迁移指南 更新仪表板和警报规则。
TickScope 是一个轻量级的 Prometheus 导出器,适用于 Minecraft Paper 和 Folia 服务器。该插件无需外部依赖,可暴露刻健康状态、玩家数量、按世界划分的计数器、JVM 和 CPU 统计信息,以及用于 Grafana 仪表板的玩家事件计数器。
mc_tick_duration_seconds{server="paper",statistic="p99"} 0.0216
mc_tps{server="paper",window="1m"} 20
mc_players_online{server="paper"} 4
mc_world_entities_by_type{server="paper",world="world",type="chicken"} 35
亮点
- 基于 Paper 原始 tick-duration 窗口的精确 p50、p95 和 p99 刻时间,以及支持在任意窗口和跨服务器使用
histogram_quantile的累积刻时间直方图 - 在 Folia 兼容服务器 API 提供相关数据时(包括 Canvas),展示玩家活跃的区域 TPS 和平均 MSPT 摘要
- 按世界统计实体数量、实体类型、方块实体、区块、玩家,以及区块加载、卸载和生成计数器
- JVM 内存区域与池、NIO 缓冲区池、线程、垃圾回收、进程 CPU、打开的文件描述符及运行时长
- 服务器及按世界划分的视距和模拟距离、在线模式和白名单状态
- 无运行时依赖、无出站遥测数据、无需数据库或嵌入式框架
- 主线程安全快照;HTTP 抓取操作绝不会调用 Bukkit API 或阻塞刻执行
- 可选的 Bearer 认证及安全失败配置重载
- 一个 jar 文件同时支持 Paper 和 Purpur 1.18.2+,并在受支持的现代版本上支持 Folia 和 Canvas
快速开始
- 从此页面顶部的 Files 选项卡下载最新的 jar 文件。
- 将
TickScope-*.jar放入服务器的plugins/目录并重启。 - 抓取默认端点:
http://127.0.0.1:9101/metrics。
scrape_configs:
- job_name: minecraft
static_configs:
- targets: ["127.0.0.1:9101"]
默认端点是开放的,但绑定到本地回环地址。当 Minecraft 在 Docker 中运行时,请在更改绑定地址之前参阅 Docker 安装说明。只要指标数据经过你不完全控制的网络,请配置 Bearer 认证和 TLS。
Grafana 仪表板
下载仪表板 JSON,将其导入 Grafana, 并选择抓取 TickScope 数据的 Prometheus 数据源。内置的服务器选择器支持单个 Paper 服务器或一组独立标记的后端网络。
采集健康状态与警报
即使 HTTP 端点仍然可达,也能跟踪采集的新鲜度和故障情况。Folia 采样会发布部分覆盖率,并显示每个玩家的待处理工作量。世界排除项和实体类型白名单有助于控制采集范围。
请参阅 健康指标、过滤器和设置说明、 Prometheus 警报规则 以及可选的 单服务器仪表板。
文档
完整手册位于 TickScope Wiki。 有关更改的名称和单位,请参阅 2.0 指标迁移指南。
| 指南 | 涵盖内容 |
|---|---|
| 安装 | 要求、升级、Prometheus 和 Docker |
| 配置 | 所有设置、Bearer 认证和命令 |
| 指标参考 | 指标名称、标签、语义和 PromQL 注意事项 |
| Grafana 和 Prometheus | 抓取、远程写入和仪表板示例 |
| 设计与隐私 | 架构、采集成本和安全性模型 |
| 故障排除 | 兼容性、缺失序列和卡顿诊断 |
| 开发与发布 | 构建、测试、发布和支持 |
| 指标稳定性 | 名称、标签和语义的兼容性保证 |
兼容性
支持 Paper 1.18.2+、兼容 Paper 的 Purpur 服务器、Folia 以及兼容 Folia 的 Canvas 服务器。不支持 Spigot、Bukkit、Velocity 和 BungeeCord。在代理网络的每个后端上安装 TickScope,并为每个服务器分配唯一的 server-id。
Minecraft 26.3 已列入兼容性列表,CI 针对 Paper 的稳定 26.3 API 进行编译和测试。维护者尚未对 26.3 上的运行时兼容性进行冒烟测试。
Paper 暴露单个服务器刻(tick),因此 TickScope 在此发布精确的 mc_tick_duration_seconds、mc_tick_samples 和 mc_tps 指标系列。Folia 没有真实的跨服等效项。在 Folia 上,这些指标系列被有意移除,并替换为基于在线玩家位置采样的 mc_folia_region_tps 摘要。暴露区域平均刻时长的服务器(包括 Canvas)也会接收 mc_folia_region_tick_duration_seconds;这是每个玩家活跃区域的平均刻时长,而非全局百分位数。由于穿越世界时会跨越区域所有权边界,Folia 上无法获取按世界划分的实体总数、方块实体总数以及按实体类型的细分数据。但按世界划分的区块和玩家数量,以及其他所有服务器、玩家、事件、JVM 和进程指标仍然可用。
在 Paper 上,这三个指标系列来自较慢的扫描过程(entity-types.interval-ticks,默认值为 600 个刻)。每次刻最多检查 entity-types.chunks-per-tick 个已加载区块,默认为 32。因此,一次扫描可能跨越多个刻;其总计值是该时间段内世界的近似视图。
支持
TickScope 由 Gabe Zimbric 维护,并根据 GPL-3.0-or-later 许可证授权。
TickScope — Minecraft monitoring for Prometheus and Grafana
Upgrading from 1.x: 2.0 changes several metric names and expresses tick duration and ping in seconds. Update dashboards and alerts with the migration guide.
TickScope is a lightweight Prometheus exporter for Minecraft Paper and Folia servers. The dependency-free plugin exposes tick health, players, per-world counters, JVM and CPU statistics, and player event counters for dashboards in Grafana.
mc_tick_duration_seconds{server="paper",statistic="p99"} 0.0216
mc_tps{server="paper",window="1m"} 20
mc_players_online{server="paper"} 4
mc_world_entities_by_type{server="paper",world="world",type="chicken"} 35
Highlights
- Exact p50, p95, and p99 tick times from Paper's raw tick-duration window, plus a cumulative
tick-time histogram for
histogram_quantileacross any window and across servers - Player-active regional TPS and average MSPT summaries where the Folia-compatible server API exposes them (including Canvas)
- Per-world entities, entity types, tile entities, chunks, players, and chunk load, unload and generation counters
- JVM memory areas and pools, NIO buffer pools, threads, garbage collection, process CPU, open file descriptors, and uptime
- Server and per-world view and simulation distance, online mode, and whitelist state
- No runtime dependencies, outbound telemetry, database, or embedded framework
- Main-thread-safe snapshots; HTTP scrapes never call Bukkit or block a tick
- Optional bearer authentication and failure-safe configuration reloads
- One jar for Paper and Purpur 1.18.2+, plus Folia and Canvas on supported modern releases
Quick start
- Download the latest jar from the Files tab at the top of this page.
- Put
TickScope-*.jarin the server'splugins/directory and restart. - Scrape the default endpoint at
http://127.0.0.1:9101/metrics.
scrape_configs:
- job_name: minecraft
static_configs:
- targets: ["127.0.0.1:9101"]
The default endpoint is open but bound to loopback. When Minecraft runs in Docker, follow the Docker installation notes before changing the bind address. Configure bearer authentication and TLS whenever metrics cross a network you do not fully control.
Grafana dashboard
Download the dashboard JSON, import it into Grafana, and select the Prometheus data source that scrapes TickScope. A built-in server selector supports one Paper server or a network of independently labeled backends.
Collection health and alerting
Track collection freshness and failures even when the HTTP endpoint remains reachable. Folia sampling publishes partial coverage and bounds outstanding work per player. World exclusions and an entity-type allowlist help control collection scope.
See health metrics, filters, and setup instructions, the Prometheus alert rules, and the optional per-server dashboard.
Documentation
The full manual lives in the TickScope wiki. See the 2.0 metric migration guide for changed names and units.
| Guide | Covers |
|---|---|
| Installation | Requirements, upgrades, Prometheus, and Docker |
| Configuration | Every setting, bearer authentication, and commands |
| Metrics reference | Metric names, labels, semantics, and PromQL notes |
| Grafana and Prometheus | Scrape, remote-write, and dashboard examples |
| Design and privacy | Architecture, collection cost, and security model |
| Troubleshooting | Compatibility, missing series, and lag diagnosis |
| Development and releases | Building, testing, releases, and support |
| Metric stability | Compatibility guarantees for names, labels, and semantics |
Compatibility
Paper 1.18.2+, Paper-compatible Purpur servers, Folia, and Folia-compatible Canvas servers are
supported. Spigot, Bukkit, Velocity, and BungeeCord are not supported. Install TickScope on each
backend in a proxy network and assign each server a unique server-id.
Minecraft 26.3 is listed for compatibility, and CI compiles and tests against Paper's stable 26.3 API. Runtime compatibility on 26.3 has not been smoke-tested by the maintainer.
Paper exposes a single server tick, so TickScope publishes exact mc_tick_duration_seconds,
mc_tick_samples, and mc_tps series there. Folia has no truthful server-wide equivalent. On Folia, those series are
intentionally absent and are replaced by mc_folia_region_tps summaries sampled at online player
locations. Servers exposing regional average tick times, including Canvas, also receive
mc_folia_region_tick_duration_seconds; this is average tick duration per player-active region
rather than a global percentile. Per-world entity totals, tile-entity totals, and the entity-type breakdown are
unavailable on Folia, because walking a world crosses region ownership boundaries; per-world chunk
and player counts, and all other server, player, event, JVM, and process metrics, remain
available.
On Paper those three series come from a slower scan (entity-types.interval-ticks, 600 ticks by
default). It inspects at most entity-types.chunks-per-tick loaded chunks on each tick, 32 by
default. A scan may therefore span multiple ticks; its totals are an approximate view of the
world over that interval.
Support
TickScope is maintained by Gabe Zimbric and licensed under GPL-3.0-or-later.
下载 TickScope
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TickScope
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TickScope
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TickScope
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TickScope
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TickScope
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TickScope
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TickScope
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TickScope
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 TickScope
更改
修复:
- 在 Folia 上,插件被禁用并再次启用(例如通过插件管理器)时未收集任何数据:关闭标志和已关闭玩家采样器从未重置。两者均在启用时重置,且事件计数器可跨此流程保留。
- 在 Folia 上,重载操作会将发布的快照替换为全零占位符持续一个 tick,并丢弃一个间隔内的延迟和区域摘要。重载会保留当前快照,并将上一次接受的玩家样本带入新的采集器。
- 首次收集前发布的占位符报告堆内存为零、运行时间为零且启动时间为 1970 年。JVM、进程和事件读数从一开始就是真实的;只有服务器拥有的值需等待首次收集。
/tickscope reload期间首次采样失败会导致采集器没有计划任务且端点冻结。该采样受到保护,如同所有计划任务一样,并且配置文件会在获取运行时锁之前读取,因此 Folia 的全局区域不会等待磁盘 I/O。mc_events_total{event="chat"}仅统计未被插件取消的消息,这导致在聊天插件取消并重发每条消息的服务器上其值为零。现已计入被取消的聊天消息:该系列统计玩家发送的消息。- 包含非 ASCII 字符的令牌无法进行身份验证,因为请求头是逐字节解码的。现在将请求头作为 UTF-8 解码。
- 以
Zombie或minecraft:zombie形式写入的entity-types.allowlist条目静默匹配不到内容。条目会被规范化为小写的注册表键(不带命名空间),无法作为注册表名称的条目将被拒绝。 - 以
//开头或包含%的path虽被接受但不可达;带括号的 IPv6bind-address(如[::1])会在/tickscope status中生成无效 URL;仅由空格组成的auth-token会静默禁用身份验证。以上三种情况均在解析时处理。 - 交换截止日期从接受连接时开始计算,而非从工作线程拾取连接时开始,因此排在停滞客户端后面的连接不再可能无限期等待。取消看门狗任务后会立即离开调度程序,而不是停留 15 秒。
- 渲染器故障会返回 500 并每分钟记录一次日志,而不是静默关闭连接;过长的请求行或头部行会返回 414 或 431,而不是直接关闭连接;请求行之前的空行会被容忍。配置了令牌后,每个缺少令牌的请求在未检查路径或方法之前就会返回 401。
mc_tick_duration_seconds在 Paper 的 tick 环有采样数据之前不存在,而不是在新启动的服务器上对所有统计数据报告 0 秒。mc_tick_samples仍表示窗口容纳了多少个 tick。- 每个指标族都作为一个连续块按稳定顺序写入。Prometheus 接受了交错输出,但更严格的文本格式解析器会将此类指标族拆分为未类型的片段。
- 当未启用按世界或实体类型系列时,
/tickscope status对世界扫描显示disabled,并在启动失败时显示此状态而不是抛出错误。 - 在 Folia 上,具有意外返回值的区域指标方法会被忽略,而不是导致每次玩家采样失败。
功能:
mc_tick_time_seconds:Paper 上基于 tick 结束事件的 tick 持续时间累积直方图:支持跨任意窗口和服务器使用histogram_quantile,从其计数中获取无上限的 tick 速率,以及跨任意范围的平均 tick 时间。mc_world_chunk_loads_total、mc_world_chunk_unloads_total和mc_world_chunk_generations_total:按世界统计,适用于 Paper 和 Folia。mc_jvm_memory_pool_*:按内存池统计,包括池最后一次收集后的占用量,以及mc_jvm_buffer_pool_*:用于 JDK 跟踪的 NIO 缓冲区池。mc_process_open_fds和mc_process_max_fds:在 HTTP 线程而非 tick 线程上读取;在 JVM 无法报告它们的地方不存在。mc_server_view_distance、mc_server_simulation_distance、mc_server_online_mode、mc_server_whitelist_enabled和mc_server_whitelist_enforced,以及mc_world_view_distance和mc_world_simulation_distance。mc_events_total新增command(玩家类型,未被取消)和kick值。mc_http_connections_rejected_total:按原因统计端点拒绝的连接数。auth-tokens除auth-token外还接受其他令牌,以便在轮换令牌时避免刮取失败。令牌更改就地应用;监听器不再重启。max-connections-per-address:使每地址连接上限(默认为 2)可配置,适用于共享反向代理或 NAT 地址的刮取器。- Grafana 仪表板新增了直方图分位数、tick 时间分布、实际 tick 速率、区块 churn 和生成、收集后的内存池、缓冲区池、文件描述符和拒绝连接的面板。警报包新增了
TickScopeFileDescriptorsNearLimit。
变更:
- 方块实体总数来自每次扫描时对每个世界的区块持有者的一次遍历,而不是对每个区块实体分配方块状态的逐区块遍历。扫描在到达每个世界时获取该世界的区块列表,而不是一次性获取所有列表。
- 随附的配置注释说明了强制执行的最小值、区块预算范围、接受的白名单格式、连接上限以及
entity-types.interval-ticks测量的内容:两次扫描之间的空闲间隙,而非扫描周期。 - 发布工作流程在重试时刷新 GitHub 发行说明,Modrinth 项目正文来自一个在相对链接时失败的脚本,链接检查器覆盖
docs/和警报规则,CI 针对 Paper 的稳定 26.3 API 进行编译和测试。
升级说明: 现有配置文件仍可正常使用。每个新版本均为新增内容;不会重命名或删除任何内容。mc_events_total 现在多出两个 event 值,因此不带 by (event) 的 sum(rate(mc_events_total[5m])) 现在会包含命令和踢出事件。重启后的最初几秒内没有 mc_tick_duration_seconds 数据;在安装了拦截聊天插件的服务端上,mc_events_total{event="chat"} 的计数会更多。请重新导入仪表板以查看新增的面板。
完整更新日志:
更新内容
- 在 Modrinth 和 Hangar 的 Paper 兼容性列表中添加了 Minecraft 26.3。相同的 Java 17 插件仍兼容旧版受支持版本;同时也在 CI 中针对 Paper 26.3 API 进行了编译和测试。
- Paper 26.3 服务器构建版本仍处于 alpha 阶段。26.3 上的运行时兼容性尚未进行冒烟测试,因此生产服务器请使用稳定的 Paper 发行版。
完整更新日志:
关于这个资源的讨论、问题反馈与使用心得
还没有讨论,来发第一帖吧
你是这个资源的作者?登录后可认领此资源。
相似资源
插件
PacketEvents 是一款专为 Minecraft Java 版打造的协议库,旨在简化数据包的处理与传输。
插件
ExyliaPlugins 的库。
插件
通过对话框或铁砧界面帮助你的 Anthme
插件
重新定义服务器上的生物运输方式。使用高度可定制的口袋道具,安全地捕获、存储和释放任何实体。
插件
为基于 Spigot/Paper/Folia 的服务器添加对 Vivecraft 的支持
插件
用于绘制游戏内地图或在浏览器中随探索实时进行地图绘制的实时地图。
评论 0
登录后参与评分
还没有评论,来抢沙发吧