작성일: 2026-09-30 · 수정일: 2026-10-01
적용 범위: v1 (v2·v3는 6. 향후 버전 계획 참고)

핵심 사용자 여정의 품질을 측정하고, 목표 수준과 장애 대응 기준을 정하기 위한 문서입니다. 사용자 기대와 운영 여건을 고려해 소수의 지표부터 시작합니다.

다먹자의 핵심 사용자 여정은 재고 등록 → 아침 유통기한 알림 → 재고 조회 → 직접 소비 또는 추천 요리 활용입니다.

flowchart TD
    manual["수동 등록 · v1"] --> inventory["재고 저장"]
    receipt["영수증 촬영·AI 등록 · v2"] --> inventory
    photo["실물 촬영·AI 등록 · v3"] --> inventory
    inventory --> morning["아침 유통기한 알림 · v1"]
    morning --> gen["08:00 알림 생성 · v1"]
    gen --> v1poll["v1 · 폴링으로 알림 확인"]
    gen --> v1push["v1 · Push 수신"]
    morning -.-> v2["v2 · SSE + Push, 재접속 시 Catch-up"]
    v1poll --> notice["임박·만료 물품 확인"]
    v1push --> notice
    v2 -.-> notice
    notice --> list["오늘까지인 재고 조회 · v1"]
    list --> choice{"재고 활용 방법"}
    choice -->|"바로 소비"| direct["과자·음료 등 직접 소비"]
    choice -->|"요리에 활용 · v3"| recommend["재고 기반 요리 추천"]
    recommend --> recipe["레시피 확인·요리 적용"]
    recipe --> consume["레시피 기준 재고 소비 처리"]
    classDef base fill:#e8f1ff,stroke:#4175b5,color:#172b4d;
    classDef added fill:#e8f5e9,stroke:#4b8651,color:#16391a;
    classDef future fill:#fff1dc,stroke:#ad7927,color:#51340a;
    class manual,inventory,morning,gen,v1poll,v1push,notice,list,choice,direct base;
    class receipt,v2 added;
    class photo,recommend,recipe,consume future;

R = /api/v1/refrigerators/{refrigerator-id} 로 줄여 씁니다. 대부분의 API가 냉장고 경로 아래에 있어 같은 접두 경로가 반복되므로, 표를 짧게 해 API별 차이(끝 경로)가 잘 보이게 하기 위함입니다. 대신 실제 호출 경로는 R을 펼쳐 읽어야 합니다.

여러 API로 이어지는 사용자 작업은 한 건으로 집계합니다.

측정하지 않는 API

• 단건 재고 등록(POST R/ingredient): API는 있지만 FE에서 호출하지 않아 정상 사용자의 여정에 포함되지 않습니다. 5xx는 일반 오류 모니터링으로 확인합니다.
• 보조 관측 대상: 직접 소비(POST /api/v1/ingredients/{ingredient-id}), Push 구독(POST /api/v1/push-subscriptions)은 목표 없이 성공률·응답시간만 관찰합니다.

공통 계산 기준

• 성공률은 성공 건수 ÷ 평가 대상 건수로 계산합니다.
• 여러 구간을 합칠 때는 구간별 비율을 평균하지 않고, 성공 건수와 평가 대상 건수를 각각 더한 뒤 나눕니다. p95·p99도 구간별 값을 평균하지 않고 전체 측정값에서 다시 계산합니다.
• 판정은 HTTP 응답 코드로만 합니다. 응답 내용이 맞는지는 판정하지 않습니다.

4xx 제외

4xx 요청은 없었던 요청처럼 보고 성공률을 계산합니다.

4xx를 실패로 세면 95%, 성공으로 세면 99%가 됩니다. 제외하면 4xx는 성공률을 올리지도 내리지도 않습니다.

