Dataway 테일 샘플링¶

기능 소개¶

Dataway는 테일 샘플링 기능을 제공하며, 외부 인터페이스는 다음과 같습니다:

/v1/tail_sampling
/v1/tail_sampling_v2
/v1/tail_sampling_config

테일 샘플링은 먼저 Dataway 측에서 그룹별로 패킹된 데이터를 수신한 후, 샘플링 규칙에 따라 보존 또는 폐기를 결정하고, 최종적으로 보존된 데이터를 중앙에 기록합니다.

현재 지원되는 데이터 유형은 세 가지입니다:

tracing
logging
rum

기본 처리 흐름은 다음과 같습니다:

sequenceDiagram
autonumber

participant dk as Datakit/Client
participant dw as Dataway
participant ts as TailSamplingProcessor
participant kodo as Kodo

dk ->> dw: POST /v1/tail_sampling
alt config ready
    dw ->> ts: ingest packet
    ts ->> dw: kept packets
    dw ->> kodo: write tracing/logging/rum
else config not ready
    dw ->> dw: pending cache
    dw -->> dk: 412 Precondition Failed
    dk ->> dw: POST /v1/tail_sampling_config
    dw ->> ts: update config and drain pending
end

작업 모드¶

테일 샘플링과 집계는 동일한 모드 구성을 공유합니다:

standalone
proxy

standalone¶

standalone 모드에서 현재 Dataway는 테일 샘플링 데이터를 직접 처리합니다:

protobuf로 인코딩된 aggregate.DataPacket 수신
token + data_type을 기준으로 테일 샘플링 구성 조회
구성이 준비된 경우 TailSamplingProcessor에 직접 기록
주기적으로 만료된 그룹을 가져와 해당 데이터 유형 쓰기 인터페이스로 전송

현재 구현에서:

샘플링 윈도우 진행 주기는 1초
파생 메트릭 갱신 주기는 1분
전송 단계는 worker pool을 사용하여 비동기적으로 쓰기

proxy¶

proxy 모드에서 현재 Dataway는 로컬 테일 샘플링 상태를 유지하지 않습니다:

/v1/tail_sampling 및 /v1/tail_sampling_v2는 백엔드 노드로 전달됨
/v1/tail_sampling_config는 모든 백엔드 노드로 브로드캐스트됨

따라서 proxy 모드에서는:

aggregator_endpoint를 반드시 구성해야 함
클라이언트는 유효한 Guance-Pick-Key를携带해야 함
백엔드 노드가 실제 샘플링 및 상태 유지를 담당

Warning

Kubernetes 배포에서 프런트엔드 Dataway가 테일 샘플링 요청을 안정적으로 특정 백엔드 노드로 전달해야 하는 경우, aggregator_endpoint는 변경되지 않는 안정적인 백엔드 주소를 입력해야 합니다. 이 경우 백엔드 Dataway는 StatefulSet으로 배포하여 Pod 주소와 DNS 이름이 안정적으로 유지되도록 하고, 프런트엔드 Dataway가 고정 전달을 할 수 있도록 하는 것이 좋습니다.

로컬 구성¶

Dataway 로컬에는 별도의 테일 샘플링 YAML 구성 항목이 없습니다. 테일 샘플링은 집계와 동일한 모드 구성을 사용합니다:

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

환경 변수:

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

설명:

standalone: 현재 노드가 테일 샘플링 상태를 자체 유지함
proxy: 현재 노드는 전달 또는 브로드캐스트만 수행함

Kubernetes에서 프런트엔드 Dataway가 진입점 역할을 하고 백엔드 Dataway가 실제 테일 샘플링을 담당하는 경우, 백엔드 노드는 StatefulSet으로 배포하고 StatefulSet Pod의 안정적인 주소를 aggregator_endpoint에 작성하는 것이 더 적합합니다.

샘플링 구성 전달¶

테일 샘플링 규칙은 dataway.yaml에 작성하는 것이 아니라 인터페이스를 통해 전달됩니다:

POST /v1/tail_sampling_config

요청 본문은 JSON이며, 최상위 구조는 다음과 같습니다:

{
  "version": 1,
  "trace": {},
  "logging": {},
  "rum": {}
}

여기서:

trace는 tracing 테일 샘플링 구성에 해당
logging은 logging 테일 샘플링 구성에 해당
rum은 rum 테일 샘플링 구성에 해당

tracing 구성 예시¶

{
  "version": 1,
  "trace": {
    "version": 1,
    "data_ttl": "5m",
    "group_key": "trace_id",
    "pipelines": [
      {
        "name": "keep-all",
        "type": "probabilistic",
        "rate": 1
      }
    ],
    "builtin_metrics": [
      {
        "name": "trace_total_count",
        "enabled": true
      }
    ]
  }
}

설명:

trace.group_key는 현재 trace_id만 가능
trace.data_ttl이 비어 있으면 기본값 5m
pipelines는 condition과 probabilistic을 지원
condition은 action=keep/drop 사용
probabilistic은 rate=0~1 사용

