TickScope

插件

· 作者 gabezim

为 Paper 服务器提供 Prometheus 指标,采用轻量级插件实现,零运行时依赖。精确的 MSPT 百分位数、按世界划分的实体和区块计数、JVM 与 CPU 统计信息,可直接用于 Grafana。

0 本站下载 0 关注 更新于 2 周前

最新 2.1.0 · 26.3 · Folia / Paper

一键开服(送7天)
TickScope 图标

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

快速开始

  1. 从此页面顶部的 Files 选项卡下载最新的 jar 文件。
  2. 将 TickScope-*.jar 放入服务器的 plugins/ 目录并重启。
  3. 抓取默认端点: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 仪表板

显示玩家、TPS、精确 MSPT 百分位数和堆内存使用的 TickScope 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 许可证授权。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源