• 이유: 4xx는 잘못된 입력·권한 없음 등 클라이언트 요청에서 비롯되며, 악의적으로 부하를 넣은 요청처럼 의도된 실패도 4xx로 돌아옵니다. 서버는 정상 사용자의 실수와 의도된 실패를 구분할 수 없으므로, 4xx를 실패로 세면 서비스 품질과 무관한 요청이 SLO를 깎게 됩니다.
• 트레이드오프: 외부 요인으로 SLO가 흔들리지 않는 대신, 서버 버그나 인증 장애로 잘못 발생한 4xx(예: 정상 사용자에게 401·404 대량 발생)도 SLO에 드러나지 않습니다. 4xx는 코드별 건수를 별도로 집계하고, 평소보다 급증하면 원인을 확인합니다.

시간 초과·연결 실패

flowchart LR
    U(["사용자"]) --- Z1["사용자 ↔ Nginx<br/>회선 불량 · DNS·TLS 실패 · AWS 장애<br/>평가 제외 (Sentry로 건수만 관측)"]
    Z1 --- N(["Nginx"])
    N --- Z2["Nginx ↔ BE<br/>502 BE 다운·재배포<br/>504 BE 응답 지연<br/>실패"]
    Z2 --- BE(["BE"])
    BE --- Z3["BE 내부<br/>500 DB 연결 시간 초과 · 처리 중 예외<br/>실패"]
    Z3 --- DB(["DB"])
    classDef excluded fill:#eeeeee,stroke:#888888,color:#333333;
    classDef failure fill:#fde2e1,stroke:#c0504d,color:#5a1a18;
    class Z1 excluded;
    class Z2,Z3 failure;

• 사용자 ↔ Nginx 구간을 제외하는 이유: v1은 Route 53에서 Nginx로 바로 연결되므로 이 구간에서 우리 쪽 책임인 장애는 AWS 장애 뿐입니다. 반면 이 구간의 실패는 대부분 사용자의 인터넷 미연결·약한 회선 같은 외부 요인이며, 클라이언트 기록만으로는 둘을 구분하기 어렵습니다.
• 트레이드오프: 서버 기록(Nginx·BE)만으로 판정해 기준이 명확하고 사용자 환경 문제가 섞이지 않습니다. 대신 요청이 서버까지 오지 못하는 드문 장애는 성공률에 드러나지 않으므로, Sentry에서 짧은 시간에 여러 사용자의 네트워크 오류가 동시에 늘어나는지로 확인합니다.

응답 코드 기반 판정의 한계

서버가 2xx로 응답했지만 결과가 잘못된 경우는 성공으로 집계됩니다.

• 트레이드오프: 서버 기록으로 바로 집계할 수 있어 기준이 명확하고 구현 부담이 적은 대신, 조용히 틀리는 문제는 SLO에 드러나지 않아 테스트·QA·사용자 제보로 찾아야 합니다.
• 고도화 여지: 결과를 대조하기 쉬운 항목부터 판정에 추가할 수 있습니다(예: 아침 알림 대상 수와 실제 생성 수, 등록 요청 건수와 실제 저장 건수 비교).

판정 기준

• 서버 기록으로 판정하며, 사용자 기기가 알림을 받거나 확인한 시각은 고려하지 않습니다. 08:01까지 계획한 발송을 지키지 못하면 실패입니다.
• 사용자별 알림을 한 건으로 세고, 여러 기기 중 하나만 Push 접수에 성공해도 성공입니다.
• Push 대상 사용자(활성 Push 기기가 있고 만료 알림 수신을 켠 사용자)는 알림 생성과 Push 접수가 모두 성공해야 성공입니다. 그 외 사용자는 알림 생성만으로 판정합니다.

flowchart TD
    A{"08:01까지 알림 생성?"} -->|아니오| F["실패"]
    A -->|예| B{"Push 대상 사용자?<br/>활성 Push 기기 + 만료 알림 수신 켬"}
    B -->|아니오| S["성공"]
    B -->|예| C{"Push 발송 결과<br/>사용자의 기기 중 하나라도"}
    C -->|"ACCEPTED (08:01까지 접수)"| S
    C -->|"CANCELLED (구독 만료 · 수신자 사용 불가)"| X["평가 제외"]
    C -->|"FAILED 또는 08:01 이후 접수"| F
    classDef ok fill:#e3f2e1,stroke:#4b8651,color:#16391a;
    classDef ng fill:#fde2e1,stroke:#c0504d,color:#5a1a18;
    classDef ex fill:#eeeeee,stroke:#888888,color:#333333;
    class S ok;
    class F ng;
    class X ex;

