rsdatakit

rsdatakit은 Linux 호스트와 Kubernetes 노드용 경량 수집기로, Rust로 작성되었으며 DataKit/Guance Point v2 형식으로 Dataway에 데이터를 전송합니다.

기능 개요¶

현재 Linux amd64와 arm64를 지원합니다. Windows, macOS, OTLP Metrics, OTLP Logs, eBPF, 합성 모니터링, 원격 구성 및 DataKit 플러그인 시스템은 지원하지 않습니다.

실행 요구 사항¶

• Linux 호스트에서 /proc와 /sys에 접근할 수 있어야 합니다. journald 수집에는 systemd journal 런타임도 필요합니다.
• 설치 스크립트로 rsdatakit 서비스를 관리하려면 systemd와 systemctl이 필요합니다.
• Kubernetes 수집기는 대상 노드에서 DaemonSet으로 실행되어야 하며 Pod 메타데이터, Kubelet Summary 및 호스트 컨테이너 로그 디렉터리를 읽을 수 있어야 합니다.
• 유효한 Dataway 주소와 token이 필요합니다. 구성 파일과 상태 디렉터리는 실행 사용자만 접근할 수 있어야 합니다.

설치¶

RSDATAKIT_DATAWAY_URL="https://openway.guance.com" \
RSDATAKIT_DATAWAY_TOKEN="<DATAWAY_TOKEN>" \
  sh -c "$(curl -fsSL https://static.guance.com/rsdatakit/install.sh)"

RSDATAKIT_DATAWAY_URL="https://openway.guance.com" \
RSDATAKIT_DATAWAY_TOKEN="<DATAWAY_TOKEN>" \
  sh -c "$(curl -fsSL https://static.guance.com/rsdatakit/install-<VERSION>.sh)"

RSDATAKIT_UPGRADE=1 \
  sh -c "$(curl -fsSL https://static.guance.com/rsdatakit/install.sh)"

systemctl is-active rsdatakit
systemctl status rsdatakit --no-pager
journalctl -u rsdatakit -n 30 --no-pager

wget https://static.guance.com/rsdatakit/rsdatakit.yaml

wget -O rsdatakit.yaml https://static.guance.com/rsdatakit/rsdatakit-<VERSION>.yaml

kubectl create namespace rsdatakit-system --dry-run=client -o yaml | kubectl apply -f -
kubectl -n rsdatakit-system create secret generic rsdatakit-secrets \
  --from-literal=dataway-url='https://openway.guance.com' \
  --from-literal=dataway-token='<DATAWAY_TOKEN>' \
  --from-literal=otlp-token='<OTLP_TOKEN>' \
  --dry-run=client -o yaml | kubectl apply -f -

kubectl apply -f rsdatakit.yaml

kubectl -n rsdatakit-system rollout status daemonset/rsdatakit
kubectl -n rsdatakit-system get pods -l app.kubernetes.io/name=rsdatakit

kubectl -n rsdatakit-system logs daemonset/rsdatakit --tail=100

구성¶

기본 구성 경로는 /etc/rsdatakit/rsdatakit.toml입니다. --config <path> 또는 RSDATAKIT_CONFIG로 다른 파일을 지정할 수 있습니다. 구성은 프로세스 시작 시에만 읽으므로 변경 후 다시 시작해야 합니다.

최소 구성:

[agent]
# Local state directory for the WAL and file-log read positions. Must be absolute.
state_dir = "/var/lib/rsdatakit"
# Optional standalone health-listener address. Leave empty to disable it.
health_addr = ""

[dataway]
# Workspace Dataway endpoint.
url = "https://openway.example.com"
# Workspace token.
token = "<DATAWAY_TOKEN>"
# Per-request Dataway timeout in seconds. Valid range: 1–60.
timeout_secs = 15
# Tags added to all reported data.
global_tags = { env = "prod" }
# Target index. Uses the workspace default index when empty.
storage_index = ""

[metrics]
# Host metrics collection interval in seconds. Valid range: 5–300.
interval_secs = 15
# Mount points whose capacity is collected. Maximum: 32. Each must be absolute.
mounts = ["/"]
# Also collect virtual interfaces such as veth, docker0, and cni.
enable_virtual_interfaces = false

