시스템 로그

시스템 컴포넌트 로그는 클러스터에서 발생하는 이벤트를 기록하며, 이는 디버깅에 아주 유용하다. 더 많거나 적은 세부 정보를 표시하도록 다양하게 로그를 설정할 수 있다. 로그는 컴포넌트 내에서 오류를 표시하는 것 처럼 간단하거나, 이벤트의 단계적 추적(예: 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 - 자세한 정도 (필수, 정수, 기본 값 0)
• err - 오류 문자열 (선택 사항, 문자열)
• msg - 메시지 (필수, 문자열)

현재 JSON 형식을 지원하는 컴포넌트 목록:

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

로그 상세 레벨(verbosity)

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

로그 위치

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

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

systemd를 사용하는 시스템에서는, kubelet과 컨테이너 런타임은 jounald에 기록한다. 그 외 시스템에서는, /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 플래그 사용 중단 알아보기
• 로깅 심각도(serverity) 규칙 알아보기
• 로그 쿼리 알아보기