# 실시간 이벤트 (SignalR)

> 라이브 대시보드를 구동하는 WebSocket 이벤트 스트림 — 허브 그룹, 이벤트 페이로드, 예측 타임스탬프 의미.

라이브 업데이트는 **`/hub/realtime`**의 단일 SignalR 허브를 통해 전달됩니다. 인증은 REST API와
동일한 JWT를 사용하며, `?access_token=<jwt>`(또는 `Authorization` 헤더)로 전달합니다.

이벤트 스트림은 **최대 1회(at-most-once) 및 발사 후 망각(fire-and-forget)** 방식입니다 —
결코 진실의 원천(source of truth)이 아닙니다. 연결 끊김 중에 놓친 이벤트는 재전송되지 않으며,
권위 있는 상태는 항상 REST API(`/api/inference/status`, `/api/system/status`)와 박스 내
데이터베이스에서 옵니다.

## 구독 그룹

고빈도 스트림은 그룹별로 선택 가입(opt-in)하며, 이를 소비하는 화면이 마운트된 동안에만
가입되고 재연결 시 자동으로 재가입됩니다:

| 그룹 | 전달 내용 | 소비 주체 |
|---|---|---|
| `sensors` | 라이브 센서 판독 배치 | Realtime Monitor |
| `predictions` | 새 예측 배치 | 대시보드 차트 |
| `logs` | 전체 로그 스트림(모든 레벨) | LogViewer 페이지 전용 |
| `alerts` | Warning/Error 로그 항목만 | 알림 벨, 앱 전역 |

`alerts` 그룹은 전체 `logs` 소방호스(firehose)를 모든 대시보드로 스트리밍하지 않고도 경고가
어디서나 표면화되도록 하기 위해 존재합니다.

## 이벤트 (서버 → 클라이언트)

| 이벤트 | 페이로드 하이라이트 |
|---|---|
| `SensorReading` | `channelIndex`, `value`, `timestamp` |
| `NewPrediction` | `predictions`, `confidenceScores`, `modelId`, `inferenceTimeMs`, 윈도우 타임스탬프(아래 참조) |
| `InferenceStateChanged` | `state` ∈ `idle · ready · running`, 활성 데이터소스, 로드된 모델 — 모든 수명 주기 전환마다 방출 |
| `InferenceFaulted` | `reason`, `datasourceId` — 차단성 장애 배너도 함께 표시 |
| `HealthMetricsUpdate` | CPU/GPU/메모리, 가동 시간 |
| `ModelActivated` | `modelId`, `version`, 형상, 파일 크기 |
| `ModelUploadProgress` | 업로드/검증 단계, 실패 시 오류 메시지 |
| `OutputWriteFailed` | 싱크별로 합쳐짐 — 즉각적인 첫 경고, 이후 30초 윈도우당 하나 |
| `LogEntryAdded` | 로그 항목(레벨, 메시지, 로거, 메타데이터) |

## 예측 타임스탬프 의미

예측은 입력의 *과거* 윈도우를 서술합니다. 모든 타임스탬프는 **하나의 시계**에서 나온 Unix
epoch 밀리초입니다 — 백엔드가 판독 시점에 각 샘플을 한 번만 찍고, 그 값이 파이프라인 전체로
반향되며 결코 재생성되지 않습니다:

| 필드 | 의미 |
|---|---|
| `windowStartTimestamp` | 윈도우에서 가장 오래된 입력 샘플 |
| `windowEndTimestamp` | 가장 최신 입력 샘플 — 예측이 유효한 "기준 시점" |
| `timestamp` | `windowEndTimestamp`를 미러링(호환성) |
| `emittedAt` | 방출 시점의 백엔드 벽시계 — `emittedAt − windowEndTimestamp` ≈ 엔드투엔드 지연 시간 |

대시보드에서 예측 트레이스는 실제 파이프라인 지연 시간만큼 센서 트레이스보다 눈에 띄게
**뒤따릅니다**. 그 간격은 렌더링 결함이 아니라 의도된 운영 신호입니다.

## 전달 보장

느린 소비자가 추론을 결코 스로틀하지 않습니다: 대시보드 브로드캐스트는 발사 후 망각 방식이며,
따라잡지 못하는 클라이언트로 향하는 이벤트는 드롭되고 카운트됩니다(`/api/inference/backpressure`).
알림 대상 이벤트는 중복 제거되고 속도 제한되어 벨을 유용하게 유지합니다 —
[알림](/ko/operate/notifications/)을 참조하세요.

## 다음 단계

  - [API 개요](/ko/api-reference/overview/) — REST 표면과 인증.
  - [모니터링](/ko/operate/monitoring/) — 이 이벤트들이 UI에서 도달하는 위치.
  - [알림](/ko/operate/notifications/) — 어떤 이벤트가 경보를 일으키고 무엇이 조용히 유지되는지.