Dataway 指标聚合¶
功能介绍¶
Dataway 提供聚合上传能力,对外接口为 /v1/aggregate。
该能力主要用于先在 Dataway 侧接收聚合后的指标数据,再按窗口整理并转发到中心。当前支持两种工作模式:
standalone:当前 Dataway 直接接收聚合包,写入本地聚合缓存,窗口到期后再发送到 Kodo 的/v1/write/metricproxy:当前 Dataway 不做本地聚合,只把/v1/aggregate请求转发到后端 Dataway 节点
基本处理流程如下:
sequenceDiagram
autonumber
participant dk as Datakit/Client
participant dw as Dataway
participant cache as 聚合窗口
participant backend as 后端 Dataway
participant kodo as 数据平台
dk ->> dw: POST /v1/aggregate
alt standalone
dw ->> cache: write aggregate batch
cache ->> dw: expired windows
dw ->> kodo: POST /v1/write/metric
else proxy
dw ->> dw: pick backend endpoint
dw ->> backend: forward request
end
工作模式¶
Standalone¶
standalone 模式下,Dataway 接收 DataKit 发送的聚合数据,按时间窗口汇总后上报。
处理方式如下:
- 聚合缓存窗口为 1 分钟
- Dataway 每 1 秒检查一次过期窗口
- 窗口数据按工作空间
token分组 - 每个
token单独发送一次/v1/write/metric
这种模式适合把聚合能力集中放在 Dataway 侧,由 Dataway 负责把最终指标写入中心。
Proxy¶
proxy 模式下,Dataway 不处理聚合内容本身,而是根据请求头 Guance-Pick-Key 将请求转发到后端节点:
相同分组在后端地址列表保持不变时会转发到同一节点。所有入口节点应使用数量和顺序一致的后端地址列表。调整列表前,应安排切换并等待在途数据处理完成。
因此在 proxy 模式下:
- 必须配置
aggregator_endpoint - 客户端必须携带合法的
Guance-Pick-Key - 当前节点只负责转发,不持有聚合窗口状态
这种模式适合在入口层做负载分发,把聚合状态固定落到后端节点。
Warning
在 Kubernetes 部署中,如果前置 Dataway 需要把 /v1/aggregate 请求稳定转发到固定后置节点,那么 aggregator_endpoint 必须填写稳定不变的后端地址。这里更适合使用 StatefulSet 部署后置 Dataway,这样每个 Pod 都有固定网络标识,便于前置 Dataway 按固定 endpoint 转发。
配置方式¶
聚合相关配置项如下:
字段说明:
aggregator_mode- 可选值:
standalone、proxy - 为空时默认按
proxy处理
- 可选值:
aggregator_endpointproxy模式下的后端节点列表standalone模式下可不配置
环境变量与之对应:
Warning
如果 aggregator_mode 为空,Dataway 会按 proxy 处理;但此时如果没有同时配置 aggregator_endpoint,聚合能力不会被初始化,对应的 /v1/aggregate 路由也不会生效。
配置示例¶
单机聚合:
入口转发到后端聚合节点:
aggregator_mode: proxy
aggregator_endpoint:
- http://dataway-0.dataway:9528
- http://dataway-1.dataway:9528
在 Kubernetes 中,上述地址通常对应 StatefulSet Pod 的稳定 DNS 名称。
接口说明¶
聚合接口:
说明:
- 认证方式与 Dataway 其它写入接口一致,仍使用标准 token 校验逻辑
- DataKit Aggregator 自动生成所需的 Protobuf 聚合数据包,无需手工构造请求体
proxy模式下,客户端需要额外携带请求头Guance-Pick-Key
返回行为:
standalone模式下,数据写入本地聚合缓存成功后返回成功proxy模式下,当前节点将请求转发到目标后端,响应状态码以目标节点返回为准
standalone 入窗前会校验字段名、算法和分位数选项:字段名不能为空或仅含空白;算法支持 sum、avg、count、min、max、histogram(含别名 merge_histogram)、stdev、quantiles、count_distinct、last 和 first,忽略算法名的大小写与首尾空白。缺失、未知或不受支持的算法(如 expo_histogram)返回 400。quantiles 必须提供非空 percentiles,且每个值都是 [0,1] 内的有限数值;缺失参数、NaN、Inf 或越界值同样返回 400。任何校验失败都会拒绝整包,不会部分入窗。
损坏或不完整的数据包同样返回 400,不会参与聚合。如果某个窗口计算异常,该窗口的数据会被丢弃,其他窗口继续处理。请检查 Dataway 错误日志,排查字段和算法配置;已丢弃的数据不会自动恢复。
内置指标¶
Dataway 会在处理聚合请求时,维护一组内置统计指标。当前与聚合直接相关的指标包括:
| 指标名 | 类型 | 标签 | 说明 |
|---|---|---|---|
dataway_http_api_body_size_bytes_total |
Counter | api, token |
/v1/aggregate 请求体累计字节数 |
dataway_http_aggr_point_total |
Counter | api, token |
聚合包中累计写入的 point 数量 |
标签说明:
api:接口路径,当前聚合场景一般为/v1/aggregatetoken:当前数据所属工作空间 token
这些指标用于观察聚合入口流量、写入规模以及不同工作空间的请求分布。
自动上报指标¶
Dataway 定期采集并上报上述内置指标,可在平台中查询聚合处理的流量和规模。
当前行为如下:
- 每 1 分钟采集一次当前累积值
- 自动转换成指标集
dataway_aggregate - 使用 Dataway 默认工作空间 token 上报到
/v1/write/metric - 上报成功后重置本轮累积计数
字段映射规则:
Counter指标:- 指标名直接作为字段名
Summary指标:- 生成
<metric>_sum - 生成
<metric>_count - 生成
<metric>_quantile_<quantile>
- 生成
标签映射规则:
- Prometheus 指标标签会原样转换为指标点标签
例如,dataway_http_api_body_size_bytes_total{api="/v1/aggregate",token="tkn_xxx"} 会被转换为一条 dataway_aggregate 指标点,其字段名为 dataway_http_api_body_size_bytes_total。
Info
自动上报支持 Counter 和 Summary;Gauge、Histogram 等类型暂不支持自动上报。
适用场景¶
- 需要在入口附近先做指标聚合,再统一写入中心
- 需要把聚合流量和实际写入节点分离
- 需要观测聚合请求量、请求体大小和 point 数量