[/metrics] — 验证写入逻辑规则

# 一、实验目标与背景本章聚焦：写入行为验证

目的：基于三组对照实验，验证 相同时间戳是否覆盖、新增时间戳是否追加、以及 多对象数组是否等价支持，并用查询结果闭环校验。

适用场景

自定义指标联调：判定“补点/纠错/回灌”的生效方式
大规模上报压测：确认写入与查询一致性
看板对齐：避免前端误解为“脏读/丢点”

# 二、实验一：追加写入 —— 新时间戳应追加

# 1、操作步骤

替换 metrics，去掉最早的 2384，新增 1758095682884:77：

"metrics": {
"1758095682484": 8,
"1758095682584": 9,
"1758095682684": 99,
"1758095682784": 10,
"1758095682884": 77
}

1
2
3
4
5
6
7

发起请求（APIFOX 执行）：

# 2、查询与结果对比

执行查询接口：

返回体关键片段（对比追加前后）：

// 追加前
"metrics": {
"1758095682384": 7.0,
"1758095682484": 8.0,
"1758095682584": 9.0,
"1758095682684": 99.0,
"1758095682784": 10.0
}

// 追加后
"metrics": {
"1758095682384": 7.0,
"1758095682484": 8.0,
"1758095682584": 9.0,
"1758095682684": 99.0,
"1758095682784": 10.0,
"1758095682884": 77.0
}

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

结论：新增时间戳被追加，历史点位保留。

# 三、实验二：覆盖写入 —— 相同时间戳应覆盖

# 1、操作步骤

将已有时间戳的值全部替换，并新增 1758095682984:9999：

"metrics": {
"1758095682384": 1,
"1758095682484": 1,
"1758095682584": 1,
"1758095682684": 2,
"1758095682784": 4,
"1758095682884": 3,
"1758095682984": 9999
}

1
2
3
4
5
6
7
8
9

执行请求与查询（已完成）：

# 2、查询返回（关键片段）

"metrics": {
"1758095682384": 1.0,
"1758095682484": 1.0,
"1758095682584": 1.0,
"1758095682684": 2.0,
"1758095682784": 4.0,
"1758095682884": 3.0,
"1758095682984": 9999.0
}

1
2
3
4
5
6
7
8
9

结论：相同时间戳的值被覆盖；新增时间戳正常追加。

# 四、实验三：数组类写入 —— 多对象拆分亦可

# 1、操作步骤

把一次请求拆分为两个对象（同一 metricname/appid/hostname）：

{
  "metrics": [
    {
      "hostname": "dev1",
      "metrics": {
        "1758095682384": 1
      },
      "starttime": 1758095682484,
      "appid": "amssmoketestfake",
      "metricname": "ttbigdata.test"
    },
    {
      "hostname": "dev1",
      "metrics": {
        "1758095682484": 2323
      },
      "starttime": 1758095682484,
      "appid": "amssmoketestfake",
      "metricname": "ttbigdata.test"
    }
  ]
}

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

执行结果：

# 2、现象与结论

与“单对象、多个点”的写法效果等价；
拆分更利于“补点/错点更正”的发布策略（按批次提交）。

# 五、三类写入方式一览（结论速查）

场景	请求特征	查询表现	规则归纳
追加写入	新增未出现的时间戳点	原有点位保留，新增点追加	新时间戳 → 追加
覆盖写入	修改已存在时间戳对应的值	对应时间戳的值被覆盖，新点仍追加	相同时间戳 → 覆盖
数组类写入	多对象拆分（同指标/同主机/同 appId）	与合并写法一致，便于“补点/分批”	写法等价，按需选择

# 六、易错与实战建议

注意

1）时间戳单位=毫秒；
2）新指标写入到 METRICS_METADATA_UUID 存在可见性延迟（JVM 缓存 + 聚合），耐心等待数分钟；
3）hostname/appId/metricname 必须与查询条件一致，否则“写入成功但查不到”；
4）批量校验时，务必设置合理的 时间窗口 覆盖到你的点位。

实战建议

补点/回灌：优先使用“拆分对象”的数组写法，降低一次请求体积，便于失败重试；
幂等校验：同一时间戳多次上报，最后一次的值为准；
压测策略：先小批量验证“覆盖/追加”规则，再扩大点位与并发。

# 七、复现清单（可直接照搬）

1）准备初始 5 个点； 2）执行“追加写入”，新增 2884:77，查询应多 1 个点； 3）执行“覆盖写入”，替换已有值并新增 2984:9999，查询应“旧值变化 + 新点追加”； 4）执行“数组类写入”，两对象提交，查询应与合并写法一致。

备注：本章截图与 JSON 片段

均来自同一组实验环境（dev1/amssmoketestfake/ttbigdata.test），便于你在本地快速复现对照。

#Ambari #Ambari-Metrics #TimelineService #Collector #Controller #Metadata

← [/metrics] — 普通指标写入方法 [/metrics] — 数据写入代码整体逻辑→