From c7f226118c1002988658a04058216401648b1c7f Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Mon, 17 Nov 2025 01:04:19 +0900 Subject: [PATCH] docs: add robeing-monitor monitoring architecture --- ...being_monitor_모니터링_아키텍처.md | 219 ++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 300_architecture/325_robeing_monitor_모니터링_아키텍처.md diff --git a/300_architecture/325_robeing_monitor_모니터링_아키텍처.md b/300_architecture/325_robeing_monitor_모니터링_아키텍처.md new file mode 100644 index 0000000..62302da --- /dev/null +++ b/300_architecture/325_robeing_monitor_모니터링_아키텍처.md @@ -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/대시보드(제품/운영용)를 통해 현재 상태와 히스토리를 한눈에 볼 수 있게 된다. + +