Monitoring

Kubetail은 각 구성 요소에서 상태 점검 엔드포인트와 구조화된 로그 출력을 제공합니다. 이 페이지에서는 Kubetail이 클러스터 내부에 배포되었을 때 자체 상태를 어떻게 모니터링하는지 설명합니다.

상태 점검

각 구성 요소는 상태 엔드포인트를 제공하며, 클러스터의 liveness 및 readiness probe는 이를 사용해 Pod 상태를 판단합니다.

Dashboard와 Cluster API

Dashboard와 Cluster API는 모두 HTTP 상태 엔드포인트를 제공합니다.

GET /healthz

Helm chart는 이 엔드포인트에 대해 liveness 및 readiness probe를 자동으로 구성합니다. 동일한 엔드포인트를 사용해 구성 요소 상태를 수동으로 확인할 수도 있습니다.

kubectl exec -n kubetail-system deploy/kubetail-dashboard -- \
  wget -qO- http://localhost:8080/healthz

Cluster Agent

Cluster Agent는 gRPC 포트 (:50051) 에서 표준 gRPC health 서비스를 제공합니다. Helm chart는 컨테이너 내부에서 grpc_health_probe를 사용해 readiness와 liveness를 점검합니다.

Logging

세 구성 요소 모두 기본적으로 JSON 형식의 구조화된 로그를 출력합니다. 각 로그 항목에는 타임스탬프, 로그 레벨, 그리고 시스템 전체에서 개별 요청을 추적하기 위한 request_id 같은 컨텍스트 필드가 포함됩니다.

로그 레벨

Level	Description
`debug`	내부 요청 라우팅 세부 정보까지 포함한 상세 출력
`info`	일반적인 운영 메시지(기본값)
`warn`	주의가 필요할 수 있는 복구 가능한 문제
`error`	요청 처리에 영향을 주는 실패
`disabled`	로그 출력 없음

구성

로그 레벨과 형식은 Helm values의 runtimeConfig를 통해 구성 요소별로 설정합니다.

kubetail:
  dashboard:
    runtimeConfig:
      logging:
        level: info
        format: json        # json or pretty
        access-log:
          enabled: true
          hide-health-checks: true  # suppress /healthz from access logs
  clusterAPI:
    runtimeConfig:
      logging:
        level: info
        format: json
        access-log:
          enabled: true
          hide-health-checks: true
  clusterAgent:
    runtimeConfig:
      logging:
        level: info
        format: json

액세스 로그

Dashboard와 Cluster API에는 각 수신 요청을 기록하는 HTTP 액세스 로그가 포함됩니다. 액세스 로그 항목에는 HTTP 메서드, 경로, 상태 코드, 처리 시간, 원격 주소, 요청 ID가 포함됩니다. 노이즈를 줄이기 위해 health check 요청을 액세스 로그에서 숨길 수 있습니다.

logging:
  access-log:
    enabled: true
    hide-health-checks: true

Pod readiness 확인

Kubetail 배포 전체의 상태를 확인하려면 다음을 실행하세요.

kubectl get pods -n kubetail-system

모든 Pod는 Running 상태를 표시하고 readiness probe를 통과해야 합니다. 준비되지 않은 Pod가 있으면 해당 이벤트와 로그를 확인하세요.

kubectl describe pod -n kubetail-system <pod-name>
kubectl logs -n kubetail-system <pod-name>