一、前序章节回忆

我们在前面章节拆解了 Collector 的启动过程，并定位了控制器 TimelineWebServices。
本节聚焦 Collector 对外暴露的 REST 服务，搭建「接口全景图」。

二、接口请求梳理

2.1 接口总览表

分类	方法	路径	功能	主要参数
基础	GET	/ws/v1/timeline	服务探活	-
写入	POST	/ws/v1/timeline/metrics	写入普通指标	TimelineMetrics JSON
写入	POST	/ws/v1/timeline/metrics/aggregated	写入聚合指标	AggregationResult JSON
写入	POST	/ws/v1/timeline/containermetrics	写入容器指标	List<ContainerMetric>
查询	GET	/ws/v1/timeline/metrics	核心查询接口	metricNames, appId, hostname, startTime, endTime, precision, topN
查询	GET	/ws/v1/timeline/metrics/{instanceId}	按实例查询	instanceId PathParam
查询	GET	/ws/v1/timeline/metrics/summary	获取服务摘要	-
元数据	GET	/ws/v1/timeline/metrics/metadata	查询指标元数据	appId, metricName, includeAll
元数据	GET	/ws/v1/timeline/metrics/{instanceId}/metadata	实例元数据（实现未完整）	instanceId PathParam
拓扑	GET	/ws/v1/timeline/metrics/hosts	主机→应用映射	-
拓扑	GET	/ws/v1/timeline/metrics/instance	主机→应用→实例映射	appId, instanceId
拓扑	GET	/ws/v1/timeline/metrics/{instanceId}/instance	等价实例查询	instanceId PathParam
诊断	GET	/ws/v1/timeline/metrics/uuid	获取指标 UUID	metricName, appId, hostname, instanceId
存活	GET	/ws/v1/timeline/metrics/livenodes	当前活跃节点	-

2.2 基础类接口

枯燥提醒

不想看可以看后面的导入操作，我们把openapi.json文件放到了 github 和 gitee 中供大家自行体验

2.2.1 /ws/v1/timeline

• 方法：GET
• 功能：探活，确认 Collector 是否在线。
• 参数：无

2.3 写入类接口

2.3.1 /ws/v1/timeline/metrics

• 方法：POST
• 功能：写入普通时序指标。
• 参数：TimelineMetrics JSON

2.3.2 /ws/v1/timeline/metrics/aggregated

• 方法：POST
• 功能：写入主机级聚合指标。
• 参数：AggregationResult JSON

2.3.3 /ws/v1/timeline/containermetrics

• 方法：POST
• 功能：写入容器级指标。
• 参数：List<ContainerMetric> JSON

2.4 查询类接口

2.4.1 /ws/v1/timeline/metrics

• 方法：GET
• 功能：核心查询接口。
• 主要参数：metricNames, appId, hostname, startTime, endTime, precision, topN

2.4.2 /ws/v1/timeline/metrics/{instanceId}

• 方法：GET
• 功能：与 2.4.1 类似，支持 PathParam instanceId。

2.4.3 /ws/v1/timeline/metrics/summary

• 方法：GET
• 功能：返回 Collector 服务摘要。
• 参数：无

2.5 元数据接口

2.5.1 /ws/v1/timeline/metrics/metadata

• 方法：GET
• 功能：查询指标元数据。
• 主要参数：appId, metricName, includeAll

2.5.2 /ws/v1/timeline/metrics/{instanceId}/metadata

• 方法：GET
• 功能：实例元数据查询（当前实现未完整使用 PathParam）。

2.6 拓扑类接口

2.6.1 /ws/v1/timeline/metrics/hosts

• 方法：GET
• 功能：返回主机与应用映射。

2.6.2 /ws/v1/timeline/metrics/instance

• 方法：GET
• 功能：返回主机→应用→实例映射。
• 参数：appId, instanceId

2.6.3 /ws/v1/timeline/metrics/{instanceId}/instance

• 方法：GET
• 功能：与 2.6.2 类似，支持 PathParam instanceId。

2.7 诊断与存活接口

2.7.1 /ws/v1/timeline/metrics/uuid

• 方法：GET
• 功能：返回指标的 UUID。
• 主要参数：metricName, appId, hostname, instanceId

2.7.2 /ws/v1/timeline/metrics/livenodes

• 方法：GET
• 功能：返回当前活跃的 Collector 节点列表。

三、Apifox 导入与调试

我们将接口定义整理为 OpenAPI 规范文件，可以直接导入 Apifox：

👉 openapi.json 文件地址 (opens new window)

导入效果如下：

所有接口自动分组，支持调试和测试：