4. 观测标签体系设计原则：命名规范、层级结构、可扩展性与可查询性

在集群升级治理的模板制品库场景中，观测标签（Observability Labels）是连接基础设施状态与业务治理意图的核心元数据。一套设计不良的标签体系会导致查询效率低下、指标爆炸、治理规则难以维护。本节从四个维度定义标签体系的设计原则，确保标签在升级全生命周期中具备一致性、可推导性和自动化友好性。

4.1 标签命名规范：统一词根与约束规则

标签命名必须遵循反向域名或层级前缀模式，避免歧义与冲突。推荐采用 k8s-upgrade/ 作为制品库场景的全局命名空间前缀。

4.2 层级结构：从集群到模板的四层标签模型

标签层级结构决定了聚合粒度与下钻路径。在升级治理场景中，标签应分为四层：集群层 → 节点池层 → 工作负载层 → 模板制品层。每一层标签必须包含父层的关键标识，形成可追溯的标签链。

4.3 可扩展性：预留维度与版本化标签

标签体系必须支持增量扩展而不破坏现有查询。核心策略包括：预留扩展后缀、使用版本化标签、避免扁平化命名。

• 预留扩展后缀：每个层级标签保留 .ext 后缀空间，例如 k8s-upgrade/node.pool.ext.arch，用于未来新增硬件架构维度。
• 版本化标签：当标签语义发生重大变更时，使用 v2 后缀创建新标签，旧标签继续保留至少两个大版本周期。例如 k8s-upgrade/template.hash.v2。
• 避免扁平化命名：不要将所有属性塞入一个标签。例如 k8s-upgrade/template.info 包含多个 JSON 字段，应拆分为 template.hash、template.version、template.phase。

4.4 可查询性：索引友好与查询模式优化

标签的可查询性直接决定观测系统的响应速度与运维效率。设计时应遵循基数控制、前缀索引、查询模式预定义三条原则。

4.4.1 基数控制规则

标签的唯一值数量（基数）直接影响 Prometheus TSDB 的内存占用和查询性能。在升级治理场景中，必须对以下标签进行基数约束：

• 低基数标签（≤ 100 个唯一值）：k8s-upgrade/phase（升级阶段）、k8s-upgrade/status（成功/失败/进行中）、k8s-upgrade/strategy（滚动/蓝绿/金丝雀）。
• 中基数标签（≤ 10,000 个唯一值）：k8s-upgrade/cluster.id、k8s-upgrade/node.pool、k8s-upgrade/deploy.name。
• 高基数标签（需谨慎使用）：k8s-upgrade/template.hash（每个制品版本一个 hash，建议控制在 5,000 以内）。

4.4.2 前缀索引与查询加速

所有标签 key 以 k8s-upgrade/ 为固定前缀，这为 Loki 和 Prometheus 提供了前缀索引优化的可能。在 Loki 的日志查询中，使用 {k8s-upgrade/} 作为流匹配前缀，可以快速定位到升级治理相关的所有日志流，避免扫描全量日志。

# PromQL 示例：按模板版本聚合升级失败率
sum by (k8s-upgrade/template.hash) (
  rate(k8s_upgrade_failure_total{k8s-upgrade/cluster.id="prod-east"}[5m])
)
/
sum by (k8s-upgrade/template.hash) (
  rate(k8s_upgrade_total{k8s-upgrade/cluster.id="prod-east"}[5m])
)

# Loki LogQL 示例：查询特定模板的升级事件日志
{k8s-upgrade/cluster.id="prod-east", k8s-upgrade/template.hash="a1b2c3d4"}
| logfmt
| phase="rollback"

4.5 标签体系设计检查清单

在将标签体系落地到制品库之前，建议使用以下检查清单进行评审：