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 이름에 해당합니다.

API 설명¶

집계 API:

POST /v1/aggregate

설명:

인증 방식은 Dataway의 다른 쓰기 API와 동일하며, 표준 토큰 검증 로직을 사용합니다.
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`	집계 패킷에 누적하여 기록된 포인트 수

태그 설명:

api: API 경로, 현재 집계 시나리오에서는 일반적으로 /v1/aggregate
token: 현재 데이터가 속한 워크스페이스 토큰

이러한 메트릭은 집계 엔트리 트래픽, 쓰기 규모 및 워크스페이스별 요청 분포를 관찰하는 데 사용됩니다.

자동 보고 메트릭¶

apis/metrics_special.go는 위의 내장 메트릭을 주기적으로 메트릭 포인트로 변환하고 Dataway 자체를 통해 계속 보고합니다.

현재 동작은 다음과 같습니다.

1분마다 현재 누적 값을 수집합니다.
자동으로 메저먼트 dataway_aggregate로 변환합니다.
Dataway 기본 워크스페이스 토큰을 사용하여 /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 등의 유형은 현재 구현에서 보고 포인트로 변환되지 않습니다.

사용 사례¶

엔트리 근처에서 메트릭을 먼저 집계한 후, 통합하여 센터에 써야 하는 경우
집계 트래픽과 실제 쓰기 노드를 분리해야 하는 경우
집계 요청량, 요청 본문 크기 및 포인트 수를 관찰해야 하는 경우