Skip to main content

​
개요

Search 도메인은 Elasticsearch 기반의 로그 저장 기능을 제공합니다. 시스템 로그, 사용자 활동 로그 등을 Elasticsearch에 저장하여 빠른 검색과 분석을 가능하게 합니다.

​
Types

​
JSON / JSONObject

JSON 데이터를 나타내는 스칼라 타입입니다.
​
JSON
Scalar
모든 JSON 타입 (객체, 배열, 문자열, 숫자, 불리언, null)
​
JSONObject
Scalar
JSON 객체 타입만 허용

​
ElasticResult (Enum)

Elasticsearch 작업 결과를 나타냅니다.
  • created: 새로운 문서가 생성됨
  • updated: 기존 문서가 업데이트됨
  • deleted: 문서가 삭제됨
  • not_found: 문서를 찾을 수 없음
  • noop: 변경 사항 없음

​
ErrorCause

Elasticsearch 에러 원인 정보를 나타냅니다.
​
type
String
에러 타입
​
reason
String
에러 원인
​
stack_trace
String
스택 트레이스
​
caused_by
ErrorCause
직접적인 원인
​
root_cause
[ErrorCause]
근본 원인 목록
​
suppressed
[ErrorCause]
억제된 에러 목록

​
ShardFailure

샤드 실패 정보를 나타냅니다.
​
index
String
인덱스 이름
​
node
String
노드 ID
​
reason
ErrorCause
실패 원인
​
shard
Int
샤드 번호
​
status
String
HTTP 상태 코드

​
ShardStatistics

샤드 통계 정보를 나타냅니다.
​
failed
Int
실패한 샤드 수
​
successful
Int
성공한 샤드 수
​
total
Int
전체 샤드 수
​
failures
[ShardFailure]
실패 상세 정보
​
skipped
Int
건너뛴 샤드 수

​
Mutations

​
addElasticSearchLog

Elasticsearch에 로그 문서를 저장합니다.

​
GraphQL Signature

mutation AddElasticSearchLog($index: String!, $doc: JSON!) {
  addElasticSearchLog(index: $index, doc: $doc)
}

​
파라미터

​
index
String!
required
Elasticsearch 인덱스 이름인덱스 명명 규칙:
  • 소문자만 사용
  • 하이픈(-)으로 단어 구분
  • 날짜 기반 인덱스: logs-YYYY-MM-DD
  • 기능별 인덱스: user-activity, system-events 등
​
doc
JSON!
required
저장할 JSON 문서문서에는 다음 필드를 포함하는 것을 권장:
  • timestamp: 로그 발생 시각 (ISO 8601 형식)
  • level: 로그 레벨 (info, warn, error 등)
  • message: 로그 메시지
  • userId: 관련 사용자 ID (있는 경우)
  • accommodationId: 관련 숙박 시설 ID (있는 경우)

​
응답

​
result
Boolean
저장 성공 여부

​
예제

mutation {
  addElasticSearchLog(
    index: "user-activity"
    doc: {
      timestamp: "2025-01-10T15:30:00Z"
      level: "info"
      action: "user_login"
      userId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
      ip: "192.168.1.100"
      userAgent: "Mozilla/5.0..."
      message: "User logged in successfully"
    }
  )
}

​
사용 사례

​
사용자 활동 추적

사용자의 로그인, 로그아웃, 페이지 방문 등을 기록합니다. 
mutation {
  addElasticSearchLog(
    index: "user-activity"
    doc: {
      timestamp: "2025-01-10T15:30:00Z"
      level: "info"
      action: "page_view"
      userId: "01HQKS9V8X"
      page: "/reservations"
      referrer: "/dashboard"
      duration: 1234
    }
  )
}

​
시스템 이벤트 로깅

예약 생성, 수정, 취소 등의 중요 이벤트를 기록합니다. 
mutation {
  addElasticSearchLog(
    index: "system-events"
    doc: {
      timestamp: "2025-01-10T15:35:00Z"
      level: "info"
      event: "payment_completed"
      paymentId: "01HQKS9V8X"
      amount: 150000
      currency: "KRW"
      method: "card"
      userId: "01HQKS9V8X"
    }
  )
}

​
에러 및 예외 추적

시스템 에러와 예외 상황을 상세히 기록합니다. 
mutation {
  addElasticSearchLog(
    index: "error-logs"
    doc: {
      timestamp: "2025-01-10T15:40:00Z"
      level: "error"
      error: "ValidationError"
      message: "Invalid email format"
      field: "email"
      value: "invalid-email"
      userId: "01HQKS9V8X"
      endpoint: "/api/users/signup"
    }
  )
}

