# observability / health 기준

## 목적

이 문서는 1000+ 서비스가 공통으로 따르는 observability 기준선이다. metrics 수집 경로, golden signal 정의, 로그 포맷 / 수집 stack, trace 수집(OTel), health endpoint 외부 비공개 원칙, cardinality 가드를 한 파일에 고정한다.

## 공식 / 업계 근거

- **Google SRE Book (Ch.6)**: Four Golden Signals = **Latency, Traffic, Errors, Saturation**. 운영 대시보드의 기본 구성 원칙.
- **RED method (Tom Wilkie, Weaveworks)**: request-driven service에 대해 **Rate, Errors, Duration**.
- **USE method (Brendan Gregg)**: resource에 대해 **Utilization, Saturation, Errors**.
- **kube-prometheus-stack**: Prometheus Operator를 통한 `ServiceMonitor` / `PodMonitor` CRD가 primary scrape path.
- **Prometheus annotation fallback**: `prometheus.io/scrape: "true"` 등은 Operator가 없을 때만 사용.
- **OpenTelemetry**: OTLP protocol + OTel Collector (Deployment gateway + DaemonSet agent) 가 표준.
- **Log shipping canonical stacks**: Loki + Grafana Alloy (또는 Promtail) / Fluent Bit → OpenSearch. 한 플랫폼에서 둘 이상 섞지 않는다.
- `kubectl events` (1.27+ stable) — 기존 `kubectl get events`보다 sort/watch 기본 제공.
- metrics-server: HPA/VPA와 `kubectl top` 을 위한 최소 resource metric. full metrics와 분리.

## 기본 규칙

### 1. Four Golden Signals를 모든 서비스 대시보드의 골격으로

각 traffic-facing service는 최소 4개 signal을 노출한다.

- **Latency**: `request_duration_seconds` histogram (p50/p95/p99).
- **Traffic**: `requests_per_second` by method/status.
- **Errors**: `error_rate` (5xx / 전체).
- **Saturation**: resource utilization (CPU / memory / connection pool / queue depth).

SLO / alert / dashboard가 이 4개에서 시작한다.

### 2. RED는 request-driven, USE는 resource에 쓴다

- HTTP / gRPC 서비스 → **RED**.
- Node / disk / CPU / DB pool → **USE**.
- 두 방법론을 동시에 활용 가능 (golden signal은 양쪽 합집합).

### 3. ServiceMonitor / PodMonitor 를 primary scrape path로

kube-prometheus-stack을 운영하는 플랫폼에서는 `ServiceMonitor` CRD가 표준이다.

- `selector.matchLabels` 로 대상 Service 매칭.
- `namespaceSelector` 명시 (암묵적 전체 허용 금지).
- `endpoints[].port` 는 **named port**, 숫자 port 금지.
- `interval` (기본 30s), `scrapeTimeout` (interval < interval) 명시.
- `scheme` (http/https) 명시.
- `bearerTokenSecret` / `tlsConfig` 로 인증 scrape.
- `relabelings` 로 label 위생 (pod_template_hash drop 등).

Pod에 직접 연결되는 경우 (Service가 없는 워크로드) `PodMonitor` 사용.

### 4. Annotation-based scrape 는 fallback

`prometheus.io/scrape: "true"` 계열 annotation은 Prometheus가 Operator 없이 kubernetes_sd_configs로 직접 discover하는 방식이다. ServiceMonitor 대비 label relabel / auth / tls 제어가 약하다.

- kube-prometheus-stack이 있는 환경: **사용 금지**, ServiceMonitor 통일.
- legacy / 교체 진행 중인 플랫폼: 전환 기간 동안만 사용.

지원 annotation:
- `prometheus.io/scrape: "true"`
- `prometheus.io/port: "8081"`
- `prometheus.io/path: "/metrics"`
- `prometheus.io/scheme: "http"`

### 5. metrics port는 외부 비공개, NetworkPolicy로 scraper만 허용

- `/metrics` 는 절대 Ingress 경로에 노출하지 않는다.
- metrics port는 별도 containerPort (ex: 8081, 9000).
- NetworkPolicy로 **monitoring namespace의 prometheus pod만** 해당 port에 ingress 허용.

### 6. Cardinality는 label 설계 단계에서 가드

Prometheus TSDB에서 **각 label value 조합 = 새 time series**. cardinality 폭발은 쿼리 OOM / storage 폭증의 가장 흔한 원인.

금지 label:

- `user_id`, `tenant_id` (높은 기수) — 대신 top-N aggregation 또는 별도 logging.
- `path` (path에 UUID / numeric ID 포함) — template된 route로 바꾼다 (`/users/:id`).
- `url` 전체, `request_id`, `trace_id`, `session_id`.
- timestamp, epoch value.

허용 label 예:
- `method` (GET/POST/…), `status_code` (bucketed 2xx/4xx/5xx가 더 안전), `route` (template).

규칙: **한 metric당 series 수 ≤ 10,000** 목표. 10만 넘어가면 review.

### 7. Histogram 을 p99 표현 기본값으로

- summary는 aggregatable 하지 않다 (서비스 간 p99 합산 불가).
- `histogram_quantile()` 를 위한 `_bucket` + `_count` + `_sum` 를 쓴다.
- bucket boundary는 SLO에 맞춰 튜닝 (`le: 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10`).

### 8. 로그는 JSON structured, stdout/stderr 로만

application log는 **JSON one-line per record**, stdout/stderr로 출력. PVC / hostPath / 컨테이너 내부 file 금지.

필수 field:

- `timestamp` (ISO 8601 RFC3339, UTC).
- `level` (`DEBUG`/`INFO`/`WARN`/`ERROR`).
- `service` (= `app.kubernetes.io/name`).
- `trace_id`, `span_id` (OTel에서 주입).
- `message`.
- `error` (object with `type`, `message`, `stacktrace` when level=ERROR).
- optional: `user_id` (hashed), `request_id`, `http_status`.

### 9. 로그 수집 stack은 한 플랫폼당 하나

canonical choice:

- **Loki + Grafana Alloy (권장)**: 낮은 storage cost, Grafana 통합.
- **Fluent Bit → OpenSearch/Elasticsearch**: full-text search 중심, 높은 storage cost.

플랫폼 하나에서 둘 다 운영하지 않는다. AI agent가 매니페스트 생성할 때 플랫폼 선택을 context에서 받아 일관되게 적용한다.

node-level: DaemonSet으로 agent 배포 → tail `/var/log/containers/*.log`.

### 10. 민감정보는 로그 금지 + 자동 masking

금지:

- access/refresh token, bearer, API key.
- DB password, connection string의 password 부분.
- Vault secret value.
- full Authorization header.
- PII (email, phone, SSN 등) 원문.

구현:

- logging framework의 structured field 에서만 쓰고 `toString()` 흐름 차단.
- 중앙 수집 파이프라인에 redaction filter 추가.
- 의심스러운 pattern은 debug 로그에서도 masking.

### 11. OpenTelemetry / OTLP를 trace / metrics 통로로

- 애플리케이션: OTel SDK로 계측, OTLP (gRPC 4317 또는 HTTP 4318) 로 export.
- 수집: **OTel Collector DaemonSet (agent)** → **OTel Collector Deployment (gateway)** → backend (Tempo / Jaeger / New Relic / Datadog).
- gateway에서 sampling / tail-based sampling / PII scrubbing 적용.
- app은 cluster 내부 agent endpoint만 알면 됨 (localhost:4317 → DaemonSet).

### 12. health / metrics / admin endpoint 는 외부 비공개 기본값

외부 비공개 대상:

- `/health`, `/health/*`, `/actuator/*`.
- `/metrics`.
- `/admin`, `/internal`, `/debug`.
- Keycloak management port 9000.
- Vault `/sys/*` endpoint.

외부 공개는 명시적 review 필요.

### 13. probe는 health endpoint 와 목적을 구분

- probe용 endpoint는 shallow, 빠른 응답.
- 운영자 점검용 deep health는 별도 endpoint (ex: `/ops/deep-health`), 인증 필요.
- Prometheus 가 `/metrics` 를 스크레이프하더라도 probe가 `/metrics` 를 쓰지 않는다 (cost 문제).

### 14. `kubectl events` 를 기본 event 조회 수단으로 (1.27+)

Kubernetes 1.27+ 부터 `kubectl events` 가 stable.

- `kubectl events -A --watch` — cluster-wide live view.
- `kubectl events -n <ns> --for pod/<name>` — 특정 오브젝트.
- `kubectl events --types=Warning` — 경고만.

`kubectl get events` 대비 sort-by-timestamp 기본, watch 안정적.

### 15. 알림 기준: Golden Signal 에 SLO 를 먼저 정의

- availability SLO: 99.9% / 99.95% 등.
- latency SLO: p99 < 500ms.
- error budget: (1 - SLO) × 기간.
- alert는 **burn rate** 기준 (1h/6h fast burn + 6h/3d slow burn 이중 창).

단순 "CPU > 80%" alert 는 actionable 하지 않다 (saturation은 dashboard용, 알림은 SLO 기반).

### 16. 워크로드별 기본 권장안

#### auth-server (Spring Boot)
- metrics: micrometer + prometheus registry, `/actuator/prometheus`.
- ServiceMonitor with named port `metrics` (8081).
- tracing: OTel Java agent, OTLP to DaemonSet.
- logging: logback JSON encoder → stdout.

#### keycloak
- metrics: management port 9000 `/metrics`.
- ServiceMonitor 대상, `/admin` 과 `9000` 외부 비공개.
- event metric cardinality는 `event_type` level 까지만, user / session ID 금지.

#### vault
- `/sys/metrics?format=prometheus` (token 필요) → ServiceMonitor with `bearerTokenSecret`.
- `/sys/health` 는 sealed/standby 구분해서 alert 룰 따로.

#### minio
- `/minio/v2/metrics/cluster` + `/node` + `/bucket`.
- bucket metric은 bucket 수 폭증 시 cardinality 주의.

#### db (PostgreSQL / MySQL)
- postgres_exporter / mysqld_exporter sidecar 또는 별도 Deployment.
- USE method (connection pool saturation, lock wait).

#### ingress-controller
- RED + upstream response time.
- path label은 반드시 template 화.

## 프로젝트 기준 요약

- Four Golden Signals를 dashboard 골격으로, RED/USE를 세부 방법론으로.
- ServiceMonitor / PodMonitor 를 primary scrape, annotation은 fallback.
- metrics port는 NetworkPolicy로 monitoring namespace만 허용.
- Cardinality는 label 설계에서 가드 (user_id / raw path / timestamp 금지).
- 로그는 JSON structured stdout, trace_id/span_id 포함.
- log shipping stack은 플랫폼당 하나 (Loki+Alloy 또는 Fluent Bit→OpenSearch).
- 로그에 민감정보 금지, 중앙 파이프라인 redaction.
- OpenTelemetry DaemonSet agent + Deployment gateway.
- health / metrics / admin endpoint 외부 비공개.
- `kubectl events` 를 기본 event 조회 수단으로 (1.27+).
- alert는 SLO burn rate 기반, CPU% 같은 단순 threshold 금지.