시스템 로그

시스템 컴포넌트 로그는 클러스터에서 발생하는 이벤트를 기록하며, 이는 디버깅에 아주 유용하다. 더 많거나 적은 세부 정보를 표시하도록 로그 상세 레벨(verbosity)을 설정할 수 있다. 로그는 컴포넌트 내에서 오류를 표시하는 것처럼 간단하거나, 이벤트의 단계적 추적(예: HTTP 접근 로그, 파드의 상태 변경, 컨트롤러 작업 또는 스케줄러의 결정)을 표시하는 것처럼 세밀할 수 있다.

Klog

klog는 쿠버네티스의 로깅 라이브러리다. klog는 쿠버네티스 시스템 컴포넌트의 로그 메시지를 생성한다.

쿠버네티스는 각 컴포넌트의 로깅을 간소화하는 중에 있다. 다음 klog 커맨드라인 플래그는 쿠버네티스 v1.23부터 사용 중단(deprecated)되었으며 쿠버네티스 v1.26에서 제거되었다.

• --add-dir-header
• --alsologtostderr
• --log-backtrace-at
• --log-dir
• --log-file
• --log-file-max-size
• --logtostderr
• --one-output
• --skip-headers
• --skip-log-headers
• --stderrthreshold

출력은 출력 형식에 관계없이 항상 표준 에러(stderr)에 기록될 것이다. 출력 리다이렉션은 쿠버네티스 컴포넌트를 호출하는 컴포넌트가 담당할 것으로 기대된다. 이는 POSIX 셸 또는 systemd와 같은 도구일 수 있다.

distroless 컨테이너 또는 윈도우 시스템 서비스와 같은 몇몇 경우에서, 위의 옵션은 사용할 수 없다. 그런 경우 kube-log-runner 바이너리를 쿠버네티스 컴포넌트의 래퍼(wrapper)로 사용하여 출력을 리다이렉트할 수 있다. 미리 빌드된 바이너리가 몇몇 쿠버네티스 베이스 이미지에는 기존 이름인 /go-runner로, 서버 및 노드 릴리스 아카이브에는 kube-log-runner라는 이름으로 포함되어 있다.

다음 표는 각 kube-log-runner 실행법이 어떤 셸 리다이렉션에 해당되는지 보여준다.

Klog 출력

기존 klog 네이티브 형식의 예시는 다음과 같다.

I1025 00:15:15.525108       1 httplog.go:79] GET /api/v1/namespaces/kube-system/pods/metrics-server-v0.3.1-57c75779f-9p8wg: (1.512ms) 200 [pod_nanny/v0.0.0 (linux/amd64) kubernetes/$Format 10.56.1.19:51756]

메시지 문자열은 줄바꿈을 포함하고 있을 수도 있다.

I1025 00:15:15.525108       1 example.go:79] This is a message
which has a line break.

구조화된 로깅

구조화된 로깅은 로그 메시지에 일관된 구조를 도입하여 프로그램으로 정보를 추출할 수 있게 한다. 구조화된 로그는 더 적은 노력과 비용으로 저장하고 처리할 수 있다. 로그 메시지를 생성하는 코드가 기존의 구조화되지 않은 klog 출력을 사용할지, 구조화된 로깅을 사용할지 결정한다.

구조화된 로그 메시지의 기본 형식은 텍스트이며, 기존 klog와 하위 호환되는 형식이다.

<klog header> "<message>" <key1>="<value1>" <key2>="<value2>" ...

예시는 다음과 같다.

I1025 00:15:15.525108       1 controller_utils.go:116] "Pod status updated" pod="kube-system/kubedns" status="ready"

문자열은 따옴표로 감싸진다. 다른 값들은 %+v로 포맷팅되며, 이로 인해 데이터에 따라 로그 메시지가 다음 줄로 이어질 수 있다.

I1025 00:15:15.525108       1 example.go:116] "Example" data="This is text with a line break\nand \"quotation marks\"." someInt=1 someFloat=0.1 someStruct={StringField: First line,
second line.}

컨텍스츄얼 로깅(Contextual Logging)

