Loki 废弃配置检查器 deprecated-config-checker：原理、使用与配置项维护指南

Loki 废弃配置检查器 deprecated-config-checker：原理、使用与配置项维护指南

【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki

导读

本文围绕 Loki 仓库中 tools/deprecated-config-checker 工具，讲解如何一键扫描你的 Loki 配置文件（普通配置与 runtime 配置），定位其中已经废弃（deprecated）和已经删除（deleted）的选项，并在升级 Loki 版本前完成存量配置的体检与迁移。读完本文你将掌握：工具的完整命令行用法与输出语义、deprecated-config.yaml/deleted-config.yaml注解文件的编写语法（含_msg/_values两种形态）、底层递归匹配与 per-tenant 覆盖检查的实现原理，以及如何为项目新增一条废弃/删除配置并同步维护测试。

工具定位：为什么需要它

Loki 在版本演进中会不断移除旧配置项。删除行为分为两档：

• Deprecated（已废弃）：当前仍可被解析，但已被更优的配置替代，未来版本会移除；
• Deleted（已删除）：已被彻底移除，配置中继续保留它们将不再生效，甚至可能导致升级后行为与预期不符。

手工翻阅 changelog 逐条核对配置既不现实也容易遗漏。README 给出的定位非常直接：该脚本用于检查你的配置文件中是否使用了已废弃或已删除的选项。它通过一组集中维护的"注解清单"（即deprecated-config.yaml与deleted-config.yaml），以递归路径匹配的方式扫描用户配置，把"哪条配置、当前值是什么、为什么被废弃/删除、该换用什么"一次性以可读文本输出，并可用非零退出码接入升级检查流程。

快速上手：命令行用法

运行示例

工具以 Go 程序形式直接运行，无需额外安装二进制。执行-help可查看全部参数。仓库 README 给出了标准调用方式：

go run tools/deprecated-config-checker/main.go \ -config.file tools/deprecated-config-checker/test-fixtures/config.yaml \ -runtime-config.file tools/deprecated-config-checker/test-fixtures/runtime-config.yaml

上面同时传入普通配置文件与 runtime 配置文件，一次扫描两类配置。若只需检查其中一种，只传对应的-config.file或-runtime-config.file即可——从 checker.go 的校验逻辑看，二者至少必须提供一个，否则程序报错config.file or runtime-config.file are required并退出。

全部命令行参数

参数在 checker.go 的RegisterFlags中注册：

注解文件均有内置默认路径，日常使用时通常无需覆盖；默认值常量定义在 checker.go。

输出格式与退出码

检查结果分四组输出（main.go）：

1. -- Deprecated Configs --（黄色），每条以[*]前缀；
2. -- Deleted Configs --（红色），每条以[-]前缀；
3. -- Deprecated Runtime Configs --（黄色，[*]）；
4. -- Deleted Runtime Configs --（红色，[-]）。

单条提示的文本格式由DeprecationNotes.String()生成（checker.go），形如：

<配置路径> = <当前值>: <说明消息> |- Deprecated values: <注解中登记的废弃值列表>

• 配置路径以.分隔嵌套层级，列表元素以[下标]表示，例如schema_config.configs.[0].store；
• 当前值为列表时展示为[...]形式；
• 末尾的|- Deprecated/Removed values:行仅在该项针对"特定取值"废弃时出现。

只要发现任何废弃或删除配置（无论是普通配置还是 runtime 配置），程序都会打印提示"请参阅官方升级指南了解更多细节"，并以退出码 1结束（main.go）；全部干净时输出No deprecated or deleted configs found.。

注解文件语法：如何描述一条废弃/删除规则

工具的核心是两份 YAML 注解文件，语法完全一致（deleted-config.yaml开头注释即说明"语法与 deprecated-config.yaml 相同"）：

• deprecated-config.yaml：登记已废弃选项；
• deleted-config.yaml：登记已删除选项。

形态一：整条配置废弃（值为消息字符串）

最简单的方式：键为配置路径，值为一段人类可读的说明消息。

# deprecated-config.yaml 中的真实示例 index_gateway: ring: replication_factor: "Use global or per-tenant index_gateway_shard_size configuration from limits_config." server: grpc_server_stats_tracking_enabled: "Deprecated, currently doesn't do anything, will be removed in a future version."

这表示：只要用户配置中出现index_gateway.ring.replication_factor，无论取值是什么，都判定为命中废弃。

形态二：仅特定取值废弃（_values+_msg）

有时只有某配置项的部分取值被废弃。此时用_values列出废弃取值，_msg给出替代建议。这是deleted-config.yaml中schema_config.configs的用法：

