본문으로 건너뛰기

로깅 표준 및 가이드라인

개요​

DTA-WIDE 시스템에서는 다양한 유형의 로그를 수집하고 관리합니다. 이 문서에서는 시스템 전반의 로깅 표준, 특히 HTTP API 요청 로깅에 대한 가이드라인을 제공합니다.

로그 유형​

1. 애플리케이션 로그​

  • 일반 애플리케이션 동작 로그
  • 에러 및 경고 로그
  • 디버그 로그

2. HTTP API 요청 로그​

  • API 엔드포인트 접근 로그
  • 요청/응답 정보 로그
  • 성능 메트릭 로그

3. 감사 로그​

  • 비즈니스 중요 이벤트 로그
  • 보안 관련 활동 로그
  • 규정 준수 감사 로그

4. 인프라 로그​

  • 시스템 리소스 로그
  • 네트워크 활동 로그
  • 배포 및 구성 변경 로그

HTTP API 요청 로깅​

로깅 목적​

HTTP API 요청 로깅의 주요 목적:

  • 시스템 사용 패턴 파악
  • 성능 모니터링 및 최적화
  • 문제 해결 및 디버깅
  • 보안 모니터링 및 이상 탐지
  • 사용량 분석 및 용량 계획

로깅 구조​

기본 로그 필드​

HTTP API 요청 로그의 기본 필드:

필드설명예시
timestamp요청 발생 시간1679471431000
request_id고유 요청 식별자req-1234-5678-90ab-cdef
methodHTTP 메서드GET, POST, PUT, DELETE
path요청 경로/v1/users/123
query_params쿼리 파라미터{"limit":"20","offset":"0"}
user_id요청 사용자 IDuser_123 (인증된 경우)
client_ip클라이언트 IP 주소192.168.1.1
user_agent사용자 에이전트Mozilla/5.0 (Windows...)
status_codeHTTP 상태 코드200, 400, 500
response_time응답 시간(ms)42
request_size요청 크기(바이트)1024
response_size응답 크기(바이트)2048
correlation_id요청 추적 IDcorr-1234-5678

상세 로그 필드 (선택적)​

필요에 따라 추가할 수 있는 상세 필드:

필드설명예시
request_headers요청 헤더{"content-type":"application/json"}
request_body요청 본문 (민감 정보 제외){"name":"John Doe"}
response_headers응답 헤더{"content-type":"application/json"}
response_body응답 본문 (요약){"id":"user_123","name":"John"}
error_details오류 세부 정보{"code":"DB_001","message":"DB conn failed"}

BigQuery 테이블 구조​

CREATE TABLE `dta-cloud-de-ENVIRONMENT.log.api_requests` (
  timestamp TIMESTAMP(3),
  request_id STRING,
  method STRING,
  path STRING,
  query_params JSON,
  user_id STRING,
  client_ip STRING,
  user_agent STRING,
  status_code INT64,
  response_time INT64,
  request_size INT64,
  response_size INT64,
  correlation_id STRING,
  request_headers JSON,
  error_details JSON,
  service STRING,
  environment STRING
)
PARTITION BY DATE(timestamp)
CLUSTER BY method, path, status_code;

HTTP 요청 로그와 감사 로그의 관계​

HTTP API 요청 로그와 감사 로그는 서로 다른 목적을 가지지만 상호 보완적입니다:

특성HTTP API 요청 로그감사 로그
목적기술적 모니터링, 디버깅비즈니스 이벤트 추적, 규정 준수
범위모든 API 요청중요한 비즈니스 이벤트
상세도기술적 상세 정보비즈니스 컨텍스트
사용자개발자, 운영팀보안팀, 규정 준수팀, 비즈니스 관계자
보존일반적으로 더 짧음규정에 따라 장기간

연계 방법​

HTTP API 요청과 감사 로그를 연결하기 위해 다음 방법을 사용합니다:

  1. 상관 관계 ID(Correlation ID): 모든 HTTP 요청과 그로부터 생성된 감사 로그에 동일한 상관 관계 ID를 포함
  2. 요청 ID(Request ID): HTTP 요청의 고유 식별자를 감사 로그의 참조 필드로 저장
  3. 세션 ID: 사용자 세션을 기반으로 HTTP 요청과 감사 로그를 그룹화

구현 예시:​

// HTTP 요청에서 감사 로그 생성
@Post()
async createResource(@Req() request, @Body() data) {
  // 리소스 생성 로직
  const resource = await this.service.create(data);
  
  // 감사 로그 생성
  await this.auditService.createAuditLog({
    eventType: 'RESOURCE_CREATED',
    source: 'resource-service',
    actor: {
      type: 'USER',
      id: request.user.id,
      name: request.user.name
    },
    target: {
      type: 'RESOURCE',
      id: resource.id,
      name: resource.name
    },
    action: 'CREATE',
    details: { resourceType: resource.type },
    metadata: {
      correlationId: request.headers['x-correlation-id'],
      requestId: request.headers['x-request-id'],
      ipAddress: request.ip,
      userAgent: request.headers['user-agent'],
      sessionId: request.headers['x-session-id']
    },
    status: 'SUCCESS'
  });
  
  return resource;
}

변경 이력​

버전날짜작성자변경 내용
0.1.02025-03-29bok@weltcorp.com최초 작성
0.2.02025-03-30bok@weltcorp.comCoreLoggingModule 통합 추가