📝

v1

WebSocket 연결 규칙

Base URL

wss://your-domain.com/api/ws
Plain Text
복사

프로토콜

•

개발 환경: ws:// (비암호화)

•

프로덕션: wss:// (TLS 암호화, 필수)

인증 방식

Query Parameter 방식 (권장)

wss://your-domain.com/api/ws/logs?token=Bearer_xxx
Plain Text
복사

Initial Message 방식 (대안)

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'Bearer_xxx'
  }));
};
JavaScript
복사

연결 수명 주기

┌─────────────┐
│  연결 시도   │
└──────┬──────┘
       │
       ▼
┌─────────────┐      인증 실패
│  인증 확인   │──────────────► 연결 거부
└──────┬──────┘
       │ 인증 성공
       ▼
┌─────────────┐
│  연결 성공   │◄──┐
└──────┬──────┘   │
       │          │
       ▼          │
┌─────────────┐   │
│ 데이터 수신  │   │
└──────┬──────┘   │
       │          │
       ▼          │
┌─────────────┐   │
│ 연결 유지?  │───┘ Yes
└──────┬──────┘
       │ No
       ▼
┌─────────────┐
│  연결 종료   │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  재연결 시도 │
└─────────────┘
Plain Text
복사

실시간 로그 스트리밍

Endpoint

wss://your-domain.com/api/ws/services/{service_name}/logs
Plain Text
복사

Path Parameters

파라미터	타입	필수	설명	예시
service_name	string		서비스명	"user-service"

Query Parameters

파라미터	타입	필수	설명	기본값
token	string		인증 토큰	-
level	string		로그 레벨 필터	"error"
search	string		메시지 검색어	-

로그 레벨 필터

레벨	설명	사용 예시
error	에러 로그만	장애 모니터링 (기본값)
warning	경고 로그만	잠재적 문제 추적
info	정보 로그만	일반 동작 확인
debug	디버그 로그만	개발/디버깅 용도
all	모든 레벨	전체 로그 스트림

연결 예시

// 에러 로그만 수신
const errorWs = new WebSocket(
  'wss://your-domain.com/api/ws/services/user-service/logs?token=Bearer_xxx&level=error'
);

// 모든 로그 수신
const allWs = new WebSocket(
  'wss://your-domain.com/api/ws/services/user-service/logs?token=Bearer_xxx&level=all'
);

// 특정 키워드 포함 로그만 수신
const searchWs = new WebSocket(
  'wss://your-domain.com/api/ws/services/user-service/logs?token=Bearer_xxx&search=database'
);
JavaScript
복사

메시지 포맷

기본 구조

{
  "type": "log",
  "service_name": "user-service",
  "timestamp": "2025-11-07T10:35:22.999Z",
  "data": {
    "log_id": "log_123abc",
    "level": "error",
    "message": "Database connection failed",
    "trace_id": "trace_abc123",
    "span_id": "span_002",
    "attributes": {
      "error.type": "ConnectionError",
      "database.host": "db-primary",
      "retry_count": 3
    }
  }
}
JSON
복사

필드 설명

필드	타입	설명
type	string	메시지 타입 (항상 "log")
service_name	string	로그를 생성한 서비스명
timestamp	string	로그 발생 시간 (ISO 8601)
data.log_id	string	로그 고유 ID
data.level	string	로그 레벨
data.message	string	로그 메시지
data.trace_id	string	연관된 트레이스 ID (옵션)
data.span_id	string	연관된 스팬 ID (옵션)
data.attributes	object	추가 메타데이터

실시간 알림

Endpoint

wss://your-domain.com/api/ws/notifications
Plain Text
복사

Query Parameters

파라미터	타입	필수	설명
token	string		인증 토큰
service	string		특정 서비스만 구독

연결 예시

// 모든 서비스의 알림 수신
const notificationWs = new WebSocket(
  'wss://your-domain.com/api/ws/notifications?token=Bearer_xxx'
);

// 특정 서비스의 알림만 수신
const serviceNotificationWs = new WebSocket(
  'wss://your-domain.com/api/ws/notifications?token=Bearer_xxx&service=user-service'
);
JavaScript
복사

알림 유형

유형	설명	심각도
error_spike	에러율 급증	critical
latency_spike	레이턴시 급증	warning
service_down	서비스 다운	critical
deployment	새 배포 완료	info
error_new	새로운 에러 발생	warning
threshold_exceeded	임계값 초과	warning

메시지 포맷

기본 구조

{
  "type": "notification",
  "notification_id": "notif_abc123",
  "timestamp": "2025-11-07T10:35:22.123Z",
  "data": {
    "notification_type": "error_spike",
    "severity": "critical",
    "title": "에러율 급증 감지",
    "message": "user-service의 에러율이 5%를 초과했습니다 (현재: 12.3%)",
    "service_name": "user-service",
    "metadata": {
      "current_error_rate": 12.3,
      "threshold": 5.0,
      "affected_endpoints": [
        "GET /api/users/:id",
        "POST /api/orders"
      ]
    },
    "action_url": "/services/user-service/errors"
  }
}
JSON
복사

참고

 연결 관리

UI 업데이트 전략(로그 스트리밍에 대해)

알림처리 참고 내용

 에러 처리

 구현 예시