[/metrics] — applyTopNCondition精讲

# 一、开篇速览（核心结论）

结论一句话

TopN 触发条件 = isTopNHostCondition XOR isTopNMetricCondition 为 true。 也就是：两者必须有且仅有一个为 true，二者同时 true 或同时 false 都不会触发 TopN。

两大触发模式：

TopN Host 模式：主机维度排序条件：指标数量 = 1（且不含 %） 且 主机列表非空。
TopN Metric 模式：指标维度排序条件：指标数量 ≥ 1（可含 %） 且 主机数 ≤ 1（0 或 1），且主机名不得含 %。

易错点

单指标（无 %）+ 单主机（无 %） → 两个条件同时为 true → XOR 为 false → 不触发。
主机名带 % → Metric 条件直接判 false（即使主机数量为 0 或 1）。

# 二、源码与执行链

# 1、applyTopNCondition 方法

private void applyTopNCondition(ConditionBuilder conditionBuilder,
                                TopNConfig topNConfig,
                                List<String> metricNames,
                                List<String> hostnames) {
  if (topNConfig != null) {
    if (TopNCondition.isTopNHostCondition(metricNames, hostnames) ^
        TopNCondition.isTopNMetricCondition(metricNames, hostnames)) {
      conditionBuilder.topN(topNConfig.getTopN());
      conditionBuilder.isBottomN(topNConfig.getIsBottomN());
      Function.ReadFunction readFunction =
          Function.ReadFunction.getFunction(topNConfig.getTopNFunction());
      Function function = new Function(readFunction, null);
      conditionBuilder.topNFunction(function);
    } else {
      LOG.debug("Invalid Input for TopN query. Ignoring TopN Request.");
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

核心逻辑：

TopNCondition.isTopNHostCondition(metricNames, hostnames) ^
TopNCondition.isTopNMetricCondition(metricNames, hostnames)

1
2

只要 Host 条件 和 Metric 条件 有且仅有一个为 true，TopN 就生效。

# 2、TopN Host 条件

public static boolean isTopNHostCondition(List<String> metricNames, List<String> hostnames) {
  return (CollectionUtils.isNotEmpty(hostnames) &&
          metricNames.size() == 1 &&
          !metricNamesHaveWildcard(metricNames));
}

1
2
3
4
5

判定规则：

主机列表非空
指标数量 = 1
指标不含 %

👉 示例：

metricNames = ["cpu.usage"]
hostnames   = ["host1","host2"]

1
2

返回 true。

# 3、TopN Metric 条件

public static boolean isTopNMetricCondition(List<String> metricNames, List<String> hostnames) {
  return (CollectionUtils.isNotEmpty(metricNames) &&
          (hostnames == null || hostnames.size() <= 1) &&
          !hostNamesHaveWildcard(hostnames));
}

1
2
3
4
5

判定规则：

指标列表非空（可单个/多个，允许 %）
主机数 ≤ 1（可为空或 1 个）
主机名不能含 %

👉 示例：

metricNames = ["cpu.%","mem.free"]
hostnames   = ["host1"]

1
2

返回 true。

# 三、参数模型与判定规则

# 1、数据集合与符号

M：metricNames 集合
H：hostnames 集合
通配符：使用 %（如 host%、cpu.%）

# 2、XOR 真值表

isTopNHost	isTopNMetric	XOR	触发
false	false	0	否
true	false	1	是
false	true	1	是
true	true	0	否

# 四、参数案例具体解读（S01–S20）

# S01（M0, H0）不触发

metricNames = []
hostnames   = []

1
2

Host? = false
Metric? = false
最终结果：不触发

# S02（M0, H1）不触发

metricNames = []
hostnames   = ["h1"]

1
2

Host? = false
Metric? = false
最终结果：不触发

# S03（M0, H1%）不触发

metricNames = []
hostnames   = ["h%"]

1
2

Host? = false
Metric? = false
最终结果：不触发

# S04（M0, H+）不触发

metricNames = []
hostnames   = ["h1","h2"]

1
2

Host? = false
Metric? = false
最终结果：不触发

# S05（M0, H+%）不触发

metricNames = []
hostnames   = ["h%","n%"]

1
2

Host? = false
Metric? = false
最终结果：不触发

# S06（M1 无通配, H0）触发

metricNames = ["cpu.usage"]
hostnames   = []

1
2

Host? = false
Metric? = true
最终结果：触发（TopN Metric）

# S07（M1 无通配, H1 无通配）不触发

metricNames = ["cpu.usage"]
hostnames   = ["h1"]

1
2

Host? = true
Metric? = true
最终结果：不触发（冲突）

# S08（M1 无通配, H1%）触发

metricNames = ["cpu.usage"]
hostnames   = ["h%"]

1
2

Host? = true
Metric? = false
最终结果：触发（TopN Host）

# S09（M1 无通配, H+）触发

metricNames = ["cpu.usage"]
hostnames   = ["h1","h2","h3"]

1
2

Host? = true
Metric? = false
最终结果：触发（TopN Host）

# S10（M1 无通配, H+%）触发

metricNames = ["cpu.usage"]
hostnames   = ["h%","n%"]

1
2

Host? = true
Metric? = false
最终结果：触发（TopN Host）

# S11（M1 有通配, H0）触发

metricNames = ["cpu.%"]
hostnames   = []

1
2

Host? = false
Metric? = true
最终结果：触发（TopN Metric）

# S12（M1 有通配, H1 无通配）触发

metricNames = ["cpu.%"]
hostnames   = ["h1"]

1
2

Host? = false
Metric? = true
最终结果：触发（TopN Metric）

# S13（M1 有通配, H1%）不触发

metricNames = ["cpu.%"]
hostnames   = ["h%"]

1
2

Host? = false
Metric? = false
最终结果：不触发

# S14（M1 有通配, H+）不触发

metricNames = ["cpu.%"]
hostnames   = ["h1","h2"]

1
2

Host? = false
Metric? = false
最终结果：不触发

# S15（M1 有通配, H+%）不触发

metricNames = ["cpu.%"]
hostnames   = ["h%","n%"]

1
2

Host? = false
Metric? = false
最终结果：不触发

# S16（M+ 多指标, H0）触发

metricNames = ["cpu.usage","mem.free"]
hostnames   = []

1
2

Host? = false
Metric? = true
最终结果：触发（TopN Metric）

# S17（M+ 多指标, H1 无通配）触发

metricNames = ["cpu.usage","mem.free"]
hostnames   = ["h1"]

1
2

Host? = false
Metric? = true
最终结果：触发（TopN Metric）

# S18（M+ 多指标, H1%）不触发

metricNames = ["cpu.usage","mem.free"]
hostnames   = ["h%"]

1
2

Host? = false
Metric? = false
最终结果：不触发

# S19（M+ 多指标, H+）不触发

metricNames = ["cpu.usage","mem.free"]
hostnames   = ["h1","h2"]

1
2

Host? = false
Metric? = false
最终结果：不触发

# S20（M+ 多指标, H+%）不触发

metricNames = ["cpu.usage","mem.free"]
hostnames   = ["h%","n%"]

1
2

Host? = false
Metric? = false
最终结果：不触发

# 五、穷举结果总表

说明：M0/M1/M+ 分别代表 0/1/多指标；H0/H1/H+ 表示 0/1/多主机；

场景ID	指标(M)	主机(H)	isTopNHost	isTopNMetric	XOR 结果	触发模式
S01	M0	H0	false	false	false	不触发
S02	M0	H1	false	false	false	不触发
S03	M0	H1%	false	false	false	不触发
S04	M0	H+	false	false	false	不触发
S05	M0	H+%	false	false	false	不触发
S06	M1	H0	false	true	true	TopN Metric
S07	M1	H1	true	true	false	冲突（不触发）
S08	M1	H1%	true	false	true	TopN Host
S09	M1	H+	true	false	true	TopN Host
S10	M1	H+%	true	false	true	TopN Host
S11	M1%	H0	false	true	true	TopN Metric
S12	M1%	H1	false	true	true	TopN Metric
S13	M1%	H1%	false	false	false	不触发
S14	M1%	H+	false	false	false	不触发
S15	M1%	H+%	false	false	false	不触发
S16	M+	H0	false	true	true	TopN Metric
S17	M+	H1	false	true	true	TopN Metric
S18	M+	H1%	false	false	false	不触发
S19	M+	H+	false	false	false	不触发
S20	M+	H+%	false	false	false	不触发

# 六、触发模式速查与最佳实践

# 1、TopN Host 模式

触发条件：

指标数量 = 1（且不含 %）
主机列表非空

典型能触发的参数：

metricNames = ["cpu.usage"]
hostnames   = ["host1","host2","host3"]      # 多主机

1
2

metricNames = ["cpu.usage"]
hostnames   = ["host%"]                      # 主机名用通配符 %

1
2

推荐请求示例（GET）

/ws/v1/timeline/metrics?metricNames=cpu.usage&hostname=host%&topN=5&topNFunction=avg&isBottomN=false

# 2、TopN Metric 模式