• 알림 생성 성공: 08:01까지 알림이 생성되어 폴링으로 조회할 수 있는 상태
• Push 접수 성공: 브라우저 푸시 서비스(Chrome은 FCM, Safari는 Apple, Firefox는 Mozilla)가 2xx로 접수한 상태. 기기 도착을 의미하지는 않습니다.

트레이드오프: 서버 발송 기록만으로 판정해 기준이 명확하고 Push 장애가 SLO에 바로 드러납니다. 대신 브라우저 푸시 서비스 자체의 장애처럼 우리 쪽 원인이 아닌 접수 실패도 실패로 집계되고, 서버가 제시간에 보냈더라도 사용자가 늦게 받는 경우는 드러나지 않습니다.

Push 발송 기록별 판정

• 제외 이유: 4xx를 평가에서 제외하는 원칙을 따릅니다. 구독은 사용자가 알림 권한을 해제하거나 브라우저 데이터를 지우는 등 사용자 쪽 원인으로 사라지고, 발송 직전 탈퇴·수신 끔은 사용자의 선택입니다.
• 트레이드오프: 사용자 쪽 원인이 오류 예산을 깎지 않는 대신, VAPID 키를 잘못 교체하는 등 우리 실수로 구독이 대량 무효화되는 경우가 드러나지 않습니다. SUBSCRIPTION_UNAVAILABLE 건수를 별도로 집계하고 급증하면 원인을 확인합니다.
• 한계: 발송 기록에 푸시 서비스의 HTTP 상태 코드는 저장되지 않으므로, 404·410 외의 4xx(예: 400·403)는 5xx와 같은 SEND_FAILED로 기록되어 실패로 집계됩니다.

발송 흐름과 집계 시 유의점

flowchart LR
    subgraph ONTIME["정시 구간 (08:00 ~ 08:01): 성공 인정"]
        T0["08:00<br/>배치 시작"] --> T1["알림 생성<br/>냉장고별"] --> T2["Push 1차 발송<br/>기기별"]
    end
    T2 --> CUT{{"08:01<br/>정시 기준"}}
    subgraph LATE["정시 이후: 접수돼도 정시 기준으로는 실패"]
        R1["재시도 1<br/>약 08:05"] --> R2["재시도 2<br/>약 08:20"] --> R3["재시도 3<br/>약 08:50"] --> DL["12:00<br/>발송 마감"]
    end
    CUT -->|"1차 실패 시"| R1
    classDef cut fill:#fff1dc,stroke:#ad7927,color:#51340a;
    class CUT cut;
    style ONTIME fill:#e3f2e1,stroke:#4b8651
    style LATE fill:#fde2e1,stroke:#c0504d

• 08:00 배치가 냉장고별로 알림을 생성한 뒤, 생성된 알림을 기준으로 기기별 Push를 발송합니다. 알림 생성에 실패하면 Push도 발송되지 않습니다.
• Push 실패 시 직전 실패 시점부터 5분·15분·30분 뒤에 차례로 재시도하고(1차 실패가 08:00이면 약 08:05·08:20·08:50), 정오가 지나면 중단합니다. 첫 재시도가 5분 뒤이므로 재시도로 접수돼도 정시 기준으로는 실패입니다.
• 알림 생성에 실패한 냉장고는 DB에 남지 않고 배치 로그(failedRefrigeratorCount)에만 남습니다. 발송 시도 건수만 평가 대상으로 잡으면 대상 누락을 놓치므로, 전체 대상 수는 배치 로그에서 함께 가져옵니다.

알림 대상 재고

