쿠버네티스 에이전트 옵션 설정

• 와탭 쿠버네티스 에이전트 배포 시 컨테이너 env 필드를 통해 설정할 수 있습니다.

• 컨테이너 내부 whatap.conf 파일을 수정해 설정할 수 있습니다.

• whatap.conf 파일 내 옵션이 컨테이너 env 필드에 설정된 옵션보다 높은 우선순위를 가집니다.

• whatap.conf 또는 컨테이너 env에 설정된 값이 없는 경우 기본값이 사용됩니다.

노트

컨테이너 내 애플리케이션 에이전트 옵션 설정

컨테이너 내 Java, Python, Node.js 등 애플리케이션의 모니터링을 위해 필요 설정을 whatap.conf 파일에 작성합니다. whatap.conf 파일을 통해 설정할 수 있는 옵션에 대한 자세한 내용은 다음 링크를 참조하세요.

• Java whatap.conf 설정하기

• Node.js whatap.conf 설정하기

• Python whatap.conf 설정하기

컨테이너별 옵션 설정

whatap-node-helper

• collect_volume_detail_enabled bool

  기본값 true

  노드 에이전트에서 모든 컨테이너에 대한 exec df 명령어를 이용해 컨테이너 볼륨 정보 조회를 활성화합니다. 노드에 실행 중인 모든 컨테이너의 스토리지 사용량 및 볼륨 정보를 수집하는 기능을 활성화합니다.

• use_cached_mount_info_enabled bool

  기본값 false

  마운트 정보(mountinfo) 캐시 사용 여부를 설정합니다. true로 설정하면 노드 헬퍼가 첫 디스크 스캔 시점의 mountinfo를 캐시해 재사용합니다. 이 경우 에이전트 기동 후 새로 마운트된 Pod PVC 볼륨이 영구적으로 누락될 수 있어 기본값은 false입니다. mountinfo 재읽기 비용은 수집 주기당 미미합니다.

• inject_container_id_to_apm_agent_enabled bool

  기본값 true

  와탭 APM 컨테이너에 exec를 이용한 container ID 주입을 활성화합니다. 와탭 APM으로 식별되는 컨테이너의 ID를 자동으로 추출합니다. 이를 APM 도구에 주입해 성능 모니터링 데이터와 컨테이너를 연결할 수 있습니다.

• debug bool

  기본값 false

  디버그 모드의 활성화 여부를 설정합니다. 디버그 모드 활성화 시 로그 레벨을 DEBUG로, 그렇지 않을 경우 INFO로 설정합니다.

• kube_config_path string

  기본값 ~/.kube/config

  Kubernetes 설정 파일 경로를 지정합니다. 미설정 시~/.kube/config 를 사용합니다.

• log_sys_out bool

  기본값 true

  로그 시스템 출력을 설정합니다. 옵션 값을 true로 설정 시 표준 출력(stdOut)과 파일에 동시에 로깅을 남깁니다. 변경 시 로깅 시스템에 즉시 반영됩니다.

