配置

[!INFO] Git Commit: 5ea0bc3 | Updated: 2026-10-01

配置由 GTNHLib 的配置系统管理（ExporterConfig），服务器启动时自动生成 config/prometheus_exporter.cfg。共 2 个分类、20 个选项。

注册方式

@Config(modid = PrometheusExporterMod.MODID, category = "")
public class ExporterConfig {
    public static Collector collector = new Collector();
    public static Web web = new Web();

ExporterConfig.java:9-13。在 preInit 中通过 ConfigurationManager.registerConfig(ExporterConfig.class) 注册（PrometheusExporterMod.java:202）， ConfigException 被包装成 RuntimeException 抛出（:203-205）。

category = "" 使两个嵌套类成为顶层分类 collector 与 web（不是嵌套层级）。字段为 public static 且带默认值注解，GTNHLib 通过反射写入实例字段后，调用方一律读 ExporterConfig.collector.xxx / ExporterConfig.web.xxx。

客户端也会生成这份配置文件——onPreInitialization 在 if (event.getSide() == Side.CLIENT) return; （:207）之前就完成了配置注册。

`collector` 分类（18 项）

开关（9 项，全部为 boolean）

选项	类型	默认值	源码	作用
`jwm_collector`	boolean	`true`	`:17-19`	采集 JVM 进程指标（`DefaultExports.register`）
`entities`	boolean	`true`	`:21-23`	实体指标
`tileentities`	boolean	`true`	`:25-27`	正在 tick 的方块实体指标
`tileentities_details`	boolean	`false`	`:29-31`	按类型细分方块实体指标，替代 `tileentities`
`ticks`	boolean	`true`	`:33-35`	tick 耗时指标
`chunks`	boolean	`true`	`:37-39`	区块指标
`players`	boolean	`true`	`:41-43`	玩家指标
`player_statistics`	boolean	`true`	`:45-47`	玩家统计指标
`teams`	boolean	`true`	`:49-51`	ServerUtilities 队伍指标
`self_metrics`	boolean	`true`	`:53-55`	采集器自监控指标

tileentities_details 是唯一默认关闭的开关。它不是附加输出，而是在 TileEntities.sample() 中二选一（TileEntities.java:40、:65-74）：为 true 时输出 mc_dimension_tileentities_detailed，否则输出 mc_dimension_tileentities。注释明确写 replaces tileentities。

刷新间隔（6 项，全部为 int）

单位是服务器 tick，注释统一写明 20 = 1 second。全部带 @Config.RangeInt(min = 1, max = 72000)，即允许范围 1 tick ~ 3600 秒。

选项	默认值	约合	源码
`entities_interval_ticks`	100	5 s	`:57-60`
`tileentities_interval_ticks`	100	5 s	`:62-65`
`chunks_interval_ticks`	40	2 s	`:67-70`
`players_interval_ticks`	40	2 s	`:72-75`
`player_statistics_interval_ticks`	600	30 s	`:77-80`
`teams_interval_ticks`	600	30 s	`:82-85`

分档是刻意的：廉价的采集器刷新频繁，昂贵的刷新稀疏。这些默认值与 README 中的「Collection model and caching」表格完全一致（已逐项比对源码与 README、示例配置文件）。

权限与错误策略（2 项）

选项	类型	默认值	范围	源码
`command_permission_level`	int	4	0 – 4	`:87-90`
`collector_mc_dimension_tick_errors`	enum	`LOG`	`IGNORE` / `LOG` / `STRICT`	`:92-111`

command_permission_level 被 ForgePrometheusCommand.getRequiredPermissionLevel() 直接返回（ForgePrometheusCommand.java:125），默认 4 意味着默认只有 OP 能操作 /prometheus。范围 0–4 覆盖了 Minecraft 的全部权限等级（0 = 所有人）。

collector_mc_dimension_tick_errors 是个纯枚举（TickErrorPolicy，ExporterConfig.java:131-146），控制维度 tick 事件不配对时的处理方式，在 Ticks 的两处使用（Ticks.java:161、:200）：

值	行为	后果
`IGNORE`	什么也不做（`case IGNORE -> {}`）	静默吞掉不配对事件
`LOG`	`LOG.debug(...)` 一条调试日志	默认；`debug` 级别通常不进日志文件
`STRICT`	抛 `IllegalStateException`	会崩服

配置注释（:93-110）解释了 IGNORE 的存在理由：某些 mod 的自定义维度 tick 事件启停不可靠，若每次都记录可能每秒产生 20 条 × 每维度的日志，快速撑爆 logs/debug.txt。注释也给出了 LOG 之外的第三种做法——在 log4j2.xml 中过滤掉 com.github.cpburnz.minecraft_prometheus_exporter.collectors.Ticks。

注意 STRICT 的两个分支只覆盖了「重复 start」和「无 start 的 stop」两种情况； Ticks.stopDimensionTick 中还有第三种不一致——stop 的维度与当前计时维度不同—— 那一处是无条件抛异常的（Ticks.java:212），不受本配置影响。

`web` 分类（2 项）

选项	类型	默认值	范围	源码
`listen_address`	String	`0.0.0.0`	—	`:116-118`
`listen_port`	int	`19565`	0 – 65535	`:120-124`

listen_address 默认 0.0.0.0 意味着监听所有网卡（注释写 Default is everywhere）—— 指标端点无任何认证，部署时需靠防火墙或反向代理限制访问。

listen_port 默认 19565 而非常见的 9100。注释解释了取值来源：

The default TCP port ot use.
It was derived from the Minecraft port (25565) and the Prometheus exporter ports (9100+)

ExporterConfig.java:122-123（原文 ot 为 to 的拼写错误，且该错字已同步写入 examples/prometheus_exporter.cfg:82）。19565 = 25565 − 6000。

配置的生效时机

开关类选项只在 initCollectors() 时读取一次（PrometheusExporterMod.java:132-147），即服务器启动或执行 /prometheus restart 时。改动配置文件后必须重启导出器才生效。

唯一的例外是 ticks——Ticks 的事件订阅带 @EventBusSubscriber.Condition，在事件分发时实时求值（Ticks.java:105-108），因此改 ticks 无需重启。 collector_mc_dimension_tick_errors 同理，在错误发生时才读取（Ticks.java:161、:200）。

间隔类选项则在下一次 startExporter() 时被读入采集器构造函数，构造后即固定—— 运行期改间隔需要重启导出器。

20 个选项全部被实际读取

已 grep 确认 20 个配置字段无一是死配置：jwm_collector（PrometheusExporterMod:132）、 tileentities_details（TileEntities:40）、command_permission_level （ForgePrometheusCommand:125）、collector_mc_dimension_tick_errors（Ticks:161、:200）等均有读取点，其余 6 个间隔与 6 个开关在 initCollectors() 中读取。

配置文件示例

仓库中的 examples/prometheus_exporter.cfg 是完整生成的配置样例，其默认值与 ExporterConfig.java 中的注解逐项一致（已比对：9 个 boolean 开关、6 个间隔、权限等级、错误策略、地址与端口共 20 项全部吻合）。Forge 的 Configuration 按字段名字母序 输出，所以文件中的排列顺序是 chunks → collector_mc_dimension_tick_errors → command_permission_level → entities → …，与源码声明顺序无关。

配置