schema_config: configs: store: _values: [ "aws", "aws-dynamo", "gcp", "gcp-columnkey", "bigtable", "bigtable-hashed", "cassandra", "grpc", ] _msg: "Use tsdb or boltdb-shipper instead." object_store: _values: [ "aws-dynamo", "gcp", "gcp-columnkey", "bigtable", "bigtable-hashed", "cassandra", "grpc", ] _msg: "Use a different supported object storage instead."

解析逻辑见 checker.go 的getDeprecationAnnotation：

• 值为字符串 → 整体废弃，_values为空；
• 值为 Map 且含_msg字段 → 读取_values（字符串列表）与_msg；
• 值为 Map 但无_msg→ 视为中间层级，继续向下递归。

匹配语义（checker.go）：若_values为空，配置键只要出现即命中；若_values非空，则只有当用户配置中的取值（支持字符串、数字、布尔、列表逐项比对）与_values中任一值相等时才命中。

deprecated-config.yaml中还有一个值得注意的约定：

## NOTE: This will also be used to validate per-tenant overrides. limits_config: {}

空对象limits_config: {}作为注解占位符——它自身不产生任何命中，但告诉检查器：limits_config是递归扫描的入口，runtime 配置中 per-tenant overrides 里的limits_config.*子键都会按该分支下的规则校验。

递归匹配原理：从源码看检测算法

enumerateDeprecatesFields（checker.go）是核心的递归遍历函数，要点如下：

1. 逐键比对：遍历注解文件中的每个键，若用户配置中不存在该键则跳过（continue），避免误报；
2. 叶子判定：注解值为字符串或含_msg的 Map 时视为叶子，按上文"形态一/形态二"逻辑判定是否命中，命中即生成一条DeprecationNotes（携带完整路径与当前取值）并continue；
3. 向下递归：注解值为普通 Map 时继续下钻——用户配置对应值为 Map 则递归进入；为列表则对每个元素递归，路径以path.[i]形式追加下标；
4. 值类型归一：用户配置中的标量值统一转成字符串再比对，因此字符串、整数、布尔、浮点以及字符串列表都能正确参与取值匹配。

最终返回的DeprecationNotes带prefix（Deprecated或Removed）、ItemPath（如querier.engine.timeout）和ItemValues（用户当前配置的实际值），输出阶段再拼装为上文展示的提示文本。

Runtime 配置的 per-tenant 检查

Loki 的 runtime 配置文件通过overrides字段按租户（tenant）下发限额覆盖。检查器对 runtime 配置的处理（checker.go）分三步：

1. 从注解中取出limits_config分支作为待匹配规则集（getLimitsConfig）；
2. 从用户 runtime 配置中取出overrides字段（getOverrides）；
3. 对每个租户的覆盖内容，以上述limits_config规则集为模板递归扫描，并在命中路径前拼接overrides.<租户名>.前缀。

