Dataway Metrics Aggregation¶

Features¶

Dataway provides aggregation upload capability, with the external interface at /v1/aggregate.

This capability is mainly used to receive aggregated metric data on the Dataway side, then organize and forward it to the center based on windows. Currently, two working modes are supported:

• standalone: The current Dataway directly receives aggregate batches, writes them to the local aggregate cache, and sends them to Kodo's /v1/write/metric when the window expires.
• proxy: The current Dataway does not perform local aggregation, but only forwards /v1/aggregate requests to backend Dataway nodes.

The basic processing flow is as follows:

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

Working Modes¶

Standalone¶

In standalone mode, Dataway decodes the request body into aggregate.Batchs and writes them to the local aggregate.Cache.

In the current implementation:

• The aggregate cache window is 1 minute.
• Dataway checks for expired windows every 1 second.
• Window data is grouped by workspace token.
• Each token sends a separate /v1/write/metric request.

This mode is suitable for centralizing aggregation capabilities on the Dataway side, with Dataway responsible for writing the final metrics to the center.

Proxy¶

In proxy mode, Dataway does not process the aggregation content itself. Instead, it forwards the request to backend nodes based on the Guance-Pick-Key request header:

target = aggregator_endpoint[pick_key % len(aggregator_endpoint)]

Therefore, in proxy mode:

• aggregator_endpoint must be configured.
• The client must carry a valid Guance-Pick-Key.
• The current node is only responsible for forwarding and does not hold the aggregation window state.

This mode is suitable for load distribution at the entry layer, fixing the aggregation state to backend nodes.

Configuration¶

The aggregation-related configuration items are as follows:

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

Field descriptions:

• aggregator_mode
• Optional values: standalone, proxy
• When empty, it defaults to proxy.
• aggregator_endpoint
• List of backend nodes in proxy mode.
• Not required in standalone mode.

Corresponding environment variables:

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

Configuration Example¶

Single-node aggregation:

aggregator_mode: standalone

Entry forwarding to backend aggregation nodes:

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

In Kubernetes, the above addresses usually correspond to the stable DNS names of StatefulSet Pods.

API Description¶

Aggregation interface:

POST /v1/aggregate

Description:

• The authentication method is the same as other Dataway write interfaces, still using the standard token verification logic.
• In standalone mode, the request body must be the protobuf encoding of aggregate.Batchs.
• In proxy mode, the client must additionally carry the Guance-Pick-Key request header.

Response behavior:

• In standalone mode, returns success after data is successfully written to the local aggregate cache.
• In proxy mode, the current node forwards the request to the target backend, and the response status code is based on the return from the target node.

Built-in Metrics¶

Dataway maintains a set of built-in statistical metrics when processing aggregation requests. The metrics directly related to aggregation currently include:

Tag descriptions:

• api: Interface path, generally /v1/aggregate in the aggregation scenario.
• token: The workspace token to which the data belongs.

These metrics are used to observe aggregation entry traffic, write scale, and request distribution across different workspaces.

Auto-report Metrics¶

apis/metrics_special.go periodically converts the above built-in metrics into metric points and reports them through Dataway itself.

Current behavior:

• Collects the current cumulative values every 1 minute.
• Automatically converts to the metric set dataway_aggregate.
• Reports to /v1/write/metric using the default workspace token of Dataway.
• Resets the cumulative count for the current round after successful reporting.

Field mapping rules:

• Counter metrics:
• The metric name is directly used as the field name.
• Summary metrics:
• Generates <metric>_sum.
• Generates <metric>_count.
• Generates <metric>_quantile_<quantile>.

Tag mapping rules:

• Prometheus metric tags are directly converted to metric point tags.

For example, dataway_http_api_body_size_bytes_total{api="/v1/aggregate",token="tkn_xxx"} will be converted to a dataway_aggregate metric point with the field name dataway_http_api_body_size_bytes_total.

Use Cases¶

• Aggregating metrics near the entry and then writing them to the center in a unified manner.
• Separating aggregation traffic from actual write nodes.
• Observing the number of aggregation requests, request body sizes, and point counts.