콘텐츠로 이동

운영과 관측

배포 프로파일에서 REST 트래픽과 관리 엔드포인트는 포트가 분리됩니다.

  • 8080: /v1/**, /healthz
  • 9090: /actuator/health, /actuator/info, /actuator/metrics, /actuator/prometheus

/healthz는 DB나 외부 서비스를 확인하지 않고 항상 200 text/plain "ok"만 반환합니다. 외부 LB·uptime 확인용입니다. Kubernetes startup/liveness/readiness probe는 9090의 집계 Actuator health를 사용합니다.

9090은 외부에 공개하지 않습니다

Actuator에는 애플리케이션 인증이 없습니다. Deployment의 mgmt 컨테이너 포트는 probe와 GMP가 파드 IP로 접근하기 위한 것이며 Service, NEG, Ingress에 추가하면 안 됩니다.

메트릭

Micrometer Prometheus 레지스트리가 /actuator/prometheus를 제공하고 GKE Managed Prometheus의 PodMonitoring이 mgmt 포트를 스크레이프합니다. 기본 JVM, HTTP, HikariCP 지표와 application=sohri-app-backend 공통 태그를 사용합니다.

PostgreSQL 파티션 프로브가 활성화된 환경에서는 다음 지표를 1시간마다 갱신합니다.

  • sohri_partition_headroom_days{table}: 이번 달부터 연속 파티션 커버리지 잔여일
  • sohri_partition_missing_months{table}: 중간 결손 월 수
  • sohri_partition_default_rows{table}: DEFAULT 파티션 행 존재 여부 확인용 수치
  • sohri_partition_probe_last_success_seconds: 마지막 성공 epoch seconds

프로브는 읽기 전용이며 파티션을 생성하지 않습니다. 실패 시 마지막 값을 덮어쓰지 않고 성공 시각도 갱신하지 않아 정체·부재 알림이 실패를 감지하도록 설계되어 있습니다. gke에서는 활성, 병합 프로파일 gke,prod에서는 prod 오버라이드로 현재 비활성입니다.

트레이싱

Micrometer Tracing과 OpenTelemetry OTLP/HTTP exporter가 Cloud Trace로 직접 전송합니다. GKE에서는 Workload Identity ADC로 인증하고 gcp.project_id와 quota project header를 설정합니다.

기본 sampling은 0.1이지만 gke 프로파일은 1.0입니다. 현재 운영 values는 gke,prod를 순서대로 활성화하고 prod가 sampling을 다시 낮추지 않으므로 실효값은 1.0입니다. 비용·트래픽 관점에서 의도한 값인지 배포별로 확인해야 합니다.

로그와 감사

  • 요청 로그: method, URI, query parameter, header, remote address, status, elapsed time
  • 외부 Graph Builder 호출: URL, 상태, 분류된 성공·실패
  • 음성 접근 감사: principal, principalId, workspaceId, dialogId, messageId, outcome, bytes, duration
  • DB 무결성 오류: SQLSTATE와 서버 진단만 로그에 남기고 응답에는 내부 정보를 제외

요청 header 전체를 기록하는 현재 구현은 credential 노출 위험이 있으므로 보안과 현재 격차에 설명한 마스킹 점검이 필요합니다.

데이터베이스 운영

  • 운영 DB: PostgreSQL 16
  • 스키마 생성: ddl-auto=none, SQL init 비활성
  • 정본: sohri-db
  • 시간 기준: JVM과 JDBC 바인딩 UTC, API 직렬화 설정은 Asia/Seoul
  • prod Hikari: minimum idle 2, maximum pool 10
  • OSIV: 비활성

파티션 생성·마이그레이션은 App Backend가 수행하지 않습니다. sohri-db의 유지보수 함수와 운영 절차를 사용하고, 정본 변경 뒤 App Backend의 테스트용 schema.sql 사본과 JPA 매핑을 동기화해야 합니다.

기본 확인 순서

  1. 외부 생존 확인은 GET /healthz로 프로세스와 라우팅을 확인합니다.
  2. 클러스터 내부에서는 9090의 Actuator health로 DB 포함 상태를 확인합니다.
  3. HTTP latency·status와 Hikari pending/active를 확인합니다.
  4. 템플릿 등록 장애는 Graph Builder 검증 로그와 400/503 분류를 봅니다.
  5. 대화 조회 누락은 Socket Backend 기록 여부, 공유 DB 행, speech phase와 tenant를 순서대로 확인합니다. App Backend가 Socket Backend를 직접 호출하는 구간은 없습니다.

배포 키와 프로파일 값은 설정 참조를 참고하세요.