[hostobject]
# HOST object reporting interval in seconds. Valid range: 60–3600.
interval_secs = 300

[wal]
# Local write-ahead log directory. Must be absolute.
dir = "/var/lib/rsdatakit/wal"
# Total WAL capacity in bytes. Valid range: 4 MiB–256 MiB; the oldest unsent data is evicted when full.
max_bytes = 268435456

agent.state_dir, logs.state_dir, wal.dir은 절대 경로여야 합니다. 기본 WAL 용량은 256 MiB입니다. 허용 가능한 Dataway 중단 시간과 로그/Trace 쓰기량에 맞게 wal.max_bytes를 조정하세요. 시작 시 RSDATAKIT_DATAWAY_URL과 RSDATAKIT_DATAWAY_TOKEN으로 구성의 주소와 token을 재정의할 수 있습니다. RSDATAKIT_HEALTH_ADDR은 별도 상태 검사 주소를 재정의합니다.

호스트 수집¶

호스트 메트릭과 HOST 객체는 기본 활성화되며 별도 enabled 스위치가 필요 없습니다.

호스트 메트릭 주기는 5~300초, HOST 객체 주기는 60~3600초입니다. CPU, 네트워크, 디스크 I/O 속도는 두 번의 연속 샘플이 필요하므로 시작 직후 첫 수집에는 속도 필드가 없을 수 있습니다.

메트릭¶

아래 표에는 rsdatakit이 현재 보고하는 필드만 나열합니다. 필드 이름은 DataKit의 동일 메트릭 집합과 호환되지만, DataKit 수집기의 모든 확장 필드를 구현하지는 않습니다.

cpu¶

mem¶

disk¶

[metrics].mounts의 마운트마다 Point 하나를 생성합니다.

diskio¶

I/O 카운터가 있는 Linux 블록 장치마다 Point 하나를 생성합니다.

net¶

필터 조건을 충족하고 이전 샘플이 있는 네트워크 인터페이스마다 Point 하나를 생성합니다.

system¶

객체¶

HOST¶

로그 수집¶

로그는 기본 비활성화됩니다. paths가 비어 있으면 파일을 수집하지 않습니다. 필요한 경로만 지정하고 지나치게 넓은 전역 glob은 피하세요.

[logs]
# Enables file-log collection.
enabled = true
# Absolute path globs for log files to collect.
paths = ["/var/log/my-service/*.log"]
# Log data source name.
source = "my-service"
# service tag added to logs.
service = "my-service"
# Reports first-level members of a top-level JSON object as log fields.
json_as_fields = false
# Maximum number of active files read simultaneously.
max_files = 32
# Interval for rediscovering matching files in seconds.
discovery_secs = 5
# copytruncate log-rotation detection strategy.
copytruncate_mode = "auto"
# Local directory that stores file read positions. Must be absolute.
state_dir = "/var/lib/rsdatakit"

# Effective only when built with the journald feature and libsystemd is available.
journald_enabled = false
# Collects only this systemd unit. Leave empty for all accessible journal entries.
journald_unit = "my-service.service"

[logs.multiline]
# Continuation pattern. Leave empty to report one log point per line.
continuation_regex = "^\\s+"
# Maximum wait time for continuation lines in milliseconds.
flush_timeout_ms = 1000
# Maximum bytes in a merged log entry.
max_bytes = 262144

로그 위치, journald cursor 및 WAL은 상태 디렉터리에 저장됩니다. 다시 시작하면 확인된 위치부터 파일을 이어 읽으며, WAL에 기록되거나 Dataway가 수신한 후에만 위치를 갱신합니다. 연속 행 패턴에 맞는 여러 줄은 하나의 로그로 병합됩니다.