logging 구성 예시¶

{
  "version": 1,
  "logging": {
    "version": 1,
    "data_ttl": "1m",
    "group_dimensions": [
      {
        "group_key": "service",
        "pipelines": [
          {
            "name": "keep-all",
            "type": "probabilistic",
            "rate": 1
          }
        ]
      }
    ]
  }
}

rum 구성 예시¶

{
  "version": 1,
  "rum": {
    "version": 1,
    "data_ttl": "1m",
    "group_dimensions": [
      {
        "group_key": "session_id",
        "pipelines": [
          {
            "name": "keep-all",
            "type": "probabilistic",
            "rate": 1
          }
        ]
      }
    ]
  }
}

Info

logging과 rum은 group_dimensions 구성을 사용하여 그룹화 차원을 설정합니다. data_ttl이 비어 있으면 기본값은 모두 1m입니다.

Warning

현재 구현에서는 구성 내용을 검증합니다. trace는 group_key=trace_id만 허용합니다. derived_metrics는 아직 지원되지 않으며, 구성 시 오류가 반환됩니다.

데이터 보고 인터페이스¶

테일 샘플링 데이터 인터페이스:

POST /v1/tail_sampling
POST /v1/tail_sampling_v2

설명:

두 인터페이스는 현재 동일한 처리 로직을 사용
standalone 모드에서 요청 본문은 protobuf로 인코딩된 aggregate.DataPacket이어야 함
proxy 모드에서 요청은 백엔드 노드로 전달됨

412 및 pending cache¶

standalone 모드에서 Dataway가 막 시작되어 해당 token + data_type의 샘플링 구성이 아직 전달되지 않은 경우:

Dataway는 먼저 이 데이터를 로컬 pending cache에 저장
그런 다음 412 Precondition Failed를 반환

현재 동작:

pending cache는 메모리 캐시
token + data_type별로 임시 저장
구성 전달 성공 후, 사용 가능한 데이터가 자동으로 TailSamplingProcessor로 drain됨
현재 기본 최대 100000개의 패킷을 캐시

규약 동작:

클라이언트는 412를 수신한 후 이 데이터가 Dataway에 의해 이미 수신된 것으로 간주
클라이언트는 /v1/tail_sampling_config를 계속 전송하기만 하면 됨
클라이언트는 이 데이터를 다시 전송할 필요 없음

예외 상황:

pending cache가 가득 찬 경우 Dataway는 503을 반환
이 경우 요청은 더 이상 수신된 것으로 간주할 수 없음

테일 샘플링 내장 메트릭¶

테일 샘플링 구성은 builtin_metrics를 지원합니다. 이러한 메트릭은 테일 샘플링 프로세서가 샘플링 과정에서 생성하고, 주기적으로 갱신될 때 중앙에 기록됩니다.

현재 내장 메트릭은 다음과 같습니다.

tracing¶

trace_total_count
trace_kept_count
trace_dropped_count
trace_error_count
span_total_count
trace_duration

여기서:

trace_duration은 지속 시간 분포 메트릭
나머지는 카운트 메트릭

logging¶

logging_total_count
logging_error_count
logging_kept_count
logging_dropped_count

rum¶

rum_total_count
rum_kept_count
rum_dropped_count

설명:

builtin_metrics가 비어 있으면 현재 기본적으로 해당 데이터 유형이 지원하는 모든 내장 메트릭이 활성화됨
이러한 메트릭은 테일 샘플링 처리 과정 자체에서 비롯된 것이며, Dataway 자체 실행 메트릭이 아님

Dataway 자동 보고 메트릭¶

샘플러 자체의 builtin_metrics 외에도 apis/metrics_special.go는 Dataway 자체 관측 메트릭 세트를 자동으로 유지 관리하여 테일 샘플링 API의 처리 상황을 설명합니다.

현재 테일 샘플링과 관련된 메트릭은 다음과 같습니다:

메트릭 이름	유형	태그	설명
`dataway_http_api_body_size_bytes_total`	Counter	`api`, `token`	테일 샘플링 인터페이스 요청 본문 누적 바이트 수
`dataway_http_tail_sampling_trace_total`	Counter	`token`	수신된 tracing 그룹 수
`dataway_http_tail_sampling_span_total`	Counter	`token`	수신된 tracing span 총 수
`dataway_http_tail_sampling_packet_send_total`	Counter	`token`, `data_type`, `result`	전송 결과 통계, `result`에는 `success`, `failure`, `drop` 포함

이러한 메트릭은:

1분마다 한 번씩 수집됨
dataway_aggregate 메트릭 포인트로 변환됨
Dataway 기본 토큰을 사용하여 /v1/write/metric으로 보고됨
보고 후 현재 누적 값이 재설정됨

이 메트릭 세트는 Dataway 자체가 테일 샘플링 트래픽을 처리하는 실행 상태를 반영하며, 샘플링 규칙 자체의 비즈니스 통계가 아닙니다.