컨트롤 플레인 디버그 엔드포인트

원문 보기 위키 갱신 2026.10.03

컨트롤 플레인 디버그 엔드포인트 (Control Plane Debug Endpoints)

Linkerd 컨트롤 플레인 컴포넌트들이 노출하는 런타임 프로파일링 정보를 pprof를 통해 수집하고 go tool pprof로 분석하는 방법을 알려드려요.

출처: Linkerd Control Plane Debug Endpoints

본문

모든 컨트롤 플레인 컴포넌트는 Go의 pprof 패키지를 이용해 /debug/pprof 경로로 런타임 프로파일링 정보를 노출합니다. 이 엔드포인트는 기본적으로 비활성화되어 있지만, 프로파일링 데이터를 모으기 위해 활성화할 수 있어요.

제공된 데이터는 go tool pprof로 사용해 여러 형식(PDF, DOT, PNG 등)의 출력을 생성할 수 있습니다.

제공되는 진단 항목은 다음과 같습니다(/debug/pprof에 링크가 포함된 요약이 제공돼요):

allocs: 과거 메모리 할당 전체의 샘플링
block: 동기화 프리미티브에서 블로킹으로 이어진 스택 트레이스
cmdline: 현재 프로그램의 커맨드라인 호출
goroutine: 현재 모든 goroutine의 스택 트레이스
heap: 살아있는 객체의 메모리 할당 샘플링. heap 샘플을 떠기 전에 GC를 실행하려면 gc GET 매개변수를 지정할 수 있어요.
mutex: 경쟁하는 뮤텍스의 보유자 스택 트레이스
profile: CPU 프로파일. seconds GET 매개변수에 기간을 지정할 수 있어요. 프로파일 파일을 얻은 뒤 go tool pprof 명령으로 프로파일을 조사하세요.
threadcreate: 새 OS 스레드 생성으로 이어진 스택 트레이스
trace: 현재 프로그램 실행의 트레이스. seconds GET 매개변수에 기간을 지정할 수 있어요. 트레이스 파일을 얻은 뒤 go tool trace 명령으로 트레이스를 조사하세요.

예시 사용법 (Example Usage)

pprof 엔드포인트는 Linkerd를 설치하거나 업그레이드할 때 --set enablePprof=true 플래그를 설정하거나 enablePprof=true Helm 값을 설정해 활성화할 수 있습니다.

이 데이터는 admin-http 포트를 통해 제공됩니다. 이 포트를 찾으려면 pod의 yaml을 살펴보거나, 예를 들어 identity pod의 경우 다음과 같은 명령을 실행하면 됩니다:

`kubectl -n linkerd get po \
    $(kubectl -n linkerd get pod -l linkerd.io/control-plane-component=identity \
        -o jsonpath='{.items[0].metadata.name}') \
    -o=jsonpath='{.spec.containers[*].ports[?(@.name=="admin-http")].containerPort}'
`

그다음 kubectl port-forward 명령으로 클러스터 밖에서 그 포트에 접근합니다(이 예시에서 포트는 9990입니다):

`kubectl -n linkerd port-forward \
    $(kubectl -n linkerd get pod -l linkerd.io/control-plane-component=identity \
        -o jsonpath='{.items[0].metadata.name}') \
    9990
`

이제 go tool로 이 데이터를 검사할 수 있어요. 예를 들어 메모리 할당을 설명하는 그래프를 PDF 파일로 생성하려면:

`go tool pprof -seconds 5 -pdf http://localhost:9990/debug/pprof/allocs
`

더 알아보기 (Learn more)

Go pprof 패키지 문서
Linkerd 컨트롤 플레인 아키텍처