• collect_kube_node_process_metric_target_list list

  기본값 "kubelet,containerd,dockerd,crio,coredns,kube-proxy,aws-k8s-agent,kube-apiserver,etcd,kube-controller,kube-scheduler"

  기본적으로 Kubernetes 관련 프로세스를 모니터링합니다. 사용자가 특정 프로세스 리스트를 수정하여 임의로 모니터링할 프로세스를 설정할 수 있습니다. 항목은 쉼표로만 구분하고 앞뒤에 공백을 넣지 않습니다. 공백이 있으면 이름이 일치하지 않아 count가 항상 0입니다.

  쿠버네티스 에이전트 1.9.32 버전부터 이 목록의 프로세스별 실행 개수를 kube_process_count 메트릭으로 함께 수집합니다. 개수를 셀 때는 목록의 이름이 /proc/PID/status 파일의 Name 값과 정확히 일치해야 합니다. Linux는 이 값을 최대 15바이트로 기록하므로 kube-controller-manager 프로세스는 kube-controller로 입력합니다.

  노트

  와탭에서 기본 설정된 모니터링 대상 프로세스 목록

  • kubelet

    각 노드에서 실행되는 컨트롤러로, 컨테이너의 상태를 지속적으로 모니터링하며 Kubernetes 마스터와 통신하여 워크로드가 올바르게 스케줄링되고 실행되도록 합니다. 컨테이너 상태 체크 및 노드 자원 관리를 담당합니다.

  • containerd

    컨테이너 실행을 위한 고성능 컨테이너 런타임입니다. 이미지 관리, 컨테이너 생성 및 실행, 네트워킹 등을 처리합니다.

  • dockerd

    Docker 컨테이너의 생성을 관리하는 주요 프로세스입니다. 이 프로세스는 컨테이너 이미지의 빌드, 배포, 실행, 네트워크 및 데이터 관리를 포함합니다.

  • crio

    Kubernetes를 위해 설계된 경량화된 컨테이너 런타임으로, CRI(Container Runtime Interface)를 구현하여 컨테이너 워크로드를 효율적으로 관리합니다.

  • coredns

    Kubernetes 클러스터 내부에서 DNS 서비스를 제공하는 프로세스로, 클러스터 내 서비스에 대한 네임 리졸루션을 처리합니다. 또한 서비스 디스커버리 및 로드 밸런싱 기능을 수행하며, 클러스터 내 서비스 간 통신을 원활하게 지원합니다.

  • aws-k8s-agent

    AWS 환경에서 Kubernetes 네트워크 인터페이스(VPC CNI)를 관리하는 에이전트입니다. 이 프로세스는 포드 간 통신을 위해 AWS 네트워크 자원(ENI)을 할당하고 해제하는 역할을 합니다. 문제가 발생하면 네트워크 연결 장애나 리소스 할당 오류가 발생할 수 있습니다.

  • kube-proxy

    Kubernetes 클러스터 내에서 네트워크 트래픽을 라우팅하는 프로세스입니다. 이 프로세스는 각 노드에서 실행되며, 서비스와 포드 간의 통신을 가능하게 합니다. 또한 iptables 혹은 IPVS와 같은 리눅스 네트워킹 기술을 사용하여 클러스터 내부의 요청을 올바른 포드로 전달합니다. 이를 통해 Kubernetes 클러스터 내의 서비스 디스커버리 및 로드 밸런싱을 지원합니다.

  • kube-apiserver

    Kubernetes API 서버로, 클러스터의 모든 요청을 처리하고 리소스 상태를 관리하는 중앙 구성 요소입니다. 인증, 권한 부여, 애드미션 컨트롤 등 클러스터의 전반적인 요청 처리를 담당합니다.

  • etcd

    Kubernetes 클러스터 상태 정보를 저장하는 분산 키-값 데이터베이스입니다. 클러스터의 상태 저장 및 복구에 중요한 역할을 합니다.

  • kube-controller

    여러 컨트롤러를 관리하고 실행하는 프로세스로, 클러스터 리소스의 상태를 유지하고 자동화 작업을 수행합니다. 노드 및 파드 상태 관리, 레플리케이션 유지 등 다양한 역할을 담당합니다.

  • kube-scheduler

    클러스터에서 파드를 적절한 노드에 배치하는 역할을 합니다. 파드의 요구 사항과 각 노드의 상태를 고려하여 최적의 노드를 선택합니다.

---

whatap-node-agent

• shutdown bool

  기본값 false

  수집 서버와 연결을 강제로 중단합니다. 통신 중지를 의미합니다.

• license string

  프로젝트에 발급된 라이센스를 사용해 에이전트를 식별합니다.

• whatap.server.host string

  기본값 13.124.11.223 혹은 13.209.172.35

  수집 서버의 IP를 설정합니다. delimiter의 경우 /:을 사용합니다.

• whatap.server.port number

  기본값 6600

  수집 서버의 데이터 수신 Port를 설정합니다.

• ONODE_NAME string

  기본값 NODE_NAME or NODE_IP 환경 변수값

  에이전트 노드 식별을 위한 이름을 설정합니다.

• tcp_connection_timeout number

  기본값 3000

  whatap-master-agent와 수집 서버 소켓 연결 시 타임아웃 시간을 설정합니다.

• tcp_so_timeout number

  기본값 60000

  소켓 연결 후 데이터 송수신 타임아웃 시간을 설정합니다.

• debug bool

  기본값 false

  디버그 모드의 활성화 여부를 설정합니다.

• gpuEnabled bool

  기본값 false

  GPU 모니터링의 활성화 여부를 설정합니다.

• collect_kube_node_process_metric_enabled bool

  기본값 true

  노드에서 Kubernetes 관련 프로세스 모니터링을 활성화하거나 비활성화하는 플래그입니다. true로 설정하면 모니터링이 활성화되고, false로 설정하면 모니터링이 비활성화됩니다. 모니터링 대상 프로세스는 whatap-node-helper의 collect_kube_node_process_metric_target_list 옵션으로 지정합니다.

