콘텐츠로 이동

EdgeFlow 방식 테일 샘플링

EdgeFlow는 DataKit과 Dataway 사이에 배포되며, trace_id를 기준으로 트레이스의 Span을 집계한 뒤 EdgeFlow 로컬 DSL 규칙에 따라 보존 또는 폐기 여부를 결정합니다. DataKit의 Aggregator는 그룹화, 패키징 및 전송을 담당하며, 실제 샘플링 조건, 샘플링 비율 및 대기 시간은 EdgeFlow에 이미 적용된 규칙을 기준으로 합니다.

이 문서에서는 tracing 테일 샘플링을 구성하며, 예시에서는 오류 트레이스를 우선 보존하고 하트비트 및 404 트레이스를 폐기하며 나머지 트레이스는 10% 샘플링합니다. SDK 또는 수집 측에서 이미 폐기한 Span은 복구할 수 없습니다.

사전 요구 사항 및 설치 리소스

버전 요구 사항: DataKit 2.11 이상, EdgeFlow 1.0.1. 호스트 설치 패키지는 Linux AMD64용입니다. 이 문서에서는 EdgeFlow 로컬 rules validate, rules test, rules apply 명령을 통해 샘플링 규칙을 관리합니다.

설치 리소스 다운로드 주소
EdgeFlow 호스트 설치 패키지(Linux AMD64) 설치 패키지 다운로드
EdgeFlow 컨테이너 이미지 pubrepo.guance.com/guance/edgeflow:1.0.1

기존 Dataway 주소, 워크스페이스 토큰, 별도 관리 토큰 및 쓰기 가능한 상태 디렉터리를 준비합니다. DataKit이 EdgeFlow의 데이터 포트에 액세스할 수 있고 EdgeFlow가 기존 Dataway에 액세스할 수 있는지 확인합니다. 예시에서는 내부 HTTP 주소를 사용합니다. 호스트 설치 예시는 Linux/systemd를 사용합니다. Docker 설치에는 사용 가능한 Docker Engine과 영구 데이터 볼륨이 필요합니다. 먼저 DataKit 구성과 기존 규칙을 백업합니다.

작업 순서: 연결 방식 선택 → EdgeFlow 설치 → 로컬 DSL 규칙 적용 → DataKit 구성 → 샘플링 결과 검증. 호스트 설치와 Docker 설치 중 하나를 선택합니다.

연결 방식 선택

비교 항목 전체 프록시 모드 단일 샘플링 모드
[dataway].urls EdgeFlow를 가리킴 기존 Dataway 유지
[aggregator].endpoints 비어 있음, 일반 출력 경로 재사용 독립 EdgeFlow 노드를 가리킴
tracing EdgeFlow에서 샘플링한 후 Dataway로 전송 Aggregator가 EdgeFlow로 전송하고, 샘플링 후 Dataway로 전송
일반 로그, 메트릭 등 EdgeFlow를 통해 전달 기존 Dataway로 직접 전송
배포 하나의 연결 경로에 단일 인스턴스 사용 여러 독립 인스턴스를 사용할 수 있으며 trace별로 할당
장애 영향 해당 일반 출력 경로의 모든 데이터에 영향 주로 트레이스 샘플링에 영향, 다른 데이터는 기존 출력 경로 유지

이 문서에서는 tracing 테일 규칙만 추가합니다. 기존 집계, 라우팅 규칙 또는 전용 Sink의 처리 범위는 별도로 확인해야 합니다.

전체 프록시: DataKit → 단일 EdgeFlow 인스턴스 → 기존 Dataway

단일 샘플링: DataKit ── 일반 로그, 메트릭 ─────────→ 기존 Dataway
           └── Aggregator → EdgeFlow A/B ──→ 기존 Dataway

전체 프록시 모드에서는 단일 인스턴스를 사용합니다. 일반 요청에는 여러 trace가 포함될 수 있으므로 무작위 로드 밸런싱으로 요청을 여러 EdgeFlow 인스턴스에 분산해서는 안 됩니다.

단일 샘플링 다중 노드에서는 모든 DataKit이 개수와 순서가 동일한 endpoint 목록을 사용해야 하며, 각 주소는 하나의 고정 인스턴스에만 대응해야 합니다. 각 EdgeFlow 인스턴스는 독립 상태 디렉터리 또는 데이터 볼륨을 사용하고 동일한 로컬 DSL 규칙을 적용합니다. 무작위 로드 밸런싱으로 trace별 할당을 대체해서는 안 되며, 여러 노드가 상태 디렉터리를 공유하도록 해서도 안 됩니다.

endpoint 수나 순서를 변경하면 trace 소속이 변경되므로 전환과 전송 중 데이터 드레이닝을 일괄적으로 계획해야 합니다. 노드 간에 규칙이 자동 동기화되거나 기존 트레이스 상태가 자동으로 인계되지는 않습니다.

호스트 설치

다음 자리 표시자 값은 실제 값으로 바꿔야 합니다. <DATAWAY_HOST>는 기존 Dataway 호스트, <EDGEFLOW_HOST>는 EdgeFlow 호스트, <WORKSPACE_TOKEN>은 워크스페이스 토큰, <ADMIN_TOKEN>은 관리 자격 증명입니다. 예시 워크스페이스 이름은 demo, 데이터 포트는 9529, 관리 포트는 로컬에서만 액세스 가능한 9530입니다.

바이너리 및 디렉터리 설치

Linux AMD64 설치 패키지를 다운로드하고 압축을 푼 뒤 실제 버전을 확인합니다.

curl -fL 'https://static.guance.com/edgeflow/edgeflow-linux-amd64.tar.gz' -o edgeflow-linux-amd64.tar.gz
mkdir -p edgeflow-package
tar -xzf edgeflow-linux-amd64.tar.gz -C edgeflow-package
cd edgeflow-package
./edgeflow --version

다운로드 주소에는 버전 번호가 포함되어 있지 않으므로 설치 전에 바이너리 버전이 이 문서에서 사용하는 1.0.1과 일치하는지 확인합니다. 그런 다음 다음을 실행합니다.

sudo useradd --system --user-group --home-dir /var/lib/edgeflow --shell /usr/sbin/nologin edgeflow
sudo install -m 0755 ./edgeflow /usr/local/bin/edgeflow
sudo install -d -m 0755 /etc/edgeflow /etc/edgeflow/rules
sudo install -d -o edgeflow -g edgeflow -m 0750 /var/lib/edgeflow

사용자가 이미 존재하면 useradd를 건너뜁니다. 업그레이드 시 기존 구성과 상태 디렉터리를 유지합니다.

실행 구성 및 자격 증명

sudoedit /etc/edgeflow/edgeflow.toml을 사용하여 실행 구성을 생성합니다.

listen = "0.0.0.0:9529"
admin_listen = "127.0.0.1:9530"
upstream_url = "http://<DATAWAY_HOST>:9528"
admin_token_env = "EDGEFLOW_ADMIN_TOKEN"

[state]
mode = "memory_spill"
path = "/var/lib/edgeflow/edgeflow.state"
max_bytes = 10737418240

[workspaces.demo]
token_env = "EDGEFLOW_DEMO_TOKEN"

upstream_url은 기존 Dataway의 프로토콜과 포트를 유지하며, 쓰기 API 경로나 ?token=...을 추가하지 않고 EdgeFlow를 다시 가리켜서도 안 됩니다. 워크스페이스 토큰은 환경 변수를 통해 별도로 제공하며, 기존 Dataway가 허용하는 유효한 토큰이어야 합니다. 관리 토큰은 직접 생성한 무작위 문자열을 사용하고 워크스페이스 토큰과 분리하여 설정하며, 로컬 규칙 관리에 사용합니다.

demo는 EdgeFlow 내부의 워크스페이스 식별자이며 명령의 --workspace demo와 일치해야 합니다. 워크스페이스를 추가할 때는 해당 워크스페이스에 [workspaces.<名称>], 별도의 token_env 및 대응하는 환경 변수를 추가하며, 각 토큰은 하나의 워크스페이스에만 구성할 수 있습니다. 각 워크스페이스의 규칙은 별도로 적용해야 하며, 동일한 워크스페이스는 모든 노드에서 같은 식별자와 토큰을 사용합니다.

sudoedit /etc/edgeflow/edgeflow.env를 사용하여 자격 증명을 저장하며, 값에 특수 문자가 있으면 systemd 환경 파일 규칙에 따라 올바르게 인용합니다.

EDGEFLOW_ADMIN_TOKEN=<ADMIN_TOKEN>
EDGEFLOW_DEMO_TOKEN=<WORKSPACE_TOKEN>
sudo chmod 0644 /etc/edgeflow/edgeflow.toml
sudo chmod 0600 /etc/edgeflow/edgeflow.env

서비스 시작

/etc/systemd/system/edgeflow.service를 생성합니다.

[Unit]
Description=EdgeFlow tail sampling
Wants=network-online.target
After=network-online.target

[Service]
User=edgeflow
Group=edgeflow
StateDirectory=edgeflow
WorkingDirectory=/var/lib/edgeflow
EnvironmentFile=/etc/edgeflow/edgeflow.env
ExecStart=/usr/local/bin/edgeflow --config /etc/edgeflow/edgeflow.toml run
Restart=on-failure
TimeoutStopSec=180

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now edgeflow
sudo systemctl status edgeflow --no-pager
sudo journalctl -u edgeflow -n 100 --no-pager
curl -fsS http://127.0.0.1:9529/healthz

서비스가 정상인지 확인한 후 로컬 규칙 준비 및 적용을 계속 진행합니다. 상태 확인이 성공했다고 해서 샘플링이 이미 구성된 것은 아닙니다.

Docker 설치

Docker 호스트에 독립 디렉터리를 준비합니다.

mkdir -p edgeflow-docker/rules
cd edgeflow-docker

edgeflow.toml과 edgeflow.env를 생성하고, 내용은 실행 구성 및 자격 증명을 참조하며 state.path를 /app/data/edgeflow.state로 변경합니다. upstream_url은 컨테이너 네트워크에서 액세스할 수 있어야 하며, 관리 주소는 127.0.0.1:9530을 유지합니다. 규칙 파일은 현재 디렉터리의 rules/ 아래에 저장합니다. Docker 환경 파일은 KEY=value 형식으로 작성하고 값 바깥에 shell 따옴표를 추가하지 않습니다.

chmod 0644 edgeflow.toml
chmod 0600 edgeflow.env
chmod 0755 rules
docker volume create edgeflow-state
docker pull pubrepo.guance.com/guance/edgeflow:1.0.1
docker run -d --name edgeflow --restart unless-stopped --stop-timeout 180 \
  --env-file ./edgeflow.env \
  -p 9529:9529 \
  -v "$PWD/edgeflow.toml:/app/edgeflow.toml:ro" \
  -v "$PWD/rules:/app/local-rules:ro" \
  -v edgeflow-state:/app/data \
  pubrepo.guance.com/guance/edgeflow:1.0.1 run
docker logs --tail 100 edgeflow
curl -fsS http://127.0.0.1:9529/healthz

이미지는 비root 사용자로 실행됩니다. 새로 만든 명명된 볼륨은 이미지 내부의 데이터 디렉터리로 초기화됩니다. 기존 볼륨을 재사용할 때는 컨테이너 사용자에게 읽기/쓰기 권한이 있는지 확인합니다. 데이터 포트 9529만 노출하고, 로컬 규칙 CLI는 컨테이너 내에서 실행합니다.

호스트 설치와 Docker 설치 중 하나를 선택하며, 두 프로세스가 동일한 포트나 상태 디렉터리를 두고 경쟁하도록 해서는 안 됩니다. 다중 노드 단일 샘플링 배포에서는 각 노드가 독립 컨테이너, 데이터 볼륨 및 고정적으로 접근 가능한 주소를 사용하고 동일한 DSL 파일을 각각 적용합니다. 로컬 규칙 준비 및 적용을 계속 진행합니다.

로컬 규칙 준비 및 적용

edgeflow.toml은 실행 구성이고, 아래의 tracing.dsl은 실제 샘플링 규칙입니다. DSL 파일을 편집한 후에는 반드시 rules apply를 실행해야 하며, 파일을 저장하는 것만으로는 실행 중인 규칙이 업데이트되지 않습니다.

한 번의 rules apply는 지정된 워크스페이스의 전체 DSL 규칙을 대체하며, 규칙 하나를 추가하는 것이 아닙니다. 다음 예시는 아직 비즈니스 규칙을 구성하지 않은 워크스페이스에 사용하기 위한 것입니다. 이미 집계, 라우팅 또는 샘플링 규칙이 있는 경우 현재 전체 DSL을 먼저 백업하고, 유지해야 할 규칙을 동일한 파일에 병합한 뒤 검증 및 적용해야 하며, 이 문서의 예시로 바로 덮어쓸 수 없습니다.

규칙 예시

호스트에서는 /etc/edgeflow/rules/tracing.dsl로 저장하고, Docker 설치에서는 설치 디렉터리 아래의 rules/tracing.dsl로 저장합니다.

version 1;

schema tracing {
  field.trace_id: string;
  field.resource: string;
  field.duration: number;
  tag.status: string;
  tag.http_status_code: string;
}

tail "trace_sampling" on tracing {
  group by field.trace_id;
  idle 10s max_wait 1m decision_ttl 5m;

  keep when any(tag.status == "error");
  drop when any(field.resource in ["/health", "/healthz", "/ready", "/readyz", "/heartbeat"]);
  drop when any(tag.http_status_code == "404");
  sample 0.1 otherwise seed "edgeflow-tracing-v1";
}

규칙은 순서대로 판정되며, 처음 일치한 동작이 이미 집계된 전체 트레이스의 보존 여부를 결정합니다. 따라서 오류 트레이스가 하트비트나 404와 일치하더라도 우선 보존됩니다. 하트비트나 404를 무조건 삭제하려면 해당 drop을 오류 보존 규칙 앞에 배치합니다.

any(...)는 임의의 Span이 일치하면 된다는 의미이며, '엔트리 Span 일치'와 동일하지 않습니다. 예시는 DataKit에서 일반적인 필드 위치를 사용합니다. 운영 환경에 적용하기 전에 실제 데이터의 tag./field., 유형 및 값을 확인합니다. resource는 GET /health 또는 라우트 템플릿일 수 있으므로 목록을 조정해야 합니다. HTTP 상태 코드가 숫자 필드인 경우 스키마와 조건을 모두 수정해야 합니다.

선택적인 느린 트레이스 보존 규칙은 오류 보존 규칙 뒤, 폐기 규칙 앞에 배치합니다.

keep when any(field.duration > 1000000);

여기서 duration은 number로 선언되며, DataKit 표준 tracing의 마이크로초 값으로 비교하므로 1000000은 1초입니다. 이는 특정 Span이 1초를 초과함을 의미하며, 전체 트레이스의 시작부터 끝까지의 범위가 1초를 초과함을 의미하지 않습니다. Pipeline에서 단위를 변경한 경우 이에 맞게 함께 조정해야 합니다.

호스트에서 검증 및 적용

먼저 오프라인으로 검증하고 테스트 실행합니다. 기본 내장 샘플은 빠른 확인에만 사용하며, 비즈니스 규칙은 실제 비식별화 샘플로 별도 검증해야 합니다.

sudo chmod 0644 /etc/edgeflow/rules/tracing.dsl
edgeflow rules validate /etc/edgeflow/rules/tracing.dsl
edgeflow rules test /etc/edgeflow/rules/tracing.dsl --workspace demo --format json

다음 명령은 임시 systemd 유닛을 통해 기존 자격 증명 파일을 로드하여 EdgeFlow 호스트에서 로컬로 규칙을 적용하므로, 토큰을 명령줄에 기록하지 않습니다. 최초 적용 시 --if-match 0을 사용합니다.

sudo systemd-run --quiet --wait --pipe --collect \
  --property=EnvironmentFile=/etc/edgeflow/edgeflow.env \
  /usr/local/bin/edgeflow --config /etc/edgeflow/edgeflow.toml \
  rules apply /etc/edgeflow/rules/tracing.dsl --workspace demo --if-match 0 --format json

출력에서 ok: true를 확인하고 revision과 hash를 기록합니다. 기존 규칙 업데이트 시에는 계속 0을 사용하지 말고 업데이트 및 롤백을 참조합니다.

컨테이너 내에서 검증 및 적용

DSL 파일을 Docker 설치 디렉터리 아래의 rules/tracing.dsl로 저장합니다. 해당 디렉터리는 이미 컨테이너에 읽기 전용으로 마운트되어 있습니다. 호스트 파일을 편집한 후 컨테이너 내에서 검증 및 적용합니다.

chmod 0644 rules/tracing.dsl
docker exec edgeflow edgeflow rules validate /app/local-rules/tracing.dsl
docker exec edgeflow edgeflow rules test /app/local-rules/tracing.dsl --workspace demo --format json
docker exec edgeflow edgeflow --config /app/edgeflow.toml \
  rules apply /app/local-rules/tracing.dsl --workspace demo --if-match 0 --format json

컨테이너에는 --env-file을 통해 필요한 자격 증명이 이미 주입되어 있습니다. 최초 적용 후 업데이트 시에는 현재 revision을 사용하거나 --if-match를 생략합니다. 다중 노드에서는 위 단계를 각각 실행하고, 각 인스턴스가 동일한 파일을 적용하여 동일한 hash를 반환하는지 확인합니다. 각 인스턴스의 revision은 독립적이므로 값이 같을 필요는 없습니다.

먼저 EdgeFlow 규칙을 적용한 다음 DataKit 데이터 출력 경로를 전환합니다. DSL 원본 파일과 이전 버전을 보관해야 하며, 컨테이너의 데이터 볼륨이 유일한 백업이 되어서는 안 됩니다.

DataKit Aggregator 구성

자세한 파라미터는 DataKit Aggregator를 참조합니다. 여기서는 데이터 수집 연결만 설정하며, EdgeFlow의 실제 비즈니스 샘플링 정책은 DataKit에서 관리하지 않습니다.

연결 구성 선택

호스트의 기본 메인 구성은 /usr/local/datakit/conf.d/datakit.conf입니다. 기존 구성 섹션에서 필드를 수정하고, 구성 섹션을 중복 추가하거나 전체 파일을 덮어쓰지 않습니다.

단일 샘플링 모드에서는 기존 [dataway].urls를 유지합니다.

[dataway]
urls = ["http://<DATAWAY_HOST>:9528?token=<WORKSPACE_TOKEN>"]

[aggregator]
endpoints = [
  "http://edgeflow-a:9529?token=<WORKSPACE_TOKEN>",
  "http://edgeflow-b:9529?token=<WORKSPACE_TOKEN>"
]
timeout = "30s"
max_raw_body_size = 1048576
use_local_config = true
local_config_dir = "/usr/local/datakit/conf.d/aggr"
local_metric_config_file = "aggr.toml"
local_tail_sampling_config_file = "tail-sampling.toml"

단일 노드에서는 endpoint를 하나만 유지하며, 호스트 이름을 실제 접근 가능한 주소로 교체합니다. Kubernetes의 DataKit도 Pod 네트워크에서 액세스할 수 있는 EdgeFlow 호스트 주소 또는 DNS를 사용해야 합니다. endpoint는 토큰이 포함된 서비스 루트 주소를 사용하고 API 경로를 추가하지 않습니다. 동일한 DataKit의 endpoint 목록에서 각 주소는 같은 워크스페이스 토큰을 사용해야 하며, 기존 [dataway].urls의 워크스페이스와 일치해야 합니다. 이 목록에서 서로 다른 워크스페이스를 혼용해서는 안 됩니다.

전체 프록시 모드에서는 동일한 Aggregator 파라미터를 사용하지만 다음 두 항목을 수정합니다.

[dataway]
urls = ["http://<EDGEFLOW_HOST>:9529?token=<WORKSPACE_TOKEN>"]

[aggregator]
endpoints = []

이 구성 조각은 차이점만 보여 줍니다. 이전 전체 예시의 다른 Aggregator 필드는 계속 유지해야 합니다. endpoint 목록이 비어 있으면 일반 Dataway 출력 경로를 재사용하며, 이 모드에서는 EdgeFlow 주소를 하나만 구성합니다.

연결용 규칙 파일 생성

호스트에서는 /usr/local/datakit/conf.d/aggr/을 생성하고, Kubernetes 환경에서는 작업 머신에서 다음 두 파일을 준비합니다.

aggr.toml은 빈 집계 규칙 세트를 유지합니다.

default_window = "15s"
action = ""
delete_rules_point = false
aggregate_rules = []

기존 집계 작업이 있는 경우 원본 파일을 바로 덮어쓰지 않습니다. 집계 작업도 Aggregator endpoint를 사용하기 때문입니다.

tail-sampling.toml은 tracing 그룹 전송을 활성화하는 데 사용합니다.

version = 1

[trace]
data_ttl = "1m"
group_key = "trace_id"

[[trace.sampling_pipeline]]
name = "send-traces-to-edgeflow"
type = "condition"
condition = '{ 1 = 1 }'
action = "keep"

여기서 keep은 EdgeFlow가 모든 트레이스를 보존한다는 의미가 아닙니다. 실제 보존 여부는 적용된 tracing.dsl에 의해 결정됩니다. 이 TOML의 version, data_ttl은 EdgeFlow의 규칙 revision, 대기 시간과 동일한 파라미터 세트가 아닙니다. 이번 작업 범위를 tracing만 처리하도록 유지하려면 [logging] 또는 [rum]을 추가하지 않습니다.

Kubernetes에서 DataKit 구성

다음은 DataKit이 datakit 네임스페이스에 있고 DaemonSet 이름이 datakit이라고 가정합니다. 먼저 기존 구성을 백업합니다. 배포 도구 또는 GitOps로 관리하는 경우 원본 구성 소스를 수정하고 배포해야 합니다. 이 섹션에서는 기존 DataKit만 구성하며 EdgeFlow는 설치하지 않습니다.

ConfigMap을 생성합니다.

kubectl -n datakit get daemonset datakit -o yaml > datakit-daemonset-backup.yaml
kubectl -n datakit create configmap edgeflow-tail-ingestion \
  --from-file=aggr.toml=./aggr.toml \
  --from-file=tail-sampling.toml=./tail-sampling.toml \
  --dry-run=client -o yaml | kubectl apply -f -

연결 주소 Secret을 생성합니다. 아래는 2개 노드 단일 샘플링 예시이며, datakit-edgeflow-endpoints.yaml로 저장한 후 kubectl apply -f datakit-edgeflow-endpoints.yaml을 실행합니다.

apiVersion: v1
kind: Secret
metadata:
  name: datakit-edgeflow-endpoints
  namespace: datakit
type: Opaque
stringData:
  endpoints: "http://<EDGEFLOW_A_HOST>:9529?token=<WORKSPACE_TOKEN>,http://<EDGEFLOW_B_HOST>:9529?token=<WORKSPACE_TOKEN>"

다음 조각을 DataKit 컨테이너의 기존 env, volumeMounts에 병합하고, 기존 ENV_DATAWAY를 유지하며 같은 이름의 변수는 하나만 유지합니다.

env:
  - name: ENV_AGGREGATOR_ENDPOINTS
    valueFrom:
      secretKeyRef:
        name: datakit-edgeflow-endpoints
        key: endpoints
  - name: ENV_AGGREGATOR_TIMEOUT
    value: "30s"
  - name: ENV_AGGREGATOR_MAX_RAW_BODY_SIZE
    value: "1048576"
  - name: ENV_AGGREGATOR_USE_LOCAL_CONFIG
    value: "true"
  - name: ENV_AGGREGATOR_LOCAL_CONFIG_DIR
    value: "/usr/local/datakit/conf.d/aggr"
  - name: ENV_AGGREGATOR_LOCAL_METRIC_CONFIG_FILE
    value: "aggr.toml"
  - name: ENV_AGGREGATOR_LOCAL_TAIL_SAMPLING_CONFIG_FILE
    value: "tail-sampling.toml"
volumeMounts:
  - name: edgeflow-tail-ingestion
    mountPath: /usr/local/datakit/conf.d/aggr/aggr.toml
    subPath: aggr.toml
    readOnly: true
  - name: edgeflow-tail-ingestion
    mountPath: /usr/local/datakit/conf.d/aggr/tail-sampling.toml
    subPath: tail-sampling.toml
    readOnly: true

spec.template.spec.volumes에 병합합니다.

volumes:
  - name: edgeflow-tail-ingestion
    configMap:
      name: edgeflow-tail-ingestion

전체 프록시 모드에서는 Secret의 주소를 단일 http://<EDGEFLOW_HOST>:9529?token=<WORKSPACE_TOKEN>로 변경하고 첫 번째 환경 변수 이름을 ENV_DATAWAY로 변경합니다. 중복된 ENV_DATAWAY와 기존 ENV_AGGREGATOR_ENDPOINTS를 제거하고, 메인 구성의 aggregator.endpoints = []도 확인합니다. 빈 환경 변수는 파일에 이미 있는 endpoint 목록을 지우지 않습니다.

DataKit 구성 활성화

호스트에서 실행합니다.

sudo systemctl restart datakit
sudo systemctl status datakit --no-pager

Kubernetes 환경에서 구성 소스를 업데이트한 후 실행합니다.

kubectl -n datakit rollout restart daemonset/datakit
kubectl -n datakit rollout status daemonset/datakit

DataKit 로컬 연결 구성이 변경된 후에는 DataKit을 재시작합니다. subPath 마운트도 새 파일을 읽으려면 Pod를 다시 생성해야 합니다. EdgeFlow 샘플링 정책만 수정하는 경우에는 EdgeFlow의 각 노드에 DSL을 적용하면 되며, 이를 위해 DataKit 구성을 수정할 필요는 없습니다.

규칙 파라미터 및 샘플링 기준

파라미터 예시 의미
version 1 DSL 구문 버전이며, 수정할 때마다 증가하는 규칙 버전이 아님
group by field.trace_id 전체 트레이스 기준으로 그룹화, service를 추가하면 서비스 간 트레이스가 분할 그룹화됨
idle 10s 해당 그룹이 마지막으로 데이터를 수신한 후의 유휴 시간, 0보다 커야 함
max_wait 1m 해당 그룹의 첫 데이터 수신부터의 최대 집계 시간, idle보다 커야 함
decision_ttl 5m 결정 보존 시간, 0보다 커야 함; 이 기간에 지연 도착한 동일 그룹 데이터는 기존 결정을 재사용
sample 0.1 일반 트레이스의 샘플링 비율, 범위는 [0,1]
seed edgeflow-tracing-v1 안정적 확률 샘플링의 시드, 동일 정책에서 일관되게 유지
revision 적용 후 반환됨 현재 인스턴스의 규칙 리비전 번호, 업데이트 시 동시성 검사에 사용

위 시간은 EdgeFlow가 데이터를 수신한 시간을 기준으로 계산합니다. idle 또는 max_wait 중 하나의 조건을 충족하면 집계를 종료하며, 모든 트레이스가 1분을 기다리는 것은 아닙니다. Span 보고 간격과 트레이스 지속 시간에 따라 조정하여 너무 일찍 종료되지 않도록 해야 합니다.

decision_ttl은 집계 시간을 연장하지 않습니다. 이미 폐기 결정이 있는 경우 보존 기간 내에 지연 도착한 오류 Span도 폐기 결정을 따릅니다. 보존 기간이 끝난 후 동일한 trace의 후속 데이터는 다시 그룹화되어 다른 결정이 내려질 수 있습니다.

오류 보존이 우선하며, 10%는 앞선 규칙에 일치하지 않은 트레이스에만 적용됩니다. 10,000개 트레이스 중 오류 규칙으로 500개를 보존하고, 이어지는 폐기 규칙으로 1,500개를 삭제한 뒤 나머지 8,000개에서 약 800개를 샘플링하면 총 보존율은 약 13%입니다. 서로 다른 trace_id를 기준으로 집계해야 하며, Span 수나 바이트 수로 대체할 수 없습니다.

모든 트레이스를 일률적으로 10% 샘플링하려면 tail 내부의 세 가지 조건 동작을 제거하고 sample ... otherwise만 유지합니다. 이 경우 오류 트레이스도 샘플링 대상에 포함됩니다. 동일 범주의 tail 규칙을 두 번째로 추가하지 않습니다.

샘플링 결과 검증

먼저 고유하고 검색 가능한 trace ID로 결정론적 규칙을 검증한 다음, 다수의 서로 다른 trace로 비율을 검증합니다.

시나리오 기본 예시 예상 결과
오류 Span 포함 이미 집계된 전체 트레이스 보존
오류 없음, 하트비트 경로 일치 폐기
오류 없음, 404 포함 폐기
오류와 404를 동시에 충족 오류 규칙 우선, 보존
다수의 일반 트레이스 trace 기준 집계, 약 10% 보존
동일 trace가 서로 다른 DataKit에서 발생 단일 샘플링 다중 노드에서 동일 인스턴스로 집계
일반 로그, 메트릭 선택한 모드에 따라 EdgeFlow를 통해 전달되거나 기존 Dataway로 직접 전송

집계 시간과 실제 전달 지연을 초과하여 대기한 후 플랫폼 결과를 확인합니다. HTTP 성공과 상태 확인은 규칙 수용 테스트를 대체할 수 없습니다. 운영 환경에 적용하기 전에 지연 도착 Span, 다운스트림 중단 및 복구를 검증하여 실패 시 폴백이 보존 비율을 변경하는지 확인해야 합니다.

업데이트, 롤백 및 운영

로컬 규칙 업데이트 및 롤백

  1. 해당 워크스페이스의 현재 전체 DSL 파일, 적용된 revision 및 hash를 저장합니다.
  2. 로컬 파일을 수정하고 validate 및 test를 실행합니다.
  3. 동일한 rules apply 명령을 사용하되, 최초의 --if-match 0을 해당 인스턴스의 현재 revision으로 교체합니다. 이 파라미터를 생략할 수도 있으며, CLI가 현재 버전을 읽고 동시 업데이트를 검사합니다.
  4. 성공 반환을 확인하고 각 노드에서 동일한 파일을 적용한 뒤 hash를 검사하고, 그다음 비즈니스 결과를 검증합니다.

동일한 내용을 반복 적용해도 revision은 증가하지 않습니다. 버전 충돌 시 먼저 기존 규칙을 확인하고, 다른 사람의 변경 사항을 바로 덮어쓰지 않습니다. 롤백은 저장한 이전 DSL을 사용하여 다시 적용하며, 구문 버전은 계속 version 1;을 유지합니다.

기존 그룹은 여전히 원래 규칙에 따라 처리를 완료할 수 있으므로, 업데이트 후에는 전송 중 데이터를 관찰해야 합니다. DSL 파일만 수정하거나 DataKit만 재시작해도 EdgeFlow 규칙은 업데이트되지 않습니다.

실행 구성 또는 자격 증명 수정

실행 구성, 자격 증명 및 샘플링 규칙은 적용 방식이 다릅니다.

수정 내용 적용 작업
EdgeFlow DSL 해당 워크스페이스의 각 노드에서 rules apply 실행, DataKit 재시작 불필요
호스트의 edgeflow.toml 또는 edgeflow.env 저장 후 sudo systemctl restart edgeflow 실행; 서비스 유닛 수정 시 먼저 sudo systemctl daemon-reload 실행
Docker의 edgeflow.toml 또는 edgeflow.env 기존 설치 디렉터리에서 기존 컨테이너를 중지 및 제거한 후 Docker 설치의 docker run 명령에 따라 다시 생성; 기존 데이터 볼륨은 유지 및 재사용
DataKit 메인 구성 또는 로컬 연결 파일 DataKit 구성 활성화에 따라 서비스를 재시작하거나 Pod를 다시 생성

Docker를 다시 생성하려면 먼저 docker stop edgeflow, docker rm edgeflow를 실행할 수 있으며, edgeflow-state 데이터 볼륨을 삭제해서는 안 됩니다. docker restart만 실행하면 수정된 --env-file이 로드되지 않습니다. 다시 생성하면 교체된 마운트 구성 파일도 다시 읽도록 보장할 수 있습니다. 재시작 후 서비스 상태와 샘플링 결과를 확인합니다. 새 워크스페이스는 시작에 성공한 후 규칙을 별도로 적용하고, 그다음 해당 워크스페이스의 데이터를 연결해야 합니다.

기존 데이터 채널 복구

전체 프록시 모드에서는 기존 [dataway].urls를 복구하고, 단일 샘플링 모드에서는 사용자 지정 Aggregator endpoints를 제거합니다. 두 모드 모두 이번에 활성화한 tracing 연결 구성을 취소해야 하며, 기존 구성을 복구한 후 DataKit을 재시작하고 일반 tracing 쓰기가 복구되었는지 확인합니다. use_local_config = false만 설정하지 마십시오. 이는 구성 소스를 전환합니다.