json_as_fields는 기본 비활성화됩니다. 활성화하면 최상위가 객체인 JSON 로그의 첫 계층 멤버를 필드로 보고합니다: 문자열, 불리언, int64, 유한한 float64는 유형을 유지하며, 객체와 배열은 압축된 JSON 문자열로 인코딩됩니다. null과 지원 범위를 벗어난 숫자는 무시합니다. 파싱 실패, 최상위가 객체가 아님, 사용 가능한 필드가 없음 중 하나에 해당하면 원본 message를 유지합니다. JSON 필드는 같은 이름의 수집기 필드를 덮어씁니다. 필드 이름은 Point 규칙으로 정규화하고 256바이트로 제한합니다. Point 하나당 최대 1024개 필드를 유지합니다. time, source, date, storage_index는 각각 json_* 필드로 이름을 바꾸며 Point 시간, 로그 source 또는 저장 인덱스는 바꾸지 않습니다. 다음 설정으로도 활성화할 수 있습니다: RSDATAKIT_LOG_JSON_AS_FIELDS=true. 기존 json_extract와 RSDATAKIT_LOG_JSON_EXTRACT는 호환 별칭으로 유지됩니다.

journald_enabled = true는 systemd journal 읽기를 추가하며 파일 로그 수집 여부에는 영향을 주지 않습니다. 릴리스 패키지는 journald를 활성화합니다. 소스에서 직접 빌드할 때는 다음을 사용합니다:

cargo build --release --locked --features journald

로그 데이터¶

로그 measurement는 [logs].source입니다. Kubernetes 컨테이너 로그의 초기 source는 보통 kubernetes로 설정하며, 메타데이터가 일치하면 measurement를 컨테이너 이름으로 바꿉니다.

메타데이터를 사용할 수 있으면 Kubernetes 컨테이너 로그에 다음 tag도 추가합니다:

OpenTelemetry Trace¶

OTLP는 기본 비활성화됩니다. 활성화하면 OTLP Trace를 받아 tracing 분류로 전달합니다:

[otlp]
# Starts OTLP HTTP and gRPC receivers.
enabled = true
# OTLP/HTTP listen address.
http_addr = "127.0.0.1:4318"
# OTLP/gRPC listen address. Must differ from http_addr.
grpc_addr = "127.0.0.1:4317"
# Bearer token required for non-local listen addresses. It may be empty for local listening.
bearer_token = ""
# Maximum bytes per OTLP request.
max_request_bytes = 4194304
# Maximum number of concurrent OTLP requests.
max_concurrent_requests = 8
# Total memory budget in bytes for admitted OTLP requests.
max_inflight_bytes = 16777216

HTTP 또는 gRPC를 loopback이 아닌 주소에 바인딩하면 bearer_token을 설정해야 하며 클라이언트는 Authorization: Bearer <token>을 사용합니다. 현재 Trace만 수신하며 OTLP Metrics와 OTLP Logs 요청은 지원하지 않습니다. /health는 agent.health_addr로 별도 제공할 수 있습니다. OTLP가 비활성화되면 4317/4318에 바인딩하지 않습니다. 연결 유휴 제한은 30초입니다. HTTP header/body, gRPC 연결 시작, 요청 본문 수신/디코딩에는 각각 65초의 절대 기한이 적용됩니다. gRPC 메시지와 trailers 디코딩이 완료되면 본문 기한을 종료합니다. 이후 매핑, 큐 삽입 및 Dataway/WAL receipt 대기에는 전체 handler 시간 제한이 없으며 활성 요청은 연결 유휴 기한으로 중단되지 않습니다. gRPC 요청 본문이 수신 기한을 넘으면 DeadlineExceeded를 반환하고 전역 수용 예산을 해제합니다.

Trace 데이터¶

OTLP Span은 tracing 분류로 출력하며 measurement는 opentelemetry로 고정됩니다. 시간 필드 start와 duration은 마이크로초를 사용하며 Point 타임스탬프는 Span 시작 시간(나노초)을 사용합니다.

일반적인 OTel Resource/Span 속성은 평면 필드로 변환됩니다. 예: db.system → db_system, db.operation.name → db_operation、http.request.method → http_method、 http.response.status_code → http_status_code、rpc.system → rpc_system、 messaging.system → messaging_system. 문자열, 불리언, 정수, 부동소수점은 유형을 유지하고 배열과 객체는 JSON으로 인코딩합니다. 속성 소스당 최대 256개 속성을 처리합니다. 의미 매핑 허용 목록 밖의 속성은 최상위 필드가 되지 않지만 message JSON에 유지됩니다.

의미 속성 필드¶

아래는 현재 허용 목록의 OTel 속성 매핑입니다. http_status_code를 제외한 필드는 입력 속성의 string, bool, int 또는 float 유형을 유지합니다. 배열과 key/value 객체는 JSON 문자열로 인코딩합니다.

Kubernetes 모드에서 Trace에도 컨테이너 로그와 같은 클러스터, Node, Pod, Container, workload 및 허용된 label tag를 추가할 수 있습니다. OTel Resource 식별 정보를 우선하고 누락된 항목만 로컬 Pod 캐시로 보완합니다.

Kubernetes 수집¶

[kubernetes].enabled = true로 Kubernetes 모드를 활성화합니다. DaemonSet은 로컬 Pod 메타데이터, Kubelet /stats/summary 및 호스트 /var/log/pods에서 데이터를 수집합니다:

[kubernetes]
# Enables Kubernetes collection.
enabled = true
# Reports Pod and container metrics.
metrics_enabled = true
# Reports Pod and container objects.
objects_enabled = true
# Kubernetes cluster name.
cluster_name = "default"
# Local Pod metadata refresh interval in seconds.
refresh_secs = 60
# Pod and container object reporting interval in seconds.
object_interval_secs = 300
# Allowlist of Pod labels added to reported data.
label_tags = ["app.kubernetes.io/name"]

metrics_enabled와 objects_enabled는 독립적으로 제어합니다. 메트릭은 기본 60초마다 수집하며 객체는 시작 즉시 보고한 뒤 기본 5분마다 보고합니다. label_tags는 태그 카디널리티를 제어하는 Pod label 허용 목록입니다.

rsdatakit은 HTTPS와 자동 마운트된 ServiceAccount bearer token으로 Kubelet에 접근하며 nodes/stats RBAC 권한으로 인가합니다. 노드 자체 서명 인증서와 Node IP SAN이 없는 클러스터를 지원하기 위해 Kubelet 연결의 서버 인증서는 검증하지 않습니다. Kubernetes API는 별도 클라이언트를 사용하고 ServiceAccount CA로 인증서를 엄격하게 검증합니다.

프로젝트 DaemonSet 예제는 /var/log/pods, /var/lib/docker/containers 및 /var/lib/rsdatakit도 마운트합니다. 컨테이너 로그는 노드 로컬 파일에서 읽으며 로그마다 Kubernetes API를 호출하지 않습니다. Pod 메타데이터는 공유 로컬 노드 캐시로 보완합니다.

메트릭¶

Kubelet Summary가 제공하지 않는 선택 필드는 생성하지 않습니다. CPU, 메모리, 파일 시스템 및 네트워크 누적값은 로컬 Kubelet /stats/summary에서 가져오며 request, limit, ready, restart 및 workload tag는 Pod API 메타데이터에서 가져옵니다.

kube_pod¶

로컬 Pod마다 Point 하나를 생성합니다.

docker_containers(Kubernetes 메트릭)¶

로컬 컨테이너마다 Point 하나를 생성합니다. 컨테이너 네트워크는 Pod 수준의 kube_pod가 보고하므로 여기에 네트워크 필드는 없습니다.

객체¶

객체는 DataKit 페이지와 호환되는 분류를 사용합니다. 객체 message는 현재 객체 필드의 JSON 스냅샷입니다. 이번 수집에서 Kubelet Summary를 사용할 수 있으면 동일한 Pod/컨테이너 리소스 필드도 포함합니다. 아래 표에 각 필드를 나열합니다.

kubelet_pod 객체¶

docker_containers 객체¶

Prometheus 수집¶

Prometheus 스크래핑은 Kubernetes 모드의 일부입니다. 독립 바이너리는 기본 비활성화, 프로젝트 DaemonSet 예제는 기본 활성화됩니다:

[kubernetes.prometheus]
# Enables local Prometheus target discovery and scraping.
enabled = true
# Scrape interval per target in seconds.
scrape_interval_secs = 30
# Timeout per scrape in seconds.
scrape_timeout_secs = 10
# Keeps the full exporter metric name as the field name.
keep_exist_metric_name = true
# Discovers Pods annotated with prometheus.io/scrape.
discover_pod_annotations = true
# Discovers Services annotated with prometheus.io/scrape.
discover_service_annotations = true
# Discovers Prometheus Operator PodMonitors.
discover_pod_monitors = true
# Discovers Prometheus Operator ServiceMonitors.
discover_service_monitors = true

자동 검색 외에도 신뢰할 수 있는 대상을 명시적으로 구성할 수 있습니다:

[[kubernetes.prometheus.instances]]
# Target source type.
role = "pod" # node | pod | service | endpoints
# Namespaces containing the targets.
namespaces = ["default"]
# Kubernetes label selector。
selector = "app=nginx"
# Scrape scheme.
scheme = "http"
# Numeric or named port.
port = "metrics"
# HTTP metrics path.
path = "/metrics"
# Measurement name. Derived automatically when empty.
measurement = ""
# Tags added to all metrics from this target.
tags = { team = "platform" }

지원하는 대상 소스:

• Pod/Service의 prometheus.io/scrape, port, scheme, path 등의 annotations;
• Prometheus Operator의 PodMonitor 및 ServiceMonitor;
• 신뢰할 수 있는 정적 구성의 node, pod, service, endpoints 인스턴스.

로컬 노드에 속함을 확인할 수 있는 대상만 스크래핑하여 각 DaemonSet 복제본이 전체 클러스터를 중복 수집하지 않도록 합니다. 수집한 measurement는 exporter 메트릭 이름 또는 정적 measurement 구성으로 결정되며, collector.up은 각 대상의 스크래핑 결과를 나타냅니다.

필요 없는 검색 기능의 discover_* 스위치를 끄세요. Service annotation과 ServiceMonitor가 비활성화되고 service/endpoints 명시적 인스턴스도 없으면 전역 Service 및 EndpointSlice 리소스를 구독하지 않습니다.

메트릭 변환 규칙¶

Prometheus exporter의 measurement와 field는 메트릭 이름에서 동적으로 생성되므로 고정 호스트 메트릭처럼 모두 나열할 수 없습니다:

스크래핑마다 수집기 상태 메트릭도 생성합니다:

collector¶

실행 및 검증¶

sudo RUST_LOG=rsdatakit=info rsdatakit --config /etc/rsdatakit/rsdatakit.toml

sudo systemctl restart rsdatakit
sudo systemctl status rsdatakit
sudo journalctl -u rsdatakit -f

kubectl -n rsdatakit-system rollout status daemonset/rsdatakit
kubectl -n rsdatakit-system get pods -l app=rsdatakit
kubectl -n rsdatakit-system logs daemonset/rsdatakit --tail=100

시작 로그에 rsdatakit started가 나타나면 중앙 화면에서 다음 데이터를 확인합니다:

별도 상태 주소를 설정하거나 OTLP HTTP를 활성화하면 상태를 확인할 수 있습니다. 예:

curl http://127.0.0.1:4319/health

degraded는 Dataway, WAL 또는 수집 모듈에 현재 장애가 있음을 뜻합니다. HTTP 503은 큐, WAL 또는 백그라운드 작업이 비정상 상태임을 뜻합니다.

참고 사항¶

• 로그와 Trace는 네트워크 오류, HTTP 5xx 또는 429에서 WAL에 쓰고 재시도하며 다른 4xx는 재시도하지 않습니다. 메트릭과 객체는 주기적 스냅샷이며 WAL에 쓰지 않습니다.
• 로그/Trace 쓰기량과 허용 Dataway 중단 시간에 맞게 wal.max_bytes를 조정하세요.
• Dataway token과 OTLP bearer token은 Secret 또는 접근이 제한된 구성 파일로 주입하고 저장소에 커밋하지 마세요.
• 높은 카디널리티를 피하려면 kubernetes.label_tags에 필요한 Pod label만 추가하세요.
• RUST_LOG=rsdatakit=debug는 많은 로그를 생성하므로 짧은 문제 해결 시에만 사용하세요.