• count_interval number

  기본값 5000

  메트릭스(kube_pod, container)를 수집 서버에 전송하는 주기를 설정합니다. 단위는 ms이며 1000~30000 범위에서 1000 단위로 설정합니다. 노드 에이전트 1.9.29 버전부터 최소값이 5000에서 1000으로 바뀌었습니다.

  • 1000 단위가 아닌 값은 1000 단위로 내림합니다. 예를 들어 29999는 29000으로 적용합니다.

  • 1000 미만이거나 숫자가 아닌 값은 기본값 5000을, 30000을 넘는 값은 30000을 사용합니다.

  • 한 옵션만 줄이면 다른 단계의 주기가 병목이 됩니다. collect_interval과 같은 값으로 함께 설정하세요.

  노트

  해당 옵션은 화면상 데이터 갱신 주기에 영향을 줄 수 있습니다. 자세한 내용은 다음 메트릭스별 영향을 받는 화면 구성요소를 참고하세요.

• collect_interval number

  기본값 5000

  에이전트가 메트릭스(kube_pod, container)를 수집하는 주기를 설정합니다. 컨테이너 통계, 노드 프로세스 성능, 노드 CPU, 메모리, 디스크, 네트워크 지표 수집이 이 주기를 따릅니다. 단위와 설정 범위는 count_interval과 같습니다. 이 값을 5초보다 짧게 설정해도 apiserver에 전체 Pod 메타데이터를 조회하는 간격은 최소 5초를 유지합니다.

  노트

  해당 옵션은 화면상 데이터 갱신 주기에 영향을 줄 수 있습니다. 자세한 내용은 다음 메트릭스별 영향을 받는 화면 구성요소를 참고하세요.

• 1초 또는 2초 주기로 수집하기

  두 옵션을 같은 값으로 함께 설정하세요. 1초 주기는 둘 다 1000, 2초 주기는 둘 다 2000입니다.

  count_interval=1000
  collect_interval=1000

  설정을 다시 적용하면 다음 주기 경계부터 반영하며, 지난 주기를 몰아서 다시 실행하지 않습니다.

  주의

  1초와 2초는 에이전트가 요청하는 주기입니다. 원천 데이터를 읽는 시간과 캐시 갱신 속도에 따라 모든 지표가 매 주기 새 값으로 바뀌지는 않으며, 수집 서버의 저장 단위와 화면의 표시 해상도도 이 설정과 별개입니다. 주기를 줄이면 노드 에이전트의 CPU 사용량과 송신량이 늘어나므로 노드, 컨테이너 규모에 맞춰 CPU, throttling, 송신량을 먼저 확인한 뒤 적용하세요.

• collect_apiserver_metric_by_leader bool

  기본값 false

  해당 옵션이 활성화 된 경우 노드 에이전트는 메트릭 수집을 마스터 에이전트에 위임합니다. whatap-master-agent의 collect_apiserver_metric_by_leader 옵션 활성화 선행이 필요합니다. 메트릭 수집 위임을 통해 기존 whatap-node-agent가 발생시킨 apiserver 부하를 낮출 수 있습니다.

• kubelet_root_dir string

  기본값 /var/lib/kubelet

  kubelet 루트 디렉터리 경로를 설정합니다. 노드 에이전트는 이 경로를 기준으로 컨테이너 로그 경로의 심볼릭 링크를 해석합니다. Huawei Cloud Container Engine(CCE)과 같이 kubelet 루트 위치가 기본값과 다른 환경에서 사용합니다. 기본 경로와 다른 환경에서도 에이전트가 로그 파일을 조회할 수 있도록 설정하는 옵션입니다.

• container_log_path string

  기본값 없음

  컨테이너 로그 디렉터리 경로를 직접 지정합니다. 미설정 시 노드 에이전트는 kubelet_root_dir 기반의 기본 경로와 /var/log/pods 같은 표준 경로를 차례로 탐색합니다. CCE 환경처럼 로그 경로가 비표준이어서 자동 탐색이 어려울 경우에만 이 옵션으로 명시적으로 지정합니다.

  노트

  kubelet_root_dir과 container_log_path는 컨테이너 런타임이나 클라우드 사업자가 표준과 다른 로그 경로를 사용할 때만 설정합니다. 일반적인 EKS, GKE, AKS, 온프레미스 환경에서는 기본값으로 두어도 정상 동작합니다.

• collect_conntrack_enabled bool

  기본값 true

  노드 conntrack 사용 현황 수집의 활성화 여부를 설정합니다. 활성화 시 kube_node_perf 카테고리에 conntrack_count, conntrack_max, conntrack_pct 필드를 전송합니다. nf_conntrack 모듈이 로드되지 않은 노드는 필드를 전송하지 않습니다. 노드 에이전트 1.9.18 버전 이상에서 지원합니다.