也就是说，普通配置里limits_config.ruler_remote_write_url命中的规则，在 runtime 配置中会以overrides.foo.ruler_remote_write_url、overrides.bar.ruler_remote_write_url等形态逐租户报告。测试夹具 test-fixtures/runtime-config.yaml 中"foo"与"bar"两个租户共享同一份覆盖内容（YAML 锚点&tenant_overrides/*tenant_overrides），正好用于验证该逻辑；checker_test.go 中的expectedRuntimeConfigDeletes断言了两个租户各自的命中路径。

实战输出示例

以 README 中的命令运行（基于 test-fixtures/config.yaml 与 test-fixtures/runtime-config.yaml），可得到类似下面的结果（省略部分条目）：

-- Deprecated Configs -- [*] index_gateway.ring.replication_factor = 2: Use global or per-tenant index_gateway_shard_size configuration from limits_config. [*] schema_config.configs.[1].store = aws: Use tsdb or boltdb-shipper instead. |- Deprecated values: aws, aws-dynamo, gcp, gcp-columnkey, bigtable, bigtable-hashed, cassandra, grpc -- Deleted Configs -- [-] legacy-read-mode = true: Legacy read SSD mode is deprecated and will be eventually removed. Use the new read and backend targets. [-] querier.engine.timeout = 1m: Use global or per-tenant query_timeout configuration from limits_config. [-] schema_config.configs.[0].row_shards = 16: The row_shards setting is removed. It configured a static query shard factor for removed legacy index types; TSDB resolves query sharding dynamically. -- Deleted Runtime Configs -- [-] overrides.foo.unordered_writes = true: This setting is removed. [-] overrides.foo.ruler_remote_write_url = push.123abc.net: This setting is removed. Use ruler_remote_write_config instead.

checker_test.go中的TestConfigDeprecatesAndDeletes与TestRuntimeConfigDeprecatesAndDeletes（checker_test.go）以ElementsMatch严格断言了上述夹具应命中的全部路径，可作为工具输出正确性的权威对照——例如普通配置侧共断言了 71 条删除项与 1 条废弃项，runtime 配置侧断言了两个租户共 28 条删除项。

当前已登记的废弃/删除项速查

注解文件是"活"的清单，以下摘录当前仓库登记的主要类别（完整内容以 deleted-config.yaml 与 deprecated-config.yaml 为准）：

已废弃（deprecated）：

• index_gateway.ring.replication_factor→ 改用全局或 per-tenant 的index_gateway_shard_size；
• kafka_config.address/kafka_config.client_id→ 改用reader_config或writer_config下的对应字段；
• server.grpc_server_stats_tracking_enabled→ 已无实际作用，未来版本移除。

已删除（deleted）——存储与索引迁移类：

• storage_config下bigtable、cassandra、boltdb、grpc_store、aws.dynamodb整体删除（对应后端支持已移除）；
• schema_config.configs的store/object_store不再支持aws、gcp、bigtable、cassandra、grpc等旧值；row_shards、chunks、index.tags一并删除（TSDB 索引时代已无意义）；
• boltdb_shipper/tsdb_shipper的shared_store、shared_store_key_prefix、use_boltdb_shipper_as_backup→ 由period_config中的object_store与path_prefix替代；
• common/ruler/storage_config下的 S3sse_encryption→ S3 加密统一为 SSE-S3，改配.sse字段。

已删除（deleted）——限额与 Ruler 类：

• limits_config.unordered_writes、enforce_metric_name、allow_deletes、ruler_evaluation_delay_duration、ruler_enable_wal_replay、enable_multi_variant_queries整项删除；
• limits_config.per_tenant_override_config/per_tenant_override_period→ 改用runtime_config.file/runtime_config.period；
• 一批limits_config.ruler_remote_write_*（url、timeout、headers、relabel_configs、queue_capacity、queue_min_shards、queue_max_shards、queue_max_samples_per_send、queue_batch_send_deadline、queue_min_backoff、queue_max_backoff、queue_retry_on_ratelimit、sigv4_config）→ 统一改用ruler_remote_write_config；
• querier.engine.timeout、chunk_store_config.max_look_back_period、compactor.deletion_mode→ 改用 limits_config 中对应的全局或 per-tenant 限额；
• frontend_worker.parallelism/match_max_concurrent→ 改用querier.max_concurrent；
• query_range.split_queries_by_interval/forward_headers_list、compactor.shared_store/shared_store_key_prefix、distributor.max_recv_msg_size/max_decompressed_size、ingester.max_transfer_retries、legacy-read-mode等。

升级前将你的生产配置跑一遍本工具，即可对照输出逐条迁移。

维护指南：如何新增一条废弃/删除配置

README 明确给出了为项目登记新规则的步骤：

1. 登记规则：废弃项写入 deprecated-config.yaml，删除项写入 deleted-config.yaml；
2. 同步测试夹具：在 test-fixtures/config.yaml（普通配置场景）和 test-fixtures/runtime-config.yaml（per-tenant 场景）中按需加入对应配置项——夹具文件里用# DELETED、# DEPRECATED注释标注预期分类，便于人工审阅；
3. 更新测试断言：在 checker/checker_test.go 的expectedConfigDeletes、expectedConfigDeprecates、expectedRuntimeConfigDeletes、expectedRuntimeConfigDeprecates四个列表中登记预期命中的完整路径，随后运行go test ./tools/deprecated-config-checker/...验证。

上述流程保证了"注解清单 → 测试夹具 → 断言"三者一致，任何一侧遗漏都会被测试拦截。从目录结构与默认路径可以看出，该工具在仓库内以独立子命令形态存在（main.go+checker子包），可被 CI、升级脚本或 pre-upgrade 检查流程直接调用；结合-no-color参数与退出码语义，从代码结构看它很适合作为升级前自动化体检的一环。

小结

deprecated-config-checker是 Loki 升级链路中一个轻量而实用的"配置体检器"：用两份集中维护的 YAML 注解文件描述"什么被废弃、什么被删除、为什么、换成什么"，以递归路径匹配覆盖嵌套配置与 per-tenant 覆盖场景，最终以彩色分组文本和退出码给出结论。对普通使用者而言，升级前运行 README 中的一行命令即可获得完整的配置迁移清单；对仓库维护者而言，遵循"改注解 → 改夹具 → 改测试"三步即可持续维护这份清单，让配置演进始终可追踪、可验证。

【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki