Dataway Metrics Aggregation¶

Features¶

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

This capability is primarily used to first receive aggregated metrics data on the Dataway side, then organize them by window and forward them to the center. Currently, two working modes are supported:

• standalone: The current Dataway directly receives aggregation packets, writes them to the local aggregation cache, and sends them to Kodo's /v1/write/metric after the window expires.
• proxy: The current Dataway does not perform local aggregation, only forwards the /v1/aggregate request 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 it to the local aggregate.Cache.

In the current implementation:

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

This mode is suitable for centralizing aggregation capability 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, but forwards the request to a backend node based on the request header Guance-Pick-Key:

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 description:

• aggregator_mode
• Optional values: standalone, proxy
• Defaults to proxy if empty.
• aggregator_endpoint
• List of backend nodes in proxy mode.
• May not be configured in standalone mode.

The corresponding environment variables are:

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

Configuration Examples¶

Single-machine 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 typically correspond to the stable DNS names of StatefulSet Pods.

API Description¶

Aggregation interface:

POST /v1/aggregate

Description:

• The authentication method is consistent with other Dataway write interfaces, still using standard token validation logic.
• In standalone mode, the request body needs to be protobuf-encoded aggregate.Batchs.
• In proxy mode, the client needs to additionally carry the request header Guance-Pick-Key.

Return behavior:

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

Built-in Metrics¶

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

Tag description:

• api: Interface path, currently /v1/aggregate for aggregation scenarios.
• token: The workspace token to which the current data belongs.

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

Automatic Metric Reporting¶

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

Current behavior:

• Collects current cumulative values every 1 minute.
• Automatically converts to the measurement dataway_aggregate.
• Reports to /v1/write/metric using Dataway's default workspace token.
• Resets the current round's cumulative count 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 converted as-is to metric point tags.

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

Use Cases¶

• Need to perform metric aggregation near the entry point before uniformly writing to the center.
• Need to separate aggregation traffic from actual write nodes.
• Need to observe aggregation request volume, request body size, and point count.