Dataway 指标聚合¶

功能介绍¶

Dataway 提供聚合上传能力，对外接口为 /v1/aggregate。

该能力主要用于先在 Dataway 侧接收聚合后的指标数据，再按窗口整理并转发到中心。当前支持两种工作模式：

standalone：当前 Dataway 直接接收聚合包，写入本地聚合缓存，窗口到期后再发送到 Kodo 的 /v1/write/metric
proxy：当前 Dataway 不做本地聚合，只把 /v1/aggregate 请求转发到后端 Dataway 节点

基本处理流程如下：

sequenceDiagram
autonumber

participant dk as Datakit/Client
participant dw as Dataway
participant cache as Aggregate Cache
participant kodo as Kodo

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 ->> kodo: forward request
end

工作模式¶

standalone¶

standalone 模式下，Dataway 会将请求体解码为 aggregate.Batchs，然后写入本地 aggregate.Cache。

当前实现中：

聚合缓存窗口为 1 分钟
Dataway 每 1 秒检查一次过期窗口
窗口数据按工作空间 token 分组
每个 token 单独发送一次 /v1/write/metric

这种模式适合把聚合能力集中放在 Dataway 侧，由 Dataway 负责把最终指标写入中心。

proxy¶

proxy 模式下，Dataway 不处理聚合内容本身，而是根据请求头 Guance-Pick-Key 将请求转发到后端节点：

target = aggregator_endpoint[pick_key % len(aggregator_endpoint)]

因此在 proxy 模式下：

必须配置 aggregator_endpoint
客户端必须携带合法的 Guance-Pick-Key
当前节点只负责转发，不持有聚合窗口状态

这种模式适合在入口层做负载分发，把聚合状态固定落到后端节点。

Warning

在 Kubernetes 部署中，如果前置 Dataway 需要把 /v1/aggregate 请求稳定转发到固定后置节点，那么 aggregator_endpoint 必须填写稳定不变的后端地址。这里更适合使用 StatefulSet 部署后置 Dataway，这样每个 Pod 都有固定网络标识，便于前置 Dataway 按固定 endpoint 转发。

配置方式¶

聚合相关配置项如下：

aggregator_mode: standalone
aggregator_endpoint:
  - http://dataway-0:9528
  - http://dataway-1:9528

字段说明：

aggregator_mode
可选值：standalone、proxy
为空时默认按 proxy 处理
aggregator_endpoint
proxy 模式下的后端节点列表
standalone 模式下可不配置

环境变量与之对应：

DW_AGGREGATOR_MODE=standalone
DW_AGGREGATOR_ENDPOINTS=http://dataway-0:9528,http://dataway-1:9528

Warning

如果 aggregator_mode 为空，Dataway 会按 proxy 处理；但此时如果没有同时配置 aggregator_endpoint，聚合能力不会被初始化，对应的 /v1/aggregate 路由也不会生效。

配置示例¶

单机聚合：

aggregator_mode: standalone

入口转发到后端聚合节点：

aggregator_mode: proxy
aggregator_endpoint:
  - http://dataway-0.dataway:9528
  - http://dataway-1.dataway:9528

在 Kubernetes 中，上述地址通常对应 StatefulSet Pod 的稳定 DNS 名称。

接口说明¶

聚合接口：

POST /v1/aggregate

说明：

认证方式与 Dataway 其它写入接口一致，仍使用标准 token 校验逻辑
standalone 模式下，请求体需要是 aggregate.Batchs 的 protobuf 编码
proxy 模式下，客户端需要额外携带请求头 Guance-Pick-Key

返回行为：

standalone 模式下，数据写入本地聚合缓存成功后返回成功
proxy 模式下，当前节点将请求转发到目标后端，响应状态码以目标节点返回为准

内置指标¶

Dataway 会在处理聚合请求时，维护一组内置统计指标。当前与聚合直接相关的指标包括：

指标名	类型	标签	说明
`dataway_http_api_body_size_bytes_total`	Counter	`api`, `token`	`/v1/aggregate` 请求体累计字节数
`dataway_http_aggr_point_total`	Counter	`api`, `token`	聚合包中累计写入的 point 数量

标签说明：

api：接口路径，当前聚合场景一般为 /v1/aggregate
token：当前数据所属工作空间 token

这些指标用于观察聚合入口流量、写入规模以及不同工作空间的请求分布。

自动上报指标¶

apis/metrics_special.go 会定期把上述内置指标转换成指标点，并通过 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 数量