컨텍스츄얼 로깅은 구조화된 로깅을 기반으로 한다. 컨텍스츄얼 로깅은 주로 개발자가 로깅 호출을 사용하는 방법에 관한 것이다. 해당 개념을 기반으로 하는 코드는 좀 더 유연하며, 컨텍스츄얼 로깅 KEP에 기술된 추가적인 사용 사례를 지원한다.

개발자가 자신의 컴포넌트에서 WithValues 또는 WithName과 같은 추가 함수를 사용하는 경우, 로그 항목에는 호출자가 함수로 전달하는 추가 정보가 포함된다.

쿠버네티스 1.37에서 이 기능은 ContextualLogging 기능 게이트로 제어되며 기본적으로 활성화되어 있다. 이 기능을 위한 인프라는 컴포넌트를 수정하지 않고 1.24에 추가되었다. component-base/logs/example 명령은 새 로깅 호출을 사용하는 방법과 컨텍스츄얼 로깅을 지원하는 컴포넌트가 어떻게 작동하는지 보여준다.

$ cd $GOPATH/src/k8s.io/kubernetes/staging/src/k8s.io/component-base/logs/example/cmd/
$ go run . --help
...
      --feature-gates mapStringBool  A set of key=value pairs that describe feature gates for alpha/experimental features. Options are:
                                     AllAlpha=true|false (ALPHA - default=false)
                                     AllBeta=true|false (BETA - default=false)
                                     ContextualLogging=true|false (BETA - default=true)
$ go run . --feature-gates ContextualLogging=true
...
I0222 15:13:31.645988  197901 example.go:54] "runtime" logger="example.myname" foo="bar" duration="1m0s"
I0222 15:13:31.646007  197901 example.go:55] "another runtime" logger="example" foo="bar" duration="1h0m0s" duration="1m0s"

runtime 메시지 및 duration="1m0s" 값을 로깅하는 기존 로깅 함수를 수정하지 않고도, 이 함수의 호출자에 의해 logger 키와 foo="bar"가 로그에 추가되었다.

컨텍스츄얼 로깅이 비활성화되어 있으면, WithValues 및 WithName은 아무 효과가 없으며, 로그 호출은 전역 klog 로거를 통과한다. 따라서 이 추가 정보는 더 이상 로그 출력에 포함되지 않는다.

$ go run . --feature-gates ContextualLogging=false
...
I0222 15:14:40.497333  198174 example.go:54] "runtime" duration="1m0s"
I0222 15:14:40.497346  198174 example.go:55] "another runtime" duration="1h0m0s" duration="1m0s"

JSON 로그 형식

--logging-format=json 플래그는 로그 형식을 klog 기본 형식에서 JSON 형식으로 변경한다. JSON 로그 형식 예시(보기 좋게 출력된 형태)는 다음과 같다.

{
   "ts": 1580306777.04728,
   "v": 4,
   "msg": "Pod status updated",
   "pod":{
      "name": "nginx-1",
      "namespace": "default"
   },
   "status": "ready"
}

특별한 의미가 있는 키는 다음과 같다.

• ts - Unix 시간의 타임스탬프 (필수, 부동 소수점)
• v - 로그 상세 레벨(정보 메시지에만 사용되며 오류 메시지에는 사용되지 않음, 정수)
• err - 오류 문자열 (선택 사항, 문자열)
• msg - 메시지 (필수, 문자열)

현재 JSON 형식을 지원하는 컴포넌트 목록은 다음과 같다.

• kube-controller-manager
• kube-apiserver
• kube-scheduler
• kubelet

로그 상세 레벨

-v 플래그로 로그 상세 레벨을 제어한다. 값을 늘리면 기록된 이벤트 수가 증가한다. 값을 줄이면 기록된 이벤트 수가 줄어든다. 로그 상세 레벨을 높이면 점점 덜 심각한 이벤트가 기록된다. 로그 상세 레벨을 0으로 설정하면 중요한 이벤트만 기록된다.

로그 위치

시스템 컴포넌트에는 컨테이너에서 실행되는 것과 컨테이너에서 실행되지 않는 두 가지 유형이 있다. 예를 들면 다음과 같다.

• 쿠버네티스 스케줄러와 kube-proxy는 컨테이너에서 실행된다.
• kubelet과 컨테이너 런타임은 컨테이너에서 실행되지 않는다.