• 유통기한이 지난 재고는 사용자가 치울 때까지 매일 만료 알림에 포함됩니다. 치우지 않은 재고를 치우도록 알리는 것이 목적입니다.
• 수량이 0인 재고는 존재하지 않습니다. 남은 양이 0이 되면 재고가 삭제되고, 등록·수정 시에도 수량은 1 이상(무게는 0 초과)만 허용됩니다.
• 알림은 08:00 배치가 조회한 시점의 재고로 만들며, 이후의 재고 변경은 당일 알림에 반영되지 않습니다. 발송 직전 재고를 다시 확인하는 등 고도화 여지가 있습니다.

알려진 한계 (클라이언트)

• 화면 표시 지연: 폴링 간격이 30초이므로 알림이 화면에 표시되기까지 최대 약 30초가 걸릴 수 있으며, 이는 서버 기준 SLO에 포함하지 않습니다.
• 폴링 중단: 폴링 요청이 재시도 후에도 실패하면 폴링이 멈추고, 사용자가 탭을 전환해 돌아올 때 재개됩니다. 발송 직전 서버가 잠깐 5xx를 반환하면, 서버가 정시에 알림을 생성했더라도 탭 전환 전까지 화면에 표시되지 않을 수 있습니다.

EC2의 로그를 CloudWatch Logs로 수집하고, 지표 필터(Metric Filter)로 실시간 집계합니다.

flowchart LR
    subgraph EC2["EC2"]
        NG["Nginx 접근 로그"]
        BL["BE 로그"]
        BT["08:00 배치 로그"]
    end
    NG & BL & BT --> AG["CloudWatch Agent"]
    AG -->|"약 5초"| CL["CloudWatch Logs"]
    CL -->|"지표 필터 · 1분"| CM["CloudWatch 지표<br/>응답 코드별 건수"]
    DB[("DB<br/>알림·Push 발송 기록")]
    SE["Sentry<br/>브라우저 응답시간"]
    CM -->|"작업 성공률"| M["월 합산 · SLO 판정"]
    CL -->|"알림 대상 수"| M
    DB -->|"아침 알림"| M
    SE -->|"응답시간"| M

• 1분 주기를 선택한 이유: 지표 필터는 로그가 도착할 때마다 평가하지만 지표 값은 1분 단위로 기록하므로, 코드 수정 없이 얻을 수 있는 가장 짧은 주기입니다. 장애가 나면 약 1~2분 안에 지표에 반영됩니다.
• 트레이드오프: 1초 단위 집계는 BE 로그 형식을 바꾸거나(EMF) 지표를 직접 보내야(PutMetricData) 하므로 채택하지 않았습니다. 또한 지표 필터는 조건별 건수만 셀 수 있어, 4xx 제외·API별 분리처럼 조건이 늘어나면 필터도 그만큼 늘어납니다.
• 보관: CloudWatch는 지표를 15일 이내 1분, 63일 이내 5분, 455일 이내 1시간 해상도로 보관합니다. 해상도가 줄어도 합계는 유지되므로 월간 합산에는 영향이 없습니다.

평가 기간은 **한국 시간 기준 달력 월(매월 1일 00:00 이상, 다음 달 1일 00:00 미만)**입니다. 월간 비율은 일별 비율의 평균이 아니라 건수를 합산해 계산합니다.

응답시간은 평가 대상의 95% 이상이 1초 이내, 99% 이상이 10초 이내라는 두 조건으로 관리하며, 등록과 조회를 각각 평가합니다. 응답시간 목표와 성공률 목표는 서로 대신하지 않고 각각 평가합니다.

4xx 응답은 성공률과 같이 응답시간 집계에서도 제외합니다.

• 이유: 악의적으로 부하를 넣은 요청은 대부분 4xx로 돌아오며, 서버는 이를 정상 요청과 구분할 수 없습니다. 4xx를 포함하면 이런 요청 때문에 응답시간 지표가 어쩔 수 없이 나빠지므로 이를 막기 위해 제외합니다.
• 트레이드오프: 외부 요청으로 지표가 흔들리지 않는 대신, 정상 사용자가 받은 4xx 응답이 느렸던 경우(예: 인증 처리 지연 후 401)는 응답시간 지표에 드러나지 않습니다.

