# Monitoring

import { Aside } from '@astrojs/starlight/components';

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

---

## 상태 점검

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

### Dashboard와 Cluster API

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

```
GET /healthz
```

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

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

### Cluster Agent

Cluster Agent는 gRPC 포트 (`:50051`) 에서 표준 [gRPC health](https://grpc.github.io/grpc/core/md_doc_health-checking.html) 서비스를 제공합니다. Helm chart는 컨테이너 내부에서 `grpc_health_probe`를 사용해 readiness와 liveness를 점검합니다.

---

## Logging

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

### 로그 레벨

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

### 구성

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

```yaml
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
```

<Aside type="tip">
개발 중에는 사람이 읽기 쉬운 로그 출력을 위해 `format: pretty`를 사용하세요. 운영 환경에서는 `format: json`이 로그 집계 도구와 더 잘 통합됩니다.
</Aside>

### 액세스 로그

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

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

---

## Pod readiness 확인

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

```sh
kubectl get pods -n kubetail-system
```

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

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