Repository navigation
Observability
orino 플랫폼의 로그·메트릭·트레이스(Three Pillars)와 에러 트래킹 스택. 장애·성능 문제를 빠르게 감지·진단한다.
- 저장: Loki (로그) · Thanos (메트릭) · Tempo (트레이스) · S3 (장기저장)
- 수집: Alloy (로그·트레이스) · Prometheus (메트릭)
- 조회: Grafana (통합 UI, Exemplar 연동)
- 계측: BE Micrometer + OpenTelemetry, Istio Envoy, FE ErrorBoundary
| 원칙 | 설명 |
|---|---|
| 오픈소스 + S3 장기저장 | 외부 SaaS(DataDog, NewRelic 등) 의존 없이 자체 운영. 장기저장은 S3로 비용 절감 |
| 표준 프로토콜 | OpenTelemetry(OTLP)로 계측 표준화. 향후 수집기·백엔드 교체 용이 |
| 상호 연결 | 메트릭↔트레이스↔로그 간 Exemplar로 1-clic 이동. 문제 원인 추적 시간 단축 |
| 관측 가능성 == 운영 근거 | 대시보드·알림 기반으로 운영 결정. 감각에 의존하지 않음 |
| 컴포넌트 | 역할 | 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개월 늦게 발견됐다.
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
파일: 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 |
간단 패턴 | 테스트 노이즈 최소화 |
파일: 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 등)는 자동 포함.
파일: 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
-
- 버킷:
orino-loki-logs(ap-northeast-2) - 보존: 90일 (
2160h) - 인증:
observability-s3-secret(SealedSecret, AWS IAM 키)
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 데이터소스)
파일: be/orino-app-api/src/main/resources/application-actuator.yml
- 포트 분리: 관리 포트 9090 (
/prometheus,/health) — 외부 트래픽 차단 - Micrometer Prometheus Registry로 노출
-
enableFeatures: [exemplar-storage]— 메트릭에 traceId 첨부
- Istio sidecar가 자동으로 요청 수·지연·에러율(RED) 메트릭 노출
- ServiceMonitor로 수집 → Grafana Istio 대시보드
파일: infra/helm/thanos/values.yaml
| 해상도 | 보존 |
|---|---|
| Raw | 30일 |
| 5m 다운샘플 | 90일 |
| 1h 다운샘플 | 365일 |
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
파일: infra/helm/istiod/values.yaml, infra/helm/istiod/templates/telemetry.yaml
-
extensionProvider: tempo (OTLP) - 샘플링: 100% (초기 운영, 데이터 양 보며 조정)
- Envoy → Alloy → Tempo 경로
파일: 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 사용 → 로그↔트레이스 연결
파일: infra/helm/alloy/values.yaml
-
otelcol.receiver.otlp: gRPC(4317) + HTTP(4318) -
otelcol.exporter.otlp→ Tempo
Grafana 단일 UI에서 한 번의 클릭으로 메트릭↔트레이스↔로그 이동.
파일: infra/helm/kube-prometheus-stack/values.yaml
| 방향 | 구성 | 설명 |
|---|---|---|
| Prometheus → Tempo | exemplarTraceIdDestinations |
메트릭 그래프 점 → 해당 트레이스 |
| Loki → Tempo |
derivedFields (traceId 정규식 추출) |
로그 라인 → 해당 트레이스 |
| Tempo → Loki |
tracesToLogsV2 (namespace/pod 필터) |
트레이스 span → 동시간대 로그 |
지연 증가 조사 예시:
- Grafana 대시보드에서 BE p95 지연 스파이크 확인
- 스파이크 구간의 Exemplar 점 클릭 → 해당 트레이스로 이동 (Tempo)
- 느린 span(예: DB 쿼리) 확인 → Logs for this span 클릭 → 동시간대 Loki 로그
- 로그의
requestId로 전체 요청 흐름 재구성
브라우저 런타임 텔레메트리(에러·로그·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 트레이스와 동일 백엔드)
| 영역 | 내용 |
|---|---|
| 에러 |
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 통합) |
Faro Web SDK의 TracingInstrumentation이 fetch/axios 요청에 traceparent 헤더를 주입 → BE가 같은 traceId로 span 생성 → FE 클릭 → BE 처리 → DB 쿼리까지 단일 트레이스로 Tempo에서 조회.
propagateTraceHeaderCorsUrls에 BE URL 패턴(api.orino.dev)을 등록해야 작동.
패키지:
-
@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) 호출.
추가 파일: 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 재사용
}
}
telemetry.orino.dev 서브도메인을 Istio Gateway + VirtualService로 Alloy Service(12347 포트)에 라우팅. CORS는 Alloy가 처리.
SealedSecret(alloy-faro-secret)으로 API key 관리. FE는 public key처럼 번들에 포함(노출되어도 rate limit·CORS가 방어).
prod 빌드의 minified 스택트레이스를 원본 파일/라인으로 복원하려면 faro-javascript-bundler-plugins의 Vite 플러그인 사용. 초기 도입 시 생략 가능, 필요해지면 추가.
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 관리).
관측성 스택은 monitoring 네임스페이스에 집중 배포. istio-injection: enabled 미적용(관측성 자체가 무한 루프 유발 방지).
대시보드는 실제로 쓰는 커스텀 대시보드만 프로비저닝한다(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에서 직접 쿼리하거나 필요한 패널만 커스텀 대시보드에 추가한다(기본 세트 일괄 노출 대신 선별).
-
레벨 필터:
level은 라벨이라 변수로 즉시 필터(error/warn/info/...). -
식별자 필터:
requestId/userId/logger/traceId는 structured metadata로 부착되어 로그 패널에서 클릭 한 번으로 필터(쿼리에| json불필요). - 트레이스 연계: 로그 라인의 traceId → derivedField로 Tempo 트레이스 이동(§6.1).
-
자유 검색:
search변수 →|~ "(?i)$search"정규식.
Prometheus Alertmanager + 커스텀 PrometheusRule로 알림 규칙을 선언적으로 관리한다.
파일: 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 |
파일: 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분 |
메트릭으로 잡히지 않는 로그 내용 기반 에러를 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건 초과 |
임계값은 단일 사용자 트래픽 기준 초기값 — 운영 보며 조정.
현재 인프라 레벨(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 참조)
서비스 품질 목표를 명시적으로 관리해 운영 판단의 기준으로 삼는다. 개인 서비스라 대기업 수준 SLO는 불필요하지만, 명시된 기준이 있어야 개선 방향을 잡을 수 있다.
| 서비스 | URL | 중요도 |
|---|---|---|
| orino FE | orino.dev |
사용자 진입점 |
| orino BE API | api.orino.dev |
FE가 의존 |
Alloy/Grafana 등 관측성 자체는 SLO 대상 아님(내부 도구).
| SLI | 정의 | 목표 SLO | 에러 예산 (월) |
|---|---|---|---|
| 가용성 | 5xx가 아닌 응답 / 전체 응답 | 99.0% | 월 7시간 18분 |
| 지연 | p95 요청 지연 | < 500ms (95% of time) | 월 약 36시간 |
근거:
- 개인 플랫폼: 99.9%는 과도 (1인 운영자 대응 시간 고려)
- 99%면 월 다운타임 ~7h 허용 → 운영 피로도↓
- 학습·사용 패턴 쌓이면서 목표 상향
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").
단순 "현재 에러율 > 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 평가.
Grafana에 "SLO 대시보드" 구축 필요:
- 현재 SLI 값
- 월간 남은 에러 예산 (%, 시간)
- 시간대별 에러율 추이
- burn rate 현재값
- 목표 대비 over/under 기간
Sloth 등 SLO generator 도구로 PrometheusRule·대시보드 자동 생성 검토.
현상: 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 블록)
§10.3 참조. 인프라 레벨 알림(Pod/Node)은 구축됐으나 BE 애플리케이션·Istio RED 메트릭 알림 부재.
관련 이슈: wcorn/orino#300
§11 설계 기준의 PrometheusRule·대시보드 미구축 상태.
관련 이슈: wcorn/orino#301 (#300 일부 의존)
- 코드·배포:
-
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 에러 트래킹
-
- 문서:
- Infra-Architecture — GitOps·Helm 구조
- BE-Architecture — 애플리케이션 구조
- Environment-Config — profile별 설정
- 외부: