Skip to content

Observability

wcorn edited this page Aug 11, 2026 · 7 revisions

관측성 (Observability)

orino 플랫폼의 로그·메트릭·트레이스(Three Pillars)와 에러 트래킹 스택. 장애·성능 문제를 빠르게 감지·진단한다.

  • 저장: Loki (로그) · Thanos (메트릭) · Tempo (트레이스) · S3 (장기저장)
  • 수집: Alloy (로그·트레이스) · Prometheus (메트릭)
  • 조회: Grafana (통합 UI, Exemplar 연동)
  • 계측: BE Micrometer + OpenTelemetry, Istio Envoy, FE ErrorBoundary

1. 설계 원칙

원칙 설명
오픈소스 + S3 장기저장 외부 SaaS(DataDog, NewRelic 등) 의존 없이 자체 운영. 장기저장은 S3로 비용 절감
표준 프로토콜 OpenTelemetry(OTLP)로 계측 표준화. 향후 수집기·백엔드 교체 용이
상호 연결 메트릭↔트레이스↔로그 간 Exemplar로 1-clic 이동. 문제 원인 추적 시간 단축
관측 가능성 == 운영 근거 대시보드·알림 기반으로 운영 결정. 감각에 의존하지 않음

2. 컴포넌트 스택

컴포넌트 역할 Upstream Chart Helm 경로
Loki 로그 저장·쿼리 (SingleBinary) grafana/loki 6.55.0 infra/helm/loki/
Tempo 트레이스 저장·쿼리 grafana/tempo 1.24.4 infra/helm/tempo/
Thanos 메트릭 장기저장·글로벌 쿼리 bitnami/thanos (custom) infra/helm/thanos/
Prometheus + Grafana 메트릭 수집 + 통합 조회 UI prometheus-community/kube-prometheus-stack 82.16.0 infra/helm/kube-prometheus-stack/
Alloy 로그·트레이스 수집 에이전트 (DaemonSet) grafana/alloy 1.7.0 infra/helm/alloy/
MinIO S3 호환 오브젝트 스토리지 (일부 테스트용) bitnami/minio 5.4.0 infra/helm/minio/

배포는 모두 GitOps(Infra-Architecture §3) 기반. 각 컴포넌트는 infra/argocd/applications/{name}-app.yaml로 Application 등록.

💰 이 컴포넌트들은 대부분 주기적으로 S3를 두드린다. 어느 설정이 얼마 주기로 도는지는 주기 루프 인벤토리에 정리되어 있다. 차트 values에 안 적힌 기본값이 절반이므로 새 컴포넌트를 붙일 때 반드시 확인한다 — ELOG-027이 그래서 5개월 늦게 발견됐다.

3. 로그 파이프라인

BE Pod (stdout JSON)       FE 브라우저
   │                          │
   │                          │ sendBeacon → BE /api/client-logs (미구현, §11)
   │                          │
   ▼                          ▼
Alloy DaemonSet (파일 tail + 라벨 추가)
   │
   ▼
Loki (3100/loki/api/v1/push)
   │  - TSDB 스키마 v13
   │  - 24h 인덱스 주기
   ▼
S3 (orino-loki-logs 버킷, 90일 보존)
   │
   ▼
Grafana Explore

3.1 BE 구조화 로깅

파일: be/orino-app-api/src/main/resources/logback-spring.xml

Profile 포맷 용도
local 컬러 패턴 (HH:mm:ss.SSS [level] [requestId] [userId] logger - msg) 로컬 개발 가독성
prod LogstashEncoder JSON 운영 (Loki 수집)
test 간단 패턴 테스트 노이즈 최소화

3.2 MDC 필드 (prod JSON 출력)

파일: be/orino-core-web/src/main/java/ds/project/orino/core/web/MdcLoggingFilter.java

MdcLoggingFilter(@Order(HIGHEST_PRECEDENCE))가 요청마다 MDC에 주입하는 필드:

필드 값 설명
requestId UUID 앞 8자 요청 식별자 (response header X-Request-Id로도 반환)
method HTTP 메서드 GET/POST 등
uri 요청 경로 /api/...
userId 인증 사용자 JwtAuthenticationFilter에서 주입
traceId / spanId OTel SDK 자동 주입 Tempo 트레이스와 상관관계

기본 LogstashEncoder 필드(@timestamp, message, logger_name, thread_name, level 등)는 자동 포함.

3.3 Alloy 수집 구성

파일: infra/helm/alloy/values.yaml

  • Kubernetes Pod discovery → relabel (namespace, pod, container, app 라벨)
  • JSON 파싱(stage.json) → 필드 추출: level, logger, requestId, userId, traceId
  • 승격 전략 (카디널리티 관리):
    • level → 스트림 라벨(stage.labels). 저카디널리티라 필터·대시보드 변수로 활용
    • logger / requestId / userId / traceId → structured metadata(stage.structured_metadata). 라벨이 아니라 스트림 카디널리티를 늘리지 않으면서 Grafana 로그 패널에서 컬럼·클릭 필터로 바로 사용 → | json 쿼리 파싱 불필요
    • 전제: Loki tsdb + schema v13, limits_config.allow_structured_metadata: true

3.4 S3 장기저장

  • 버킷: orino-loki-logs (ap-northeast-2)
  • 보존: 90일 (2160h)
  • 인증: observability-s3-secret (SealedSecret, AWS IAM 키)

4. 메트릭 파이프라인

BE Pod (9090/prometheus)
   │   └─ Micrometer Prometheus Registry
   │   └─ Custom business metrics (#203)
   ▼
Prometheus (ServiceMonitor scrape)
   │  - 단기 보존 7일
   │  - Exemplar storage 활성화
   ▼
Thanos Sidecar → Thanos Store Gateway
   │
   ▼
S3 (Raw/5m/1h 계층 압축: 30d/90d/365d 보존)
   │
   ▼
Grafana (Thanos Query 데이터소스)

4.1 BE 메트릭 노출

파일: be/orino-app-api/src/main/resources/application-actuator.yml

  • 포트 분리: 관리 포트 9090 (/prometheus, /health) — 외부 트래픽 차단
  • Micrometer Prometheus Registry로 노출
  • enableFeatures: [exemplar-storage] — 메트릭에 traceId 첨부

4.2 Istio 메트릭

  • Istio sidecar가 자동으로 요청 수·지연·에러율(RED) 메트릭 노출
  • ServiceMonitor로 수집 → Grafana Istio 대시보드

4.3 Thanos 계층 압축

파일: infra/helm/thanos/values.yaml

해상도 보존
Raw 30일
5m 다운샘플 90일
1h 다운샘플 365일

5. 트레이스 파이프라인

Istio Envoy (100% 샘플링)       BE App (Micrometer Tracing)
    │                               │
    │ OTLP/gRPC:4317                │ OTLP/HTTP:4318
    ▼                               ▼
Alloy OTLP Receiver (gRPC:4317 + HTTP:4318)
    │
    ▼
Tempo (4317/v1/traces)
    │  WAL 로컬 캐시
    ▼
S3 (orino-tempo-traces 버킷, 30일 보존)
    │
    ▼
Grafana Tempo Explore

5.1 Istio 트레이싱

파일: infra/helm/istiod/values.yaml, infra/helm/istiod/templates/telemetry.yaml

  • extensionProvider: tempo (OTLP)
  • 샘플링: 100% (초기 운영, 데이터 양 보며 조정)
  • Envoy → Alloy → Tempo 경로

5.2 BE 트레이싱

파일: be/orino-app-api/src/main/resources/application.yml

  • spring-boot-starter-actuator + micrometer-tracing-bridge-otel
  • Endpoint: OTLP HTTP :4318
  • 자동 계측: HTTP 요청, JDBC, RestTemplate, WebClient
  • MDC traceId/spanId와 동일한 ID 사용 → 로그↔트레이스 연결

5.3 Alloy OTLP 수집

파일: infra/helm/alloy/values.yaml

  • otelcol.receiver.otlp: gRPC(4317) + HTTP(4318)
  • otelcol.exporter.otlp → Tempo

6. Exemplar 연동 (상호 링크)

Grafana 단일 UI에서 한 번의 클릭으로 메트릭↔트레이스↔로그 이동.

파일: infra/helm/kube-prometheus-stack/values.yaml

6.1 데이터소스 상호 연결

방향 구성 설명
Prometheus → Tempo exemplarTraceIdDestinations 메트릭 그래프 점 → 해당 트레이스
Loki → Tempo derivedFields (traceId 정규식 추출) 로그 라인 → 해당 트레이스
Tempo → Loki tracesToLogsV2 (namespace/pod 필터) 트레이스 span → 동시간대 로그

6.2 운영 시나리오

지연 증가 조사 예시:

  1. Grafana 대시보드에서 BE p95 지연 스파이크 확인
  2. 스파이크 구간의 Exemplar 점 클릭 → 해당 트레이스로 이동 (Tempo)
  3. 느린 span(예: DB 쿼리) 확인 → Logs for this span 클릭 → 동시간대 Loki 로그
  4. 로그의 requestId로 전체 요청 흐름 재구성

7. FE 관측성 (Grafana Faro)

브라우저 런타임 텔레메트리(에러·로그·Web Vitals·트레이스·세션)를 Grafana Faro로 수집한다. 기존 LGTM 스택에 자연스럽게 통합되며, 별도 SaaS(Sentry 등)가 필요 없다.

데이터 흐름:

FE 브라우저 (Faro Web SDK)
   │  HTTPS (CORS + API key)
   ▼
Alloy faro.receiver (telemetry.orino.dev:443)
   │
   ├─ logs   → Loki  (기존 로그 파이프라인과 동일)
   └─ traces → Tempo (기존 BE 트레이스와 동일 백엔드)

7.1 수집 대상 (자동)

영역 내용
에러 window.error, unhandledrejection, React ErrorBoundary
로그 console.*, faro.api.pushLog(...) 수동 호출
Web Vitals LCP, FID, CLS, INP, TTFB
세션 자동 sessionId 생성, 페이지뷰·네비게이션 추적
트레이스 fetch/XHR 자동 계측 + W3C traceparent 헤더 BE 전파
사용자 행동 라우트 변경 (React Router v7 통합)

7.2 BE와 트레이스 연결

Faro Web SDK의 TracingInstrumentation이 fetch/axios 요청에 traceparent 헤더를 주입 → BE가 같은 traceId로 span 생성 → FE 클릭 → BE 처리 → DB 쿼리까지 단일 트레이스로 Tempo에서 조회.

propagateTraceHeaderCorsUrls에 BE URL 패턴(api.orino.dev)을 등록해야 작동.

7.3 FE SDK 구성

패키지:

  • @grafana/faro-react (React 통합, ErrorBoundary 포함)
  • @grafana/faro-web-tracing (OTel 트레이싱)

초기화 (fe/src/main.tsx):

import { initializeFaro, getWebInstrumentations, ReactIntegration,
         createReactRouterV6Options, initializeReactRouterV6Instrumentation } from '@grafana/faro-react';
import { TracingInstrumentation } from '@grafana/faro-web-tracing';

initializeFaro({
  url: import.meta.env.VITE_FARO_URL,      // https://telemetry.orino.dev/collect
  apiKey: import.meta.env.VITE_FARO_KEY,
  app: { name: 'orino-fe', version: __APP_VERSION__, environment: import.meta.env.MODE },
  instrumentations: [
    ...getWebInstrumentations(),
    new TracingInstrumentation({
      instrumentationOptions: {
        propagateTraceHeaderCorsUrls: [/https:\/\/api\.orino\.dev\/.*/],
      },
    }),
    new ReactIntegration({ router: createReactRouterV6Options({ ... }) }),
  ],
});

App.tsx: 기존 ErrorBoundary를 @grafana/faro-react의 FaroErrorBoundary로 교체 또는 직접 faro.api.pushError(error) 호출.

7.4 Alloy faro.receiver 구성

추가 파일: infra/helm/alloy/values.yaml

faro.receiver "app_receiver" {
  server {
    listen_address           = "0.0.0.0"
    listen_port              = 12347
    cors_allowed_origins     = ["https://orino.dev"]
    api_key                  = env("FARO_API_KEY")
    max_allowed_payload_size = "10MiB"
    rate_limiting {
      rate = 100
    }
  }
  sourcemaps { }
  output {
    logs   = [loki.process.json_parse.receiver]           // 기존 파이프라인 재사용
    traces = [otelcol.exporter.otlp.tempo.input]          // 기존 tempo exporter 재사용
  }
}

7.5 외부 노출

telemetry.orino.dev 서브도메인을 Istio Gateway + VirtualService로 Alloy Service(12347 포트)에 라우팅. CORS는 Alloy가 처리.

7.6 API Key 관리

SealedSecret(alloy-faro-secret)으로 API key 관리. FE는 public key처럼 번들에 포함(노출되어도 rate limit·CORS가 방어).

7.7 Source Map 업로드 (선택)

prod 빌드의 minified 스택트레이스를 원본 파일/라인으로 복원하려면 faro-javascript-bundler-plugins의 Vite 플러그인 사용. 초기 도입 시 생략 가능, 필요해지면 추가.

8. 배포·시크릿 구성

8.1 공통 S3 시크릿

SealedSecret: observability-s3-secret (Loki/Tempo 공유, Thanos는 별도 thanos-objstore-secret)

키 값
AWS_ACCESS_KEY_ID IAM 키
AWS_SECRET_ACCESS_KEY IAM 시크릿
AWS_REGION ap-northeast-2

SealedSecret 갱신은 .secrets 참조(CLAUDE.md Secrets 관리).

8.2 네임스페이스

관측성 스택은 monitoring 네임스페이스에 집중 배포. istio-injection: enabled 미적용(관측성 자체가 무한 루프 유발 방지).

9. Grafana 대시보드

대시보드는 실제로 쓰는 커스텀 대시보드만 프로비저닝한다(GitOps). grafana.defaultDashboardsEnabled: false — kube-prometheus-stack 기본 세트(~25종)는 안 보는 노이즈라 비활성화한다.

  • infra/helm/kube-prometheus-stack/grafana-dashboards/*.json 을 grafana_dashboard: "1" 라벨 ConfigMap(templates/dashboard-*.yaml)으로 마운트 → Grafana sidecar가 자동 로드.
대시보드 UID 소스 용도
Logs (App) orino-logs grafana-dashboards/logs-overview.json 레벨별 로그량·ERROR/WARN/INFO 카운트·로거별 에러 Top·메인 Logs 패널. 변수: namespace/app/level/search. traceId→Tempo 링크
SLO Overview (slo) grafana-dashboards/slo-overview.json 가용성·지연 SLI, error budget

리소스/노드/파드 메트릭이 필요할 때는 Explore에서 직접 쿼리하거나 필요한 패널만 커스텀 대시보드에 추가한다(기본 세트 일괄 노출 대신 선별).

9.1 Logs (App) 대시보드 사용

  • 레벨 필터: level은 라벨이라 변수로 즉시 필터(error/warn/info/...).
  • 식별자 필터: requestId/userId/logger/traceId는 structured metadata로 부착되어 로그 패널에서 클릭 한 번으로 필터(쿼리에 | json 불필요).
  • 트레이스 연계: 로그 라인의 traceId → derivedField로 Tempo 트레이스 이동(§6.1).
  • 자유 검색: search 변수 → |~ "(?i)$search" 정규식.

10. 알림 (Alerting)

Prometheus Alertmanager + 커스텀 PrometheusRule로 알림 규칙을 선언적으로 관리한다.

10.1 Alertmanager 구성

파일: infra/helm/kube-prometheus-stack/values.yaml (§alertmanager.config)

항목 값
라우팅 모든 severity=critical|warning 알림 → Discord
채널 Discord webhook (alertmanager-discord-secret)
Grouping alertname, namespace
group_wait 30s
group_interval 5m
repeat_interval 4h
저장소 Longhorn PVC 5Gi

10.2 현재 알림 규칙

파일: infra/helm/kube-prometheus-stack/templates/prometheusrule.yaml

카테고리 알림 Severity 조건
Pod PodCrashLoopBackOff critical 5분간 재시작 반복
PodOOMKilled warning OOMKilled 발생
PodNotReady warning 10분 이상 Not Ready
ContainerMemoryNearLimit warning limit 90% 초과 5분
DeploymentReplicasMismatch critical 10분 이상 replica 불일치
Node NodeNotReady critical 5분 이상 Not Ready
NodeHighCpuUsage warning CPU > 85% 10분
NodeHighMemoryUsage warning 메모리 > 85% 10분
NodeDiskSpaceLow warning 디스크 > 85% 10분
Longhorn LonghornBackupFailed critical 백업 실패
LonghornVolumeDegrade warning 볼륨 5분 이상 Degraded
App BackendDown / FrontendDown critical 1분 이상 Pod Not Ready
MysqlDown / RedisDown critical 1분 이상 Pod Not Ready
Storage PvcUsageHigh warning PVC > 80% 5분

10.3 로그 기반 알림 (Loki Ruler)

메트릭으로 잡히지 않는 로그 내용 기반 에러를 Loki Ruler로 탐지한다.

파일: infra/helm/loki/values.yaml(loki.rulerConfig), 룰 본문 infra/helm/loki/files/orino-log-alerts.yaml → loki-alerting-rules ConfigMap을 /rules/fake(테넌트 fake, auth 비활성)로 마운트.

  • 전송: alertmanager_url → kube-prometheus-stack-alertmanager.monitoring:9093 → 기존 Discord 라우팅(§10.1) 재사용.
  • 룰 스토리지: local(ConfigMap 마운트), GitOps로 룰 버전 관리.
알림 Severity 조건(LogQL)
HighErrorLogRate warning {namespace="orino",level="error"} 5분간 10건 초과
JsonParseErrors warning json parse/JsonParseException/JsonMappingException/MismatchedInputException 10분 내
OutOfMemoryErrors critical OutOfMemoryError 10분 내
JdbcConnectionErrors warning unable to acquire jdbc/connection is not available/HikariPool...timeout 5분 내
UncaughtExceptionSpike warning unexpected error/unhandled/NullPointerException 10분간 5건 초과

임계값은 단일 사용자 트래픽 기준 초기값 — 운영 보며 조정.

10.4 누락된 알림 영역 (§12.2 gap)

현재 인프라 레벨(Pod/Node/PVC) 알림은 완비. 다음은 미구성:

  • 애플리케이션 메트릭 (BE Micrometer): HTTP 5xx 에러율, p95 지연, JVM heap, DB 커넥션 풀 포화, ThreadPool 거부
  • Istio 메트릭: 서비스 간 RED (Rate/Error/Duration) 임계값
  • 관측성 자체: Loki/Tempo/Prometheus/Alloy down·스크래핑 실패
  • 인증서: cert-manager Certificate 만료 30일/7일 전 경고
  • SLO burn rate (§11 참조)

11. SLO·에러 예산

서비스 품질 목표를 명시적으로 관리해 운영 판단의 기준으로 삼는다. 개인 서비스라 대기업 수준 SLO는 불필요하지만, 명시된 기준이 있어야 개선 방향을 잡을 수 있다.

11.1 SLO 대상 서비스

서비스 URL 중요도
orino FE orino.dev 사용자 진입점
orino BE API api.orino.dev FE가 의존

Alloy/Grafana 등 관측성 자체는 SLO 대상 아님(내부 도구).

11.2 지표와 목표 (초기)

SLI 정의 목표 SLO 에러 예산 (월)
가용성 5xx가 아닌 응답 / 전체 응답 99.0% 월 7시간 18분
지연 p95 요청 지연 < 500ms (95% of time) 월 약 36시간

근거:

  • 개인 플랫폼: 99.9%는 과도 (1인 운영자 대응 시간 고려)
  • 99%면 월 다운타임 ~7h 허용 → 운영 피로도↓
  • 학습·사용 패턴 쌓이면서 목표 상향

11.3 측정 소스

Istio 메트릭을 primary source로 사용 (배포 언어 독립적).

# 가용성 SLI (BE)
sum(rate(istio_requests_total{
  destination_service_name="be",
  response_code!~"5.."
}[5m]))
/
sum(rate(istio_requests_total{destination_service_name="be"}[5m]))

# 지연 SLI (BE p95)
histogram_quantile(0.95, sum by (le) (
  rate(istio_request_duration_milliseconds_bucket{
    destination_service_name="be"
  }[5m])
))

FE는 Istio Gateway 레벨 메트릭 사용 (reporter="source").

11.4 Burn Rate 알림 (Multi-Window)

단순 "현재 에러율 > X" 알림은 노이즈가 많다. Burn rate는 "현재 속도로 가면 SLO를 언제 소진할지" 측정.

알림 Burn Rate 윈도우 Severity 의미
Fast burn 14.4× 1h + 5m critical 2일이면 월 예산 소진 → 즉시 대응
Slow burn 6× 6h + 30m warning 5일이면 월 예산 소진 → 조사 필요

구현: PrometheusRule의 recording rule로 error rate 계산 + alert rule로 burn rate 평가.

11.5 대시보드

Grafana에 "SLO 대시보드" 구축 필요:

  • 현재 SLI 값
  • 월간 남은 에러 예산 (%, 시간)
  • 시간대별 에러율 추이
  • burn rate 현재값
  • 목표 대비 over/under 기간

Sloth 등 SLO generator 도구로 PrometheusRule·대시보드 자동 생성 검토.

12. 알려진 gap · 향후 개선

12.1 FE 에러 트래킹 → Faro 전환 진행 중

현상: FE error-logger.ts가 prod에서 /api/client-logs로 sendBeacon 전송하나, BE에 해당 컨트롤러 없어 에러 로그 유실 중.

결정: BE proxy 방식(#292)은 폐기. Grafana Faro로 전환 (§7 설계).

관련 이슈:

  • wcorn/orino#292 (폐기, Faro 이슈로 대체)
  • wcorn/orino#296 Infra: Alloy faro.receiver + telemetry.orino.dev 노출
  • wcorn/orino#297 FE: Faro Web SDK 도입 (#296 블록)

12.2 애플리케이션·Istio 메트릭 기반 알림 미구성

§10.3 참조. 인프라 레벨 알림(Pod/Node)은 구축됐으나 BE 애플리케이션·Istio RED 메트릭 알림 부재.

관련 이슈: wcorn/orino#300

12.3 SLO·Burn Rate 알림 미구현

§11 설계 기준의 PrometheusRule·대시보드 미구축 상태.

관련 이슈: wcorn/orino#301 (#300 일부 의존)

13. 참조

  • 코드·배포:
    • infra/helm/{loki,tempo,thanos,kube-prometheus-stack,alloy}/ — Helm 구성
    • be/orino-app-api/src/main/resources/logback-spring.xml — 로깅 포맷
    • be/orino-core-web/src/main/java/ds/project/orino/core/web/MdcLoggingFilter.java — MDC 주입
    • be/orino-app-api/src/main/resources/application.yml — Tracing 설정
    • fe/src/shared/error/ — FE 에러 트래킹
  • 문서:
  • 외부:

Clone this wiki locally