​
성능 모니터링

API 응답 시간 및 성능 지표를 기록합니다. 
mutation {
  addElasticSearchLog(
    index: "performance-metrics"
    doc: {
      timestamp: "2025-01-10T15:45:00Z"
      level: "info"
      metric: "api_response_time"
      endpoint: "/graphql"
      operation: "getReservations"
      duration: 234
      userId: "01HQKS9V8X"
      status: 200
    }
  )
}

​
인덱스 명명 규칙

​
기능별 인덱스

  • user-activity: 사용자 활동 로그
  • reservation-events: 예약 관련 이벤트
  • payment-events: 결제 관련 이벤트
  • system-events: 시스템 이벤트
  • error-logs: 에러 및 예외 로그
  • performance-metrics: 성능 지표
  • audit-logs: 감사 로그

​
날짜 기반 인덱스

대량의 로그를 관리하는 경우 날짜별로 인덱스를 분리합니다.
  • logs-2025-01-10: 2025년 1월 10일 로그
  • user-activity-2025-01: 2025년 1월 사용자 활동 로그

​
권장 필드

모든 로그 문서에 다음 필드를 포함하는 것을 권장합니다:

​
필수 필드

​
timestamp
String
required
로그 발생 시각 (ISO 8601 형식)예: "2025-01-10T15:30:00Z"
​
level
String
required
로그 레벨
  • debug: 디버깅 정보
  • info: 일반 정보
  • warn: 경고
  • error: 에러
  • fatal: 치명적 에러
​
message
String
required
로그 메시지 (사람이 읽을 수 있는 형태)

​
선택 필드

​
userId
String
관련 사용자 ID
​
accommodationId
String
관련 숙박 시설 ID
​
requestId
String
요청 추적 ID (분산 추적용)
​
ip
String
클라이언트 IP 주소
​
userAgent
String
클라이언트 User-Agent

​
에러 처리

​
인덱스 생성 실패

존재하지 않는 인덱스에 문서를 추가하면 Elasticsearch가 자동으로 인덱스를 생성합니다. 단, 인덱스 이름이 유효해야 합니다. 유효하지 않은 인덱스 이름:
  • 대문자 포함: UserActivity (❌)
  • 특수문자 포함: user_activity* (❌)
  • 공백 포함: user activity (❌)
유효한 인덱스 이름:
  • user-activity (✅)
  • logs-2025-01-10 (✅)
  • reservation.events (✅)

​
문서 크기 제한

Elasticsearch는 기본적으로 100MB까지의 문서를 지원하지만, 대부분의 로그는 1MB 이하로 유지하는 것을 권장합니다.

​
타임아웃

대량의 데이터를 한 번에 저장하는 경우 타임아웃이 발생할 수 있습니다. 이 경우 벌크 API 사용을 고려하세요.

​
베스트 프랙티스

​
1. 구조화된 로그

JSON 형식으로 구조화된 로그를 사용하여 검색 및 분석을 용이하게 합니다. 
{
  "timestamp": "2025-01-10T15:30:00Z",
  "level": "info",
  "service": "user-svc",
  "action": "user_login",
  "userId": "01HQKS9V8X",
  "ip": "192.168.1.100",
  "success": true
}

​
2. 일관된 필드명

동일한 타입의 데이터는 일관된 필드명을 사용합니다.
  • userId (✅), user_id (❌), uid (❌)
  • timestamp (✅), time (❌), createdAt (❌)

​
3. 적절한 로그 레벨

  • debug: 개발 및 디버깅용
  • info: 정상적인 동작 기록
  • warn: 잠재적 문제
  • error: 에러 발생 (복구 가능)
  • fatal: 치명적 에러 (복구 불가능)

​
4. 민감 정보 제외

비밀번호, 개인정보, API 키 등 민감한 정보는 로그에 포함하지 않습니다. 
// ❌ 나쁜 예
{
  "password": "mysecretpassword",
  "creditCard": "1234-5678-9012-3456"
}

// ✅ 좋은 예
{
  "passwordChanged": true,
  "paymentMethodLast4": "3456"
}

​
5. 인덱스 라이프사이클 관리

오래된 로그는 정기적으로 삭제하거나 아카이브하여 스토리지를 관리합니다.

​
관련 API