EdgeFlow를 중지하기 전에 드레이닝 시간을 확보하고 상태 디렉터리를 보존합니다. 이전 노드가 이미 수신한 데이터를 계속 전달할 수 있으므로 중복과 지연을 고려해야 합니다.

스토리지 및 장애 관찰

memory_spill은 메모리를 우선 사용하고 필요에 따라 데이터를 디스크에 임시 저장합니다. 정상 종료 시 상태를 저장합니다. 비정상 종료 시 이미 수신했지만 아직 전송하지 않은 데이터가 손실될 수 있으며, 영구 데이터 볼륨을 사용하더라도 이 위험을 없앨 수 없습니다. 이 문서의 호스트 및 Docker 예시는 모두 이 모드를 사용합니다. 비정상 종료 후에도 이미 수신한 데이터를 잃지 않아야 하는 비즈니스 요구 사항이 있다면 영구화 배포 방안을 별도로 확인해야 합니다.

state.max_bytes는 논리 상태 할당량이며 실제 디스크 사용량의 하드 상한이 아닙니다. 용량에는 백로그, 트레이스 상태, 스냅샷, 인덱스 및 여유 공간을 포함해야 합니다. 예를 들어 원시 본문이 2 MiB/s로 30분 동안 백로그되면 약 3.52 GiB가 필요합니다.

다음 제한은 edgeflow.toml의 [limits]에서 조정할 수 있으며,填写하지 않으면 기본값을 사용합니다. 표의 용량은 바이트 수이며 프로세스 전체 메모리의 상한으로 사용할 수 없습니다.

파라미터 기본값 제한 도달 시 영향
max_compressed_body 16777216(16 MiB) 제한을 초과한 요청은 거부됨
max_decompressed_body 67108864(64 MiB) 압축 해제 후 제한을 초과한 요청은 거부됨
max_active_groups 200000 이미 그룹 수 상한에 도달한 경우 새 그룹의 데이터는 그대로 보존되어 전달됨
max_group_bytes 8388608(8 MiB) 단일 트레이스의 누적 데이터가 제한을 초과하면 기존 데이터 및 이번 데이터를 보존; 이후 데이터는 결정 보존 기간 동안 계속 보존됨

DataKit의 max_raw_body_size = 1048576은 단일 전송 패킷의 크기를 제어하며, 전체 트레이스의 누적 크기를 제한하지 않습니다. 10% 샘플링 비율만으로 용량을 추정하지 마십시오. 결정 대기 중인 데이터도 여전히 공간을 차지하며, 위의 직접 보존 동작이 발생하면 보존 비율도 높아집니다.

프로세스 로그, 디스크, 메모리, /readyz 및 /metrics를 통해 상태를 관찰합니다. edgeflow_engine_fail_open_total의 reason="active_groups", reason="group_bytes"를 사용하여 용량 부족으로 인한 직접 보존을 관찰할 수 있습니다. DataKit의 aggr_tail_sampling_fallback_package_total, aggr_tail_sampling_fallback_point_total은 전송 실패 후 폴백 규모를 관찰하는 데 도움이 됩니다.

단일 샘플링 모드에서 일반 출력 경로로 폴백하면 샘플링되지 않은 데이터를 직접 전송하여 실제 보존량이 늘어날 수 있습니다. 일부 요청이 이미 성공한 경우 중복될 수도 있습니다. 전체 프록시 모드의 일반 출력 경로는 여전히 EdgeFlow이므로, 폴백으로 해당 노드 장애를 우회할 수 없습니다.

자주 묻는 질문

증상 확인 방향
규칙 수정 후 변경 없음 로컬 rules apply를 실행했는지, workspace가 올바른지, 각 노드가 동일한 파일을 적용했는지, 여전히 이전 그룹을 관찰 중인지 확인
적용 실패 DSL 구문, CLI 프로세스가 관리 토큰을 로드했는지, EdgeFlow가 실행 중인지, --if-match가 현재 revision인지 확인
하트비트 또는 404가 여전히 보존됨 오류 또는 느린 트레이스 보존 규칙이 먼저 일치했는지, 필드 위치, 유형, 리소스 이름이 예시와 일치하는지 확인
샘플링 비율이 10%가 아님 오류 우선 보존, 샘플 크기, trace와 Span 기준, 실패 폴백, 용량 초과 후 직접 보존 여부 확인
트레이스가 불완전함 SDK 헤드 샘플링, 수집 필터링, trace ID 전파, 노드 할당 및 지연 도착 Span 확인
데이터 측 인증 실패 endpoint의 토큰과 EdgeFlow 워크스페이스 토큰이 일치하는지 확인
413 또는 지속적인 5xx 패킷 크기 제한, 네트워크, 디스크 할당량, 메모리 및 다운스트림 상태 확인

관련 문서: 데이터 집계 및 테일 샘플링 개요, DataKit Aggregator, Dataway 테일 샘플링.

문서 평가

이 페이지가 도움이 되었나요?