普罗米修斯导出器

Hytale Prometheus Exporter 插件

该插件通过 HTTP 端点以 Prometheus 格式输出 Hytale 服务器的指标数据。它依赖于 Nitrado:WebServer。

插件目的

在运行 Hytale 服务器时，运维人员通常需要监控服务器性能和健康指标。该插件提供了一个兼容 Prometheus 的端点，能够输出关于服务器、世界、玩家、实体以及 JVM 性能的结构化指标。

主要功能

• 玩家指标： 每个世界的在线玩家数量。
• 区块指标： 每个世界中的活跃区块、已加载区块和已生成区块数量。
• 实体指标： 每个世界中的活跃实体数量。
• 性能指标： 每个世界 TPS（每秒游戏刻）的平均值、最小值、最大值和目标值。
• 服务器配置： 输出配置的最大视野半径。
• JVM 指标： 内置 Prometheus JVM 指标（内存、GC、线程等）。
• 基于权限的访问： 端点访问受 Hytale 权限系统控制。

安装

1. 安装 Nitrado:WebServer 插件。
2. 将本插件的 JAR 文件复制到 Hytale 服务器的 mods/ 文件夹中。

用法

端点

插件在 GET /ApexHosting/PrometheusExporter/metrics 注册一个端点。

示例响应

# HELP hytale_players_online 每个世界当前在线的玩家数量
# TYPE hytale_players_online gauge
hytale_players_online{world="default"} 5

# HELP hytale_chunks_active 每个世界当前加载的区块数量
# TYPE hytale_chunks_active gauge
hytale_chunks_active{world="default"} 256

# HELP hytale_chunks_loaded 已加载或生成的区块总数
# TYPE hytale_chunks_loaded counter
hytale_chunks_loaded{world="default"} 1024

# HELP hytale_chunks_loaded_disk 从磁盘加载的区块总数
# TYPE hytale_chunks_loaded_disk counter
hytale_chunks_loaded_disk{world="default"} 512

# HELP hytale_chunks_generated 新生成的区块总数
# TYPE hytale_chunks_generated counter
hytale_chunks_generated{world="default"} 512

# HELP hytale_entities_active 每个世界当前加载的实体数量
# TYPE hytale_entities_active gauge
hytale_entities_active{world="default"} 150

# HELP hytale_world_tps_avg 基于最近游戏刻测得的每个世界在给定周期内的平均 TPS
# TYPE hytale_world_tps_avg gauge
hytale_world_tps_avg{world="default",period="60"} 20.0

# HELP hytale_world_tps_min 基于最近游戏刻测得的每个世界在给定周期内的最小 TPS
# TYPE hytale_world_tps_min gauge
hytale_world_tps_min{world="default",period="60"} 19.5

# HELP hytale_world_tps_max 基于最近游戏刻测得的每个世界在给定周期内的最大 TPS
# TYPE hytale_world_tps_max gauge
hytale_world_tps_max{world="default",period="60"} 20.0

# HELP hytale_world_tps_target 每个世界的配置 TPS 目标
# TYPE hytale_world_tps_target gauge
hytale_world_tps_target{world="default"} 20

# HELP hytale_server_max_view_radius 当前配置的最大视野半径
# TYPE hytale_server_max_view_radius gauge
hytale_server_max_view_radius 16

# HELP hytale_metrics_collector_time_ms Hytale 指标收集器耗时（毫秒）
# TYPE hytale_metrics_collector_time_ms gauge
hytale_metrics_collector_time_ms 0.5

权限

访问指标端点需要以下权限：

权限	描述
apexhosting.prometheusexporter.web.read.metrics	访问指标端点

Prometheus 配置

在您的 prometheus.yml 中添加以下抓取配置：

scrape_configs:
  - job_name: 'hytale'
    static_configs:
      - targets: ['your-server:7003']
    metrics_path: '/ApexHosting/PrometheusExporter/metrics'
    basic_auth:
      username: 'serviceaccount.prometheus'
      password: 'YourServiceAccountPassword'

为 Prometheus 创建服务账户

在 mods/Nitrado_WebServer/provisioning/prometheus.serviceaccount.json 中创建以下文件：

{
  "Enabled": true,
  "Name": "serviceaccount.prometheus",
  "PasswordHash": "$2b$10$YourBcryptHashHere",
  "Groups": [],
  "Permissions": ["apexhosting.prometheusexporter.web.read.metrics"]
}

PasswordHash 必须是您所选密码的 bcrypt 哈希值。您可以使用以下命令生成：

# 使用 htpasswd（Apache 实用工具）
htpasswd -nbBC 10 "" YourPassword | tr -d ':\n'

# 使用 mkpasswd（whois 包）
mkpasswd -m bcrypt YourPassword

请注意 serviceaccount. 前缀同时出现在用户名（用于 Prometheus）和 Name 字段（在配置文件中）。

贡献

欢迎并鼓励社区贡献。