logging-best-practices은(는) 무엇을 하나요?
강력한 디버깅 및 분석을 위한 와이드 이벤트(표준 로그 라인) 중심의 로깅 모범 사례
와이드 이벤트(표준 로그 라인)는 각 사용자 요청에 대한 모든 관련 정보(메타데이터, 타이밍, 오류 등)를 단일 구조화된 로그 라인에 캡처하는 로깅 접근 방식입니다. 이는 전통적인 여러 개별 로그 메시지와 달리 요청 수명 주기의 전체 컨텍스트를 제공합니다.
핵심 개념
- 와이드 이벤트: 요청당 하나의 풍부하고 구조화된 로그 라인
- 구조화된 로깅: JSON 또는 protobuf와 같은 기계 판독 가능 형식 사용
- 컨텍스트 리치: 로그마다 관련 메타데이터, 타이밍, 오류 포함
모범 사례
-
요청당 하나의 와이드 이벤트 로깅: 각 사용자 요청에 대해 시작 및 완료 시 단일 로그 라인을 생성합니다. 여기에는 요청 ID, 사용자 ID, 작업, 지연 시간, 상태, 오류 코드가 포함됩니다.
-
표준 스키마 사용: 일관된 필드 이름(예:
event_type,duration_ms,status_code)을 정의합니다. 이는 로그 검색 및 집계를 단순화합니다. -
PII(개인 식별 정보) 방지: 로그에 민감한 사용자 데이터가 포함되지 않도록 합니다. 필요한 경우 마스킹 또는 해싱을 사용합니다.
-
ELK Stack 또는 유사 시스템으로 중앙 집중화: 모든 로그를 Elasticsearch, Loki, 또는 CloudWatch Logs와 같은 중앙 저장소로 전송합니다. 검색 및 시각화를 지원하는 도구를 사용합니다.
-
로깅 수준 사용:
ERROR,WARN,INFO,DEBUG를 적절히 사용합니다. 와이드 이벤트는 일반적으로INFO수준입니다. -
컨텍스트 전파: 분산 시스템에서
trace_id,span_id와 같은 상관관계 ID를 포함합니다.
예시 (구조화된 JSON 로그)
{
"timestamp": "2025-03-20T10:30:00Z",
"level": "INFO",
"event_type": "request",
"request_id": "abc-123",
"user_id": "user_456",
"action": "create_order",
"duration_ms": 234,
"status_code": 200,
"error_code": null,
"metadata": {
"source_ip": "192.168.1.1",
"user_agent": "Mozilla/5.0",
"region": "us-east-1"
}
}
일반적인 함정
- 너무 많은 이벤트: 값비싼 또는 디버그 전용 로그를 과도하게 기록하지 마십시오. 와이드 이벤트는 풍부하지만 드물어야 합니다.
- 동기식 로깅: 성능에 영향을 미칩니다. 비동기 로깅을 사용하여 지연 시간을 피하십시오.
- 구조화 부족: 간단한 문자열은 분석을 어렵게 만듭니다. 항상 구조화된 형식을 선호하십시오.
- 회전 정책 무시: 로그 보존 및 크기 한도를 올바르게 구성하십시오.
도구 및 플랫폼
- 수집: Fluentd, Logstash, Vector
- 저장소: Elasticsearch, Loki, CloudWatch Logs, BigQuery
- 대시보드: Grafana, Kibana
- 경고: Prometheus + Alertmanager, Opsgenie
참조
- The Wide Event Logging Pattern (canonical log lines) - 관찰 가능성 엔지니어링 서적
- 12 Factor App - Logs - 로그를 이벤트 스트림으로 처리
- ELK Stack 문서 - Elasticsearch, Logstash, Kibana
- OpenTelemetry 로깅 - 로깅 표준
- CloudWatch Logs 모범 사례 - AWS 로깅 가이드