> ## Documentation Index
> Fetch the complete documentation index at: https://control.datarelay.run/llms.txt
> Use this file to discover all available pages before exploring further.

# 전송 장애 진단과 복구

> HTTP 503 장애를 안전하게 재현하고 Route 실패 원인 및 복구 후 수신 결과를 검증합니다.

# Destination 전송 장애 발생 시 조치

**목표:** 테스트 Destination을 HTTP 503으로 만들어 실제 실패 로그를 확인하고, 수신기를 복구하여 정상 전달을 증명합니다.

> [!NOTE]
>
> **화면 버전:** 표시된 이미지는 과거 Control UI 테스트 캡처입니다. 현재 제품의 기본 5단계 순서(Connect → Sample & Record Selection → Destinations → Route Processing → Deploy)를 우선하세요. [번호별 화면 가이드](https://control.datarelay.run/ko/use-cases/screen-walkthrough.md)에서 차이를 설명합니다.

## 적용 순서

이 사례는 이미 구성된 Connector·Destination·Stream을 전제로 합니다. 아직 생성하지 않았다면 [커넥터별 수집 가이드](https://control.datarelay.run/ko/use-cases/index.md)에서 먼저 수집 Source를 설정하세요. 이후 이 페이지의 구체적인 단계를 수행하고 **실제 Logs와 Destination/격리 기록**을 검증합니다. 화면 캡처는 기존 테스트 증빙으로, 실제 결과를 대신하지 않습니다.

## 사전 조건

[Webhook 첫 이벤트 전송](https://control.datarelay.run/ko/use-cases/webhook-first-flow.md)을 완료해 9011 포트 수신기에서 HTTP 200과 수신 파일을 확인한 상태입니다. **운영 Destination에서는 장애를 재현하지 않습니다.**

## 1. 테스트용 HTTP 503 생성

1. 실습 수신기를 `Ctrl+C`로 종료합니다.
2. 다음과 같이 503 응답 모드로 재시작합니다.

```bash theme={null}
python3 scenario_receiver.py --port 9011 --status 503 --output received-9011.ndjson
```

3. 동일한 Control Receiver URL로 새 이벤트를 보냅니다.

```bash theme={null}
curl --fail-with-body -X POST "$CONTROL_RECEIVER_URL" \
  -H 'Content-Type: application/json' \
  --data '{"id":"delivery-fail-001","message":"controlled failure test"}'
```

**중요:** Webhook **Ingest**가 2xx를 응답하더라도 하위 **Destination Delivery**가 실패할 수 있습니다. 각각 따로 확인합니다.

## 2. 문제 발생 Route 찾기

1. **Dashboard**에서 전송 상태에 Warning/Critical 또는 실패 징후가 있는지 확인합니다.
2. **Data Flows / Routes** (`/routes`)에서 영향을 받은 Stream, Route, Destination을 선택합니다.
3. **Logs** (`/logs`)에서 해당 Stream, Route, 시간 범위, 실패 Status를 필터링합니다.
4. 실패 항목의 Detail을 열고 **Run ID, Route ID, Stage, HTTP 503/오류, Retry/Failure Policy, 실패 시각**을 기록합니다.
5. 지원되는 Stream Runtime/Checkpoint 화면에서 미처리 상태를 확인합니다. Ingest 성공만으로 Checkpoint가 진행되었다고 단정하지 않습니다.

![dashboard-triage — numbered Control historical UI capture](https://mintcdn.com/datarelay-control/Tl9_UibGAprPlCr8/images/screenshots/annotated/dashboard-triage.webp?fit=max\&auto=format\&n=Tl9_UibGAprPlCr8\&q=85\&s=f9c658cdeaa4638d8010ca10721745f1)

*그림 1. **Dashboard에서 장애 Stream 추적 시작.** ① 조회 기간을 설정하고 ② Health의 Critical/Warning을 확인한 다음 ③ Recent Alerts를 열어 영향 범위를 찾습니다. 근본 원인은 Streams·Routes·Logs에서 확인합니다.*

## 3. 수신기 복구

1. 실패 응답 수신기를 종료합니다.
2. HTTP 200 모드로 다시 실행합니다.

```bash theme={null}
python3 scenario_receiver.py --port 9011 --status 200 --output received-9011.ndjson
```

3. `delivery-recovered-001`처럼 새로운 ID의 이벤트를 전송합니다.
4. `received-9011.ndjson`에 이벤트가 기록되고 Logs에서도 동일한 Route가 성공 처리되었는지 확인합니다.

## 4. 이전 실패 건의 처리 판단

Control의 실제 Retry/Queue/Replay 결과를 먼저 확인합니다. **이미 자동 재시도에 의해 전송된 이벤트를 다시 Replay하지 않습니다.** Replay가 필요하다면 권한, 중복 처리 방식, 수신 시스템 영향을 검토한 후 수행합니다.

Route Delivery 설정의 Failover 구성을 사용하는 경우에도, 하나의 수신기 복구만으로 자동 Failover가 증명되지는 않습니다. Failover 검증은 별도 대체 목적지의 실제 수신까지 확인해야 합니다.

## 완료 조건

실패 당시의 **HTTP 503/Route 실패 증거**, 복구 뒤의 **HTTP 200/실제 수신 파일**, **성공 Route 로그**가 확인되어야 합니다. 이전 실패 이벤트는 Delivered/Queued/Dropped/Unresolved 중 **증거로 확인한 실제 상태**로 분류합니다.

## 실패 시

* 실패 로그가 없음: Stream/Route 실행 여부 및 자동 Retry 여부 확인
* 복구했지만 수신 없음: Destination URL, Enabled, 수신 IP/방화벽, 파일 확인
* Dashboard만 성공: 정확한 Run/Event ID로 Logs와 수신기 데이터 재검증
* Analytics 링크의 필터가 사라짐: 현재 개발 E2E에서 일반 Dashboard로 Redirect된 문제가 있으므로 Logs에서 직접 필터링합니다. [#413](https://github.com/datarelay-labs/datarelay-control/issues/413)

**관련:** [Logs 증빙](https://control.datarelay.run/ko/use-cases/logs-audit.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.