초기 서비스 단계에서는 운영 데이터가 없고 트래픽이 적으므로 현실적으로 지킬 수 있는 95%에서 시작합니다. 운영 데이터가 쌓이면 실제 성공률을 보고 목표를 높입니다.

• 트레이드오프: 목표가 느슨해 초기 장애나 재배포 중단으로 SLO가 쉽게 깨지지 않고, 오류 예산을 실제 개선 우선순위 판단에 쓸 수 있습니다(예: 월 1,000건이면 실패 50건까지 허용). 대신 월 5%의 실패까지 허용하므로 작은 품질 저하는 SLO에 드러나지 않습니다. 이를 보완하기 위해 5xx 건수는 별도로 관찰하고, 목표는 운영 데이터를 바탕으로 단계적으로 높입니다.
• 참고: IBM은 높은 중요도의 시스템에서 99.9% 또는 99.99% 가용성을 고려할 수 있다고 설명합니다. 다먹자는 초기 단계이므로 이 수준을 장기 목표로 두고, 처음에는 낮은 목표로 시작합니다.

Jakob Nielsen이 정리한 응답시간 한계(Usability Engineering, 1993)를 근거로 합니다.

• 트레이드오프: 사용자 인지에 근거해 "왜 1초인가"를 설명할 수 있지만, 웹·모바일 네트워크 환경을 전제로 한 연구가 아니며 적용 비율(95%, 99%)은 프로젝트의 설계 결정입니다.
• 검증: 측정 시작 후 2~4주간의 실제 응답시간으로 목표가 현실적인지 확인합니다. 측정값이 기준보다 나쁘면 목표를 낮추기보다 개선 과제로 다룹니다.
• 참고: Google Core Web Vitals의 INP는 입력 후 첫 반응이 그려지기까지를 p75 기준 200ms 이하면 "좋음"으로 봅니다. 다먹자 목표(API 요청부터 응답 수신까지)와 측정 범위가 달라 목표 수치로는 쓰지 않습니다.

FE에 설정된 Sentry의 성능 측정(Tracing)이 자동으로 기록하는 API 요청 구간(http.client)을 사용합니다.

아래 다이어그램에서 파란 영역이 측정 구간입니다. 수동 재고 등록을 예로 들었으며, 재고 조회도 같은 방식입니다.

sequenceDiagram
    actor U as 사용자
    participant B as 브라우저(FE)
    participant N as Nginx
    participant BE as BE
    participant DB as DB

    U->>B: 등록 버튼 클릭
    Note over U,B: 측정 제외: 입력 처리

    rect rgba(66, 133, 244, 0.18)
        Note over B,DB: 측정 구간 (Sentry http.client)
        B->>N: POST R/ingredients 요청 전송 ① 측정 시작
        Note over B,N: DNS 조회·TLS 연결·네트워크 전송
        N->>BE: 요청 전달
        BE->>DB: 재고 저장
        DB-->>BE: 저장 완료
        BE-->>N: 201 응답
        N-->>B: 201 응답 수신 ② 측정 완료
    end

    B->>U: 등록 완료 팝업 표시
    Note over U,B: 측정 제외: 화면 그리기

