docs: add robeing-monitor monitoring architecture
This commit is contained in:
Claude-51124
parent
6667a5c752
commit
c7f226118c
219
300_architecture/325_robeing_monitor_모니터링_아키텍처.md
Normal file
219
300_architecture/325_robeing_monitor_모니터링_아키텍처.md
Normal file
@ -0,0 +1,219 @@
|
||||
# Robeing Monitor 모니터링 아키텍처
|
||||
|
||||
## 1. 목적
|
||||
|
||||
- **역할 한 줄 요약**: `robeing-monitor`는 로빙/스킬/컨테이너에서 발생하는 상태·이벤트·리소스 데이터를 **관찰(수집)·기록(저장)·표시(조회/대시보드 제공)** 하는 중앙 모니터링 백엔드이다.
|
||||
- 이 문서는 **현재 인프라 구조에서 robeing-monitor가 담당할 모니터링 책임 범위**와,
|
||||
**각 서비스가 어떤 형식으로 데이터를 제공해야 하는지(계약)** 를 정의한다.
|
||||
|
||||
---
|
||||
|
||||
## 2. 인프라 구조 요약 (현재 기준)
|
||||
|
||||
### 2.1 서버 배치
|
||||
|
||||
| 서버 | IP | 주요 서비스 | 포트 | 역할 |
|
||||
|------|----|------------|------|------|
|
||||
| 51123 | 192.168.219.45 | nginx, Gitea, auth-server, robeing-gateway | 80, 443, 3000, 8100 | 외부 진입, 인증, 프록시 |
|
||||
| 51124 | 192.168.219.52 | rb8001, rb10508_micro, robeing-monitor, skill-* | 8001, 10508, 9024, 85xx | 로빙/스킬/모니터링 실행 |
|
||||
|
||||
> 상세 구조: `310_전체_시스템_구조_컨테이너와_마이크로서비스.md`,
|
||||
> Slack 경유 플로우: `320_Slack_기반_인터페이스_설계.md` 참조.
|
||||
|
||||
### 2.2 모니터링 관련 데이터 흐름 (요약)
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph UserSide[사용자 측]
|
||||
U[사용자\nSlack / Web UI]
|
||||
end
|
||||
|
||||
subgraph Frontend[51123]
|
||||
G[robeing-gateway (8100)]
|
||||
end
|
||||
|
||||
subgraph Backend[51124]
|
||||
RB8001[rb8001 (8001)\n프로덕션 로빙]
|
||||
RB10508[rb10508_micro (10508)\nSlack 이벤트 처리]
|
||||
Skills[skill-* (85xx)\n뉴스/이메일 등]
|
||||
Monitor[robeing-monitor (9024)\n이 문서의 주인공]
|
||||
end
|
||||
|
||||
subgraph Storage[데이터 저장소]
|
||||
PG[(PostgreSQL\nrobeing_stats 등)]
|
||||
Chroma[(ChromaDB\n벡터 메모리)]
|
||||
OS[(OpenSearch\nDataprepper-static)]
|
||||
end
|
||||
|
||||
U -->|요청/이벤트| G -->|프록시| RB8001
|
||||
G --> RB10508
|
||||
|
||||
RB8001 -->|상태/이벤트 전송| Monitor
|
||||
RB10508 -->|상태/이벤트 전송| Monitor
|
||||
Skills -->|상태/이벤트 전송| Monitor
|
||||
|
||||
Monitor -->|스탯/로그 기록| PG
|
||||
Monitor -->|메모리 기록| Chroma
|
||||
Monitor -->|표준 로그/메트릭| OS
|
||||
|
||||
U -->|대시보드 조회| G --> Monitor
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Robeing Monitor의 책임 범위
|
||||
|
||||
### 3.1 책임 한 눈에 보기
|
||||
|
||||
- **수집(Observe)**: rb8001, rb10508_micro, skill-* 등에서 발생하는 **상태 변화, 요청/응답 이벤트, 리소스 사용량**을 표준 형태로 수집한다.
|
||||
- **기록(Record)**: 수집한 데이터를 **PostgreSQL/ChromaDB/OpenSearch**에 일관된 스키마로 저장한다.
|
||||
- **표시(Show)**: `/api/stats/*`, `/api/memory/*`, `/api/monitor/*` API를 통해 **현재 상태 + 히스토리 + 집계**를 제공한다.
|
||||
- **알림(Notify, 선택)**: 향후에는 에러율/응답시간/특정 에러 패턴을 기준으로 **알람 트리거**를 보내는 역할까지 확장 가능하다.
|
||||
|
||||
### 3.2 “하지 않는 일”
|
||||
|
||||
- 비즈니스 로직(예: 이메일 실제 발송, 뉴스 수집, Slack 응답 생성)을 **대신 수행하지 않는다.**
|
||||
- LLM 추론/대화 생성/의도 분류를 **대신 수행하지 않는다.**
|
||||
- 오케스트레이션(워크플로우 실행)을 **중앙에서 모두 담당하지 않는다.**
|
||||
(단, 모니터링용으로 “어떤 워크플로우가 언제 어떻게 실패했는지”를 기록하는 것은 책임 범위 안이다.)
|
||||
|
||||
> 요약: robeing-monitor는 **“관찰자 + 기록자 + 리포터”** 역할에 집중한다.
|
||||
|
||||
---
|
||||
|
||||
## 4. 데이터 모델 및 계약(Contract)
|
||||
|
||||
### 4.1 공통 식별자 규칙
|
||||
|
||||
- **robeing_id**: `rb8001`, `rb10508_micro` 등 로빙/컨테이너 단위 ID.
|
||||
- **user_uuid**: Slack ID → UUID 변환 규칙에 따른 사용자 UUID.
|
||||
- 변환 규칙: `250817_robeing_monitor_integration.md`의 namespace UUID 사용.
|
||||
- **request_id**: 게이트웨이/서비스별로 생성하는 요청 단위 추적 ID (예: UUID4 문자열).
|
||||
|
||||
모든 서비스(rb8001, rb10508_micro, skill-*)는 **로깅/모니터링 대상 이벤트**에 대해
|
||||
다음 필드를 **가능한 한 포함**하는 것을 원칙으로 한다.
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "2025-11-16T15:28:15.199Z",
|
||||
"robeing_id": "rb8001",
|
||||
"user_uuid": "…",
|
||||
"request_id": "…",
|
||||
"channel": "Slack 채널 ID 또는 Web UI 세션 ID",
|
||||
"event_type": "llm_call | skill_call | scheduler_job | health_check | error",
|
||||
"status": "success | error | timeout",
|
||||
"latency_ms": 1234,
|
||||
"meta": {
|
||||
"intent": "email_send",
|
||||
"skill_name": "skill-email",
|
||||
"http_status": 200
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 Robeing Monitor 내부 저장소 역할
|
||||
|
||||
- **PostgreSQL**
|
||||
- `robeing_stats`: 로빙 스탯(레벨, memory/compute/empathy/leadership 등) 기록.
|
||||
- `robeing_stats_history` (제안): 일정 주기/이벤트 기반 스냅샷 저장.
|
||||
- `gmail_token`, `gmail_audit_logs` 등 기존 토큰/감사 로그 테이블.
|
||||
- **ChromaDB**
|
||||
- 각 유저별/로빙별 벡터 메모리 저장 (`rb8001_{user_uuid}`, `rb8001_{user_uuid}_memory` 등).
|
||||
- 장기적으로 “모니터링용 메타데이터(예: 요약된 세션 상태)”도 저장 가능.
|
||||
- **OpenSearch (`dataprepper-static`)**
|
||||
- Fluent Bit → Data Prepper를 통해 들어오는 **표준화된 JSON 로그/메트릭** 저장.
|
||||
- 운영 대시보드/알람의 주요 데이터 소스.
|
||||
|
||||
---
|
||||
|
||||
## 5. 각 서비스와의 연동 규칙
|
||||
|
||||
### 5.1 rb8001 (프로덕션 로빙, 포트 8001)
|
||||
|
||||
- **해야 할 일**
|
||||
- LLM 호출, 스킬 호출, 주요 사용자 액션에 대해 **위 4.1의 공통 필드 기반 로그**를 남긴다.
|
||||
- 정기적으로(또는 이벤트 기반으로) robeing-monitor의 다음 API를 호출해 **스탯/상태 동기화**:
|
||||
- `PUT /api/stats/{robeing_id}` – 레벨/스탯 업데이트
|
||||
- `POST /api/logs/{robeing_id}` – 대화/이벤트 로그 저장
|
||||
- `POST /api/memory/{robeing_id}/store` – 중요 메모리 저장
|
||||
- **robeing-monitor가 제공해야 할 것**
|
||||
- `GET /api/stats/{robeing_id}` – 현재 스탯(프론트/Slack에서 사용).
|
||||
- `GET /api/stats/{robeing_id}/history` – 성장 히스토리(그래프용).
|
||||
- `GET /api/logs/{robeing_id}/stats` – 대화 통계(요청 수, 실패율 등).
|
||||
|
||||
### 5.2 rb10508_micro (Slack 이벤트 처리)
|
||||
|
||||
- Slack 기반 아키텍처: `320_Slack_기반_인터페이스_설계.md` 참조.
|
||||
- **해야 할 일**
|
||||
- Slack 이벤트 처리 시, **사용자/채널/의도/처리 결과**를 robeing-monitor로 기록:
|
||||
- `POST /api/logs/{robeing_id}` – conversation_log 스타일로 기록.
|
||||
- 에러/타임아웃 발생 시 `status="error"`와 함께 원인 코드를 남긴다.
|
||||
- **robeing-monitor가 제공해야 할 것**
|
||||
- Slack 운영 대시보드에서 사용할 “사용자별/채널별 사용량, 스킬 사용 통계” 쿼리 API.
|
||||
|
||||
### 5.3 skill-* (이메일, 뉴스, Slack, RAG 등)
|
||||
|
||||
- **해야 할 일**
|
||||
- 각 스킬이 수행하는 주요 작업(예: 이메일 발송/뉴스 수집/RAG 검색)에 대해
|
||||
**요청 수, 성공/실패, 지연 시간, 외부 API 에러**를 robeing-monitor 또는 OpenSearch에 기록.
|
||||
- 스킬 자체 헬스 상태를 robeing-monitor가 주기적으로 조회할 수 있도록 `/health`를 제공.
|
||||
- **robeing-monitor가 제공해야 할 것**
|
||||
- `GET /api/monitor/skills` – 스킬별 헬스/에러율/응답시간 요약.
|
||||
- 향후: `GET /api/monitor/resources` – 스킬 컨테이너별 CPU/메모리/디스크 사용량.
|
||||
|
||||
---
|
||||
|
||||
## 6. “보여주기(대시보드)”를 위한 설계
|
||||
|
||||
### 6.1 운영자용(엔지니어) 뷰
|
||||
|
||||
- **도구**: OpenSearch Dashboards
|
||||
- **데이터 소스**: `dataprepper-static` 인덱스
|
||||
- **주요 화면**
|
||||
- 서비스별 로그 검색(robeing_id / container_name 필터).
|
||||
- 에러 패턴(“Event loop is closed”, “never awaited” 등) 트렌드 그래프.
|
||||
- 응답시간/에러율 타임시리즈.
|
||||
|
||||
### 6.2 제품/운영용 뷰
|
||||
|
||||
- **도구**: `robeing-monitor` 전용 Web UI 또는 기존 프론트 내 “운영 대시보드” 페이지.
|
||||
- **데이터 소스**: `robeing-monitor` API (`/api/stats/*`, `/api/monitor/*` 등)
|
||||
- **주요 화면**
|
||||
- 로빙별 성장 그래프(레벨/스탯 히스토리).
|
||||
- 사용자/워크스페이스별 사용량/성공률/스킬 사용 분포.
|
||||
- 스킬/서비스별 현재 헬스 상태와 최근 에러 요약.
|
||||
|
||||
### 6.3 역할 분리 원칙
|
||||
|
||||
- **OpenSearch 대시보드**: “원시 로그/에러 중심” 디버깅/장기 분석.
|
||||
- **robeing-monitor UI/API**: “도메인 친화적인 지표(레벨, 사용량, 성공률)” 중심 뷰.
|
||||
|
||||
---
|
||||
|
||||
## 7. 향후 개선 방향
|
||||
|
||||
- **로그 스키마 완전 표준화**
|
||||
- 모든 서비스에서 동일 필드명/타입 사용 (`robeing_id`, `user_uuid`, `request_id`, `event_type`, `status`, `latency_ms` 등).
|
||||
- Fluent Bit → Data Prepper 파이프라인에서 JSON 스키마 검증/정규화.
|
||||
|
||||
- **히스토리/집계 API 확장**
|
||||
- `/api/stats/{robeing_id}/history?from=...&to=...&interval=...`
|
||||
- `/api/monitor/overview`에 기간 필터/집계 옵션 추가.
|
||||
|
||||
- **알람 시스템 연동**
|
||||
- OpenSearch 쿼리 기반 알람 룰(에러율, 특정 메시지 패턴 등).
|
||||
- robeing-monitor 내부 스케줄러(APScheduler)를 활용한 주기적 점검 및 Slack 알림.
|
||||
|
||||
- **문서/코드 정합성 유지**
|
||||
- 새로 정의된 로깅 스키마/엔드포인트 변경 시,
|
||||
이 문서와 각 서비스 README를 **동시에 갱신**하는 것을 원칙으로 한다.
|
||||
|
||||
---
|
||||
|
||||
## 8. 요약 (운영 관점 3줄)
|
||||
|
||||
1. `robeing-monitor`는 **모든 로빙/스킬의 상태·이벤트·리소스 데이터를 중앙에서 모니터링하고 기록·표시하는 전담 백엔드**이다.
|
||||
2. 각 서비스는 공통 식별자(robeing_id/user_uuid/request_id)와 표준 로그 스키마를 따라 robeing-monitor/OpenSearch에 데이터를 보내야 한다.
|
||||
3. 운영자는 OpenSearch Dashboards(엔지니어용)와 robeing-monitor API/대시보드(제품/운영용)를 통해 현재 상태와 히스토리를 한눈에 볼 수 있게 된다.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user