systemd를 사용하는 시스템에서는, kubelet과 컨테이너 런타임은 journald에 기록한다. 그 외 시스템에서는, /var/log 디렉터리의 .log 파일에 기록한다. 컨테이너 내부의 시스템 컴포넌트들은 기본 로깅 메커니즘을 무시하고, 항상 /var/log 디렉터리의 .log 파일에 기록한다. 컨테이너 로그와 마찬가지로, /var/log 디렉터리의 시스템 컴포넌트 로그들은 로테이트해야 한다. kube-up.sh 스크립트로 생성된 쿠버네티스 클러스터에서는, logrotate 도구로 로그가 로테이트되도록 설정된다. logrotate 도구는 매일 또는 로그 크기가 100MB보다 커지면 로그를 로테이트한다.

로그 쿼리

로그 쿼리 기능은 리눅스와 윈도우 노드 모두에서 문제를 디버깅하는 데 도움이 된다. 쿠버네티스 v1.27에 도입된 이 기능을 사용하면 노드에서 실행 중인 서비스의 로그를 볼 수 있다. 이 기능을 사용하려면 대상 노드의 kubelet 구성 옵션인 enableSystemLogHandler와 enableSystemLogQuery를 모두 true로 설정해야 한다.

쿠버네티스 v1.36에서 이 기능은 스테이블로 승격되었고 NodeLogQuery 기능 게이트는 이제 true로 고정되어 기본적으로 활성화되므로, 로그 쿼리 기능을 활성화하거나 비활성화하는 데 필요한 옵션은 enableSystemLogHandler뿐이다.

enableSystemLogHandler의 기본값은 false이며, 실제로 디버깅 중인 경우가 아니라면 비활성화해 둘 것을 권장한다.

리눅스에서는 서비스 로그가 journald를 통해 제공된다고 가정한다. 윈도우에서는 서비스 로그가 애플리케이션 로그 공급자를 통해 제공된다고 가정한다. 두 운영 체제 모두에서 /var/log/ 내의 파일을 읽어 로그를 확인할 수도 있다.

노드(Node) 오브젝트와 상호작용할 권한이 있다면, 모든 노드 또는 일부 노드에서 이 기능을 사용해 볼 수 있다. 다음은 노드에서 kubelet 서비스 로그를 가져오는 예시이다.

# node-1.example이라는 이름의 노드에서 kubelet 로그 가져오기
kubectl get --raw "/api/v1/nodes/node-1.example/proxy/logs/?query=kubelet"

kubelet이 로그 가져오기를 허용하는 디렉터리에 파일이 있다면 그 파일도 가져올 수 있다. 예를 들어 리눅스 노드의 /var/log에서 로그를 가져올 수 있다.

kubectl get --raw "/api/v1/nodes/<insert-node-name-here>/proxy/logs/?query=/<insert-log-file-name-here>"

kubelet은 로그를 가져오기 위해 휴리스틱을 사용한다. 이는 특정 시스템 서비스가 journald와 같은 운영 체제의 네이티브 로거 또는 /var/log/의 로그 파일에 로그를 기록하는지 모르는 경우에 도움이 된다. 휴리스틱은 먼저 네이티브 로거를 확인하고, 사용할 수 없으면 /var/log/<servicename>이나 /var/log/<servicename>.log 또는 /var/log/<servicename>/<servicename>.log에서 첫 번째 로그를 가져오려고 시도한다.

사용할 수 있는 전체 옵션 목록은 다음과 같다.

더 복잡한 쿼리의 예시는 다음과 같다.

# node-1.example이라는 이름의 노드에서 "error"라는 단어가 포함된 kubelet 로그 가져오기
kubectl get --raw "/api/v1/nodes/node-1.example/proxy/logs/?query=kubelet&pattern=error"

다음 내용

• 쿠버네티스 로깅 아키텍처 알아보기
• 구조화된 로깅 알아보기
• 컨텍스츄얼 로깅 알아보기
• klog 플래그 사용 중단 알아보기
• 로깅 심각도(severity) 규칙 알아보기
• 로그 쿼리 알아보기