• 완료 시점을 응답 수신으로 정한 이유: 등록 요청에 응답이 오면 곧바로 등록 완료 팝업이 뜨므로, 응답 수신이 사용자가 결과를 확인하는 시점과 거의 같습니다. 화면을 그리는 시간은 포함하지 않으며, FE에 기능별 측정 구간을 추가하면 화면 반영 완료까지 측정할 수 있습니다.
• 장점: 사용자 기기에서 재므로 DNS·TLS 연결, 네트워크 왕복, BE 처리 시간이 모두 포함되고, 같은 기기의 시계로 재므로 서버와의 시계 차이 영향이 없습니다. 이미 설정된 Sentry를 쓰므로 수집 서버나 코드 수정이 필요 없습니다.
• 단점: prod는 10%만 샘플링하므로 트래픽이 적은 초기에는 측정값이 부족할 수 있습니다. 데이터가 Sentry 안에 있어 4xx 제외 같은 계산 규칙을 자유롭게 적용하기 어렵고, 측정값을 보내기 전에 탭을 닫거나 오프라인이 되면 값이 빠집니다.
• 운영상 한계: Sentry는 14일 무료 체험 계정 하나를 팀원이 함께 사용합니다. 비용 문제로 멤버 초대가 불가능해 생긴 한계로, 누가 설정을 바꿨는지 추적할 수 없고 체험 기간이 끝나면 무료 플랜의 사용량·보관 기간 제한을 받습니다.

검토했지만 채택하지 않은 방식

SLO 미달을 대응 기준으로 삼되, 운영자 알림의 발생 조건·심각도·수신자·대응·복구 조건은 별도 알림 설계에서 정합니다. 월말 최종 판정과 운영 중 조기 경보는 구분하며, 월간 SLO가 깨질 때까지 기다리지 않습니다.

아래는 v2·v3 설계 방향이며, 세부 기준은 해당 버전 착수 시 확정합니다.

v2 아침 알림: SSE + Web Push + Catch-up

목표는 v1과 같이 월간 95%, KST 08:01 기준입니다. 배치·Pub/Sub 기반으로 발송하며, ACK 식별 범위·대기 시간과 SSE·Push 결과의 판정 규칙을 정해야 합니다.

AI 재고 등록(영수증 v2, 실물 v3)

POST /api/v1/image-analyses → GET /api/v1/image-analyses/{analysisId} → POST R/ingredients 흐름을 하나의 등록 기능으로 측정합니다. 접수(202)·조회(200)만으로 성공 처리하지 않고 인식 결과와 최종 저장까지 확인합니다.

품질 평가에는 대표 사진, 사람이 확인한 정답, 값의 정규화 규칙이 필요하며, 평가셋·모델·프롬프트 버전을 기록합니다. confidence나 사용자 무수정 비율을 정답률로 대신하지 않습니다.

요리 추천·레시피 기반 소비 처리(v3)

레시피 기반 소비 처리는 추천 레시피를 기준으로 재고를 사용했다고 간주하며, 실제 조리·섭취 여부와 다릅니다. 사용자가 요리하거나 섭취하지 않아 생기는 상황은 서비스 장애에 포함하지 않습니다.

• 다먹자 API 명세서 — API 경로·동작과 재고 API 응답 코드 정의
• IBM: What is high availability? — 높은 중요도 시스템의 가용성 수준(장기 목표 참고)
• Jakob Nielsen, NN/G: Response Times: The 3 Important Limits — 1초·10초 응답시간 목표 근거
• web.dev: Interaction to Next Paint (INP) — INP 측정 범위와 기준
• IETF: RFC 8030 — Generic Event Delivery Using HTTP Push — Web Push 접수 응답과 기기 전달의 구분
• AWS: CloudWatch Agent 설정 파일 — 로그 전송 주기 기본값
• AWS: Metrics concepts — 지표 해상도와 보관 기간
• AWS: High resolution metric extraction from structured logs — 1초 단위 집계 조건(EMF)
• 어다희·천기철, LY Corporation: 신뢰성 향상을 위한 SLI/SLO 도입 1편 — 사용자 여정 중심의 지표 설계
• Google SRE: Implementing SLOs — 지표 정의와 목표 설정
• Google SRE: Example SLO Document — 측정값 기반 목표 설정 사례
• Google SRE: Alerting on SLOs — 오류 예산 기반 알림
• Google SRE: Data Processing Pipelines — 처리 파이프라인의 정확성 목표(v2·v3)
• Google Cloud: Evaluate performance — 정밀도·재현율 평가(v2·v3)