검색 (Elasticsearch)

개요

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

Types

JSON / JSONObject

JSON 데이터를 나타내는 스칼라 타입입니다.

Scalar

모든 JSON 타입 (객체, 배열, 문자열, 숫자, 불리언, null)

Scalar

JSON 객체 타입만 허용

ElasticResult (Enum)

Elasticsearch 작업 결과를 나타냅니다.

created: 새로운 문서가 생성됨
updated: 기존 문서가 업데이트됨
deleted: 문서가 삭제됨
not_found: 문서를 찾을 수 없음
noop: 변경 사항 없음

ErrorCause

Elasticsearch 에러 원인 정보를 나타냅니다.

String

에러 타입

String

에러 원인

String

스택 트레이스

ErrorCause

직접적인 원인

[ErrorCause]

근본 원인 목록

[ErrorCause]

억제된 에러 목록

ShardFailure

샤드 실패 정보를 나타냅니다.

String

인덱스 이름

String

노드 ID

ErrorCause

실패 원인

Int

샤드 번호

String

HTTP 상태 코드

ShardStatistics

샤드 통계 정보를 나타냅니다.

Int

실패한 샤드 수

Int

성공한 샤드 수

Int

전체 샤드 수

[ShardFailure]

실패 상세 정보

Int

건너뛴 샤드 수

Mutations

addElasticSearchLog

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

GraphQL Signature

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

파라미터

String!

required

Elasticsearch 인덱스 이름인덱스 명명 규칙:

소문자만 사용
하이픈(-)으로 단어 구분
날짜 기반 인덱스: logs-YYYY-MM-DD
기능별 인덱스: user-activity, system-events 등

JSON!

required

저장할 JSON 문서문서에는 다음 필드를 포함하는 것을 권장:

timestamp: 로그 발생 시각 (ISO 8601 형식)
level: 로그 레벨 (info, warn, error 등)
message: 로그 메시지
userId: 관련 사용자 ID (있는 경우)
accommodationId: 관련 숙박 시설 ID (있는 경우)

응답

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: "reservation-events"
    doc: {
      timestamp: "2025-01-10T15:35:00Z"
      level: "info"
      event: "reservation_created"
      reservationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
      accommodationId: "01HQKS9V8X"
      userId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
      guestName: "홍길동"
      checkIn: "2025-01-20"
      checkOut: "2025-01-22"
      message: "New reservation created"
    }
  )
}

mutation {
  addElasticSearchLog(
    index: "error-logs"
    doc: {
      timestamp: "2025-01-10T15:40:00Z"
      level: "error"
      error: "DatabaseConnectionError"
      message: "Failed to connect to database"
      stack: "Error: Connection timeout\n  at Database.connect..."
      userId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
      endpoint: "/api/reservations"
      method: "POST"
    }
  )
}

{
  "data": {
    "addElasticSearchLog": true
  }
}

사용 사례

사용자 활동 추적

사용자의 로그인, 로그아웃, 페이지 방문 등을 기록합니다.

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월 사용자 활동 로그

권장 필드

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

필수 필드

String

required

로그 발생 시각 (ISO 8601 형식)예: "2025-01-10T15:30:00Z"

String

required

로그 레벨

debug: 디버깅 정보
info: 일반 정보
warn: 경고
error: 에러
fatal: 치명적 에러

String

required

로그 메시지 (사람이 읽을 수 있는 형태)

선택 필드

String

에러 처리

인덱스 생성 실패

존재하지 않는 인덱스에 문서를 추가하면 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. 인덱스 라이프사이클 관리

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

​개요

​Types

​JSON / JSONObject

​ElasticResult (Enum)

​ErrorCause

​ShardFailure

​ShardStatistics

​Mutations

​addElasticSearchLog

​GraphQL Signature

​파라미터

​응답

​예제

​사용 사례

​사용자 활동 추적

​시스템 이벤트 로깅

​에러 및 예외 추적

​성능 모니터링

​인덱스 명명 규칙

​기능별 인덱스

​날짜 기반 인덱스

​권장 필드

​필수 필드

​선택 필드

​에러 처리

​인덱스 생성 실패

​문서 크기 제한

​타임아웃

​베스트 프랙티스

​1. 구조화된 로그

​2. 일관된 필드명

​3. 적절한 로그 레벨

​4. 민감 정보 제외

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

​관련 API

개요

Types

JSON / JSONObject

ElasticResult (Enum)

ErrorCause

ShardFailure

ShardStatistics

Mutations

addElasticSearchLog

GraphQL Signature

파라미터

응답

예제

사용 사례

사용자 활동 추적

시스템 이벤트 로깅

에러 및 예외 추적

성능 모니터링

인덱스 명명 규칙

기능별 인덱스

날짜 기반 인덱스

권장 필드

필수 필드

선택 필드

에러 처리

인덱스 생성 실패

문서 크기 제한

타임아웃

베스트 프랙티스

1. 구조화된 로그

2. 일관된 필드명

3. 적절한 로그 레벨

4. 민감 정보 제외

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

관련 API