• collect_pod_emptydir_enabled bool

  기본값 true

  emptyDir 볼륨 사용량 수집의 활성화 여부를 설정합니다. 활성화 시 노드 에이전트가 kubelet 볼륨 디렉터리를 60초 주기로 조회해 kube_pod_volume 카테고리로 전송합니다. false로 설정하면 기존 df 기반 수집 경로가 emptyDir 볼륨을 담당합니다. 노드 에이전트 1.9.22 버전 이상에서 지원합니다.

• pod_emptydir_max_files number

  기본값 20000

  emptyDir 볼륨 하나에서 조회할 최대 파일 수를 설정합니다. 상한에 걸린 볼륨은 truncated 필드를 1로 전송해 값이 실제보다 작다는 것을 표시합니다.

• pod_emptydir_max_volumes number

  기본값 300

  한 노드에서 조회할 최대 emptyDir 볼륨 수를 설정합니다.

• net_send_buffer_enabled bool

  기본값 true

  수집 서버와의 네트워크가 끊긴 구간에서 전송 큐를 초과한 데이터의 보관 및 재전송 여부를 설정합니다. 활성화 시 전송 큐가 가득 차면 데이터를 폐기하는 대신 보관 버퍼로 옮기고, 재연결 후 오래된 데이터부터 순서대로 전송합니다. 노드 에이전트 1.9.17 버전 이상에서 지원합니다.

• net_send_buffer_minutes number

  기본값 15

  보관 버퍼의 데이터 보관 시간을 설정합니다. 기본값의 단위는 분입니다. 보관 시간을 넘긴 데이터는 오래된 것부터 폐기합니다.

• net_send_buffer_max_mb number

  기본값 64

  보관 버퍼가 사용할 최대 메모리를 설정합니다. 기본값의 단위는 MB입니다. 상한을 넘기면 오래된 데이터부터 폐기하며, 이때 폐기된 데이터만 pack_dropped로 집계합니다.

---

whatap-control-plane-helper

• port string

  기본값 9496

  whatap-control-plane-helper의 웹 서버 포트를 설정합니다.

• cycle number

  기본값 5

  control-plane-helper가 지표를 스크래핑하는 주기를 설정합니다. 기본값의 단위는 s입니다.

• collect_control_plane_monitoring_enabled bool

  기본값 false

  control-plane-monitoring 기능의 활성화 여부를 설정합니다.

• kube_config_path string

  기본값 ~.kube/config

  Kubernetes 설정 파일 경로를 지정합니다. 미설정 시 ~/.kube/config 를 사용합니다.

• kube_master_url string

  기본값 ~/.kube/config

  스크래핑을 위해 요청할 control-plane 의 url을 설정합니다. 미설정 시 ~/.kube/config 를 사용합니다.

• debug bool

  기본값 false

  whatap-control-plane-helper의 디버깅(로깅)의 활성화 여부를 설정합니다.

• kube_client_tls_verify bool

  기본값 true

  옵션값을 false로 설정하면 TLS 인증을 강제하지 않고, 인증 절차를 생략할 수 있습니다.

---

whatap-master-agent

• shutdown bool

  기본값 false

  수집 서버와 연결을 강제로 중단합니다. 통신 중지를 의미합니다.

• license string

  프로젝트에 발급된 라이센스를 사용해 에이전트를 식별합니다.

• whatap.server.host string

  기본값 13.124.11.223 혹은 13.209.172.35

  수집 서버의 IP를 설정합니다. delimiter의 경우 /:을 사용합니다.

• whatap.server.port number

  기본값 6600

  수집 서버의 데이터 수신 Port를 설정합니다.

• tcp_connection_timeout number

  기본값 3000

  whatap-master-agent와 수집 서버 소켓 연결 시 타임아웃 시간을 설정합니다.

• tcp_so_timeout number

  기본값 60000

  whatap-master-agent와 수집 서버 소켓 통신 시 타임아웃 시간을 설정합니다.

• debug bool

  기본값 false

  whatap-master-agent에서 DEBUG 레벨 로깅 활성화 여부를 설정합니다.

• collect_apiserver_metric_by_leader bool

  기본값 false

  whatap-master-agent가 스크래퍼의 리더로 동작 활성화 여부를 설정합니다. 활성화 시 whatap-master-agent 단독으로 apiserver에 메트릭을 요청합니다.

• collect_control_plane_monitoring_enabled bool

  기본값 false

  컨트롤 플레인 모니터링 기능의 활성화 여부를 설정합니다.

• master_to_control_plane_connection_timeout number

  기본값 5000

  whatap-master-agent가 whatap-control-plane-helper와 통신 시 connection timeout이 발생할 때까지의 시간을 설정합니다. 기본값의 단위는 ms입니다.

• master_to_control_plane_read_timeout number

  기본값 20000

  whatap-master-agent가 whatap-control-plane-helper와 통신 시 read timeout이 발생할 때까지의 시간을 설정합니다. 기본값의 단위는 ms입니다.

• control_plane_debug bool

  기본값 false

  컨트롤 플레인 모니터링에 대한 whatap-master-agent에서의 모든 디버그 로그 기능의 활성화 여부를 설정합니다.

• store_k8s_object_manifest_enabled bool

  기본값 true

  오브젝트 매니페스트 수집 기능의 활성화 여부를 설정합니다. 활성화 시 하루에 한번 클러스터 오브젝트들의 매니페스트 정보를 수집합니다.

• store_k8s_object_manifest_timezone string

  기본값 UTC

  오브젝트 매니페스트 수집을 위한 타임존을 설정합니다. 별도 설정이 없을 경우 기본값 UTC 기준 자정에 수집을 시작합니다.

  예, 한국 시간 기준으로 자정에 실행하고 싶을 경우 GMT+9 혹은 Asia/Seoul과 같이 타임존 설정

• store_k8s_object_manifest_max_fetch_limit number

  기본값 50

  한 번에 수집할 오브젝트의 조회 개수를 설정합니다. 별도 설정이 없을 경우 기본값 50 기준으로 1회 요청당 50개씩 요청합니다.

  예, 전체 Pod 개수가 90개인 클러스터에서 해당 옵션 30 설정 시 Pod 정보를 30개씩 3회 요청

• collect_network_policy_enabled bool

  기본값 true

  NetworkPolicy 오브젝트의 이벤트 기반 수집 활성화 여부를 설정합니다. 활성화 시 NetworkPolicy가 추가, 변경, 삭제될 때마다 kube_network_policy 카테고리로 스냅숏을 전송합니다. ClusterRole에 networkpolicies 조회 권한이 필요합니다.

• net_send_buffer_enabled bool

  기본값 true

  수집 서버와의 네트워크가 끊긴 구간에서 전송 큐를 초과한 데이터의 보관 및 재전송 여부를 설정합니다. 노드 에이전트와 마스터 에이전트에 공통으로 적용되는 옵션입니다. 마스터 에이전트 1.9.17 버전 이상에서 지원합니다.

• net_send_buffer_minutes number

  기본값 15

  보관 버퍼의 데이터 보관 시간을 설정합니다. 기본값의 단위는 분입니다.

• net_send_buffer_max_mb number

  기본값 64

  보관 버퍼가 사용할 최대 메모리를 설정합니다. 기본값의 단위는 MB입니다.

메트릭스별 영향을 받는 화면 구성요소

kube_pod

• 대시보드 > 컨테이너 맵

  다음 예시 이미지의 Pod 뷰 기준 데이터는 kube_pod 메트릭스 수집 주기 및 수집 서버 전송 주기에 영향을 받습니다.

  

• 워크로드 > Pod 목록

  다음 예시의 데이터는 kube_pod 메트릭스 수집 주기 및 수집 서버 전송 주기에 영향을 받습니다.

  

• 대시보드 > 퍼포먼스 요약

  kube_pod 메트릭스를 이용하는 에이전트 설치 노드에서 실행 중인 Pod 수 차트 갱신 주기에 영향을 받습니다.

container

• 대시보드 > 컨테이너 맵

  다음 예시의 컨테이너 뷰 기준 화면 데이터 갱신 주기는 container 메트릭스의 영향을 받습니다.

  

• 컨테이너 > 컨테이너 이미지

  다음 예시의 데이터는 container 메트릭스의 영향을 받습니다.

  

• 대시보드 > 퍼포먼스 요약

  container 메트릭스를 이용하는 다음 차트의 갱신 주기에 영향을 받습니다.

  • 에이전트 설치 노드에서 실행 중인 컨테이너 수

  • 에이전트 설치 노드 수

  • Total Container CPU Request

  • Total Container CPU Usage

  • Node CPU

  • Node Memory

  • Container CPU Usage by Request

  • Container CPU Usage by Node

  • Container Memory Working Set by Request

  • Container Memory Failure Count

  • Container CPU Throttling Time

  • Container Network Receive Byte

  • Container Network Transmit Byte

• 클러스터 > 노드 상세

  다음 예시의 노드 상세 화면에서 컨테이너 목록의 갱신 주기는 container 메트릭스의 영향을 받습니다.