ezar-logger

ezar-logger (EL)

Go 애플리케이션을 위한 경량 원격 로깅 패키지입니다. gRPC 클라이언트 지원, SHA256 기반 고유 로그 ID 생성, Reply 체인 기능, QA 메시지 기능을 제공합니다.

🚀 주요 기능

• gRPC 클라이언트: gRPC를 통한 원격 로깅 서비스 연동
• SHA256 기반 고유 ID: 타임스탬프를 포함한 단방향 암호화 로그 ID 생성
• Reply 체인 지원: Parent 참조를 통한 연관 로그 연결
• QA 메시지 지원: Channel과 Managers를 지정한 QA 전용 로그 전송
• 로그 ID 반환: 모든 로깅 함수가 생성된 로그 ID 반환
• 다양한 로그 레벨: INFO, WARN, ERROR, FATAL, QA 지원
• Type & Status: 로그 타입(MSG/REPLY)과 상태(PENDING) 자동 관리
• 스택 트레이스: 디버깅을 위한 내장 에러 추적 기능
• 환경별 동작: DEV/STAGE/PROD 환경에 따른 자동 설정
• 자동 TLS: 프로덕션 서버 연결 시 자동 TLS 적용

📦 설치

go get bitbucket.org/ezardev-admin/ezar-logger

🔧 요구사항

• Go 1.24 이상
• ezar-grpc v1.18.2 이상
• gRPC 로깅 서비스 네트워크 연결

📁 프로젝트 구조

ezar-logger/
├── el/                             # 메인 로거 패키지 (EL - Ezar Logger)
│   ├── el.go                       # 핵심 로깅 구현
│   ├── ql.go                       # QA 로깅 구현
│   └── el_test.go                  # 테스트 코드
├── internal/
│   ├── core/
│   │   └── clients/logger/         # gRPC 클라이언트
│   └── datasource/storage/docs/    # 데이터 모델
├── pkg/utils/                      # 유틸리티 함수
└── example/                        # 사용 예제

🚀 빠른 시작

1. 로거 초기화

package main

import (
    "bitbucket.org/ezardev-admin/ezar-logger/el"
)

func main() {
    // EL 로거 초기화
    // Mode: "PROD" -> 프로덕션 서버, "STAGE" -> 스테이지 서버, 그 외 -> 로컬 출력만
    el.InitLogger("#my-application", "PROD")
    
    // 로깅 시작 - 로그 ID 반환
    id := el.Info("애플리케이션 시작", "서버가 성공적으로 초기화되었습니다")
    el.Warn("높은 메모리 사용량", "메모리 사용량이 85%입니다")
    el.Error("데이터베이스 오류", "사용자 데이터베이스 연결 실패")
}

2. Reply 체인 사용법

package main

import (
    "bitbucket.org/ezardev-admin/ezar-logger/el"
)

func main() {
    el.InitLogger("#order-service", "PROD")
    
    // 초기 로그 전송 후 ID 획득
    parentId := el.Info("주문 생성", "새 주문 #12345가 생성되었습니다")
    
    // 부모 로그에 연결된 Reply 로그 전송
    el.ReplyInfo(parentId, "결제 처리 중", "주문 #12345 결제를 처리하고 있습니다")
    el.ReplyInfo(parentId, "주문 완료", "주문 #12345가 성공적으로 완료되었습니다")
    
    // 또는 커스텀 레벨로 Reply
    el.Reply(parentId, el.WARN, "재고 부족", "주문 후 재고가 부족해졌습니다")
}

3. QA 메시지 전송

package main

import (
    "bitbucket.org/ezardev-admin/ezar-logger/el"
)

func main() {
    el.InitLogger("#my-service", "PROD")
    
    // QA 메시지 전송 (채널과 담당자 지정)
    qaId := el.AskQA(
        "#qa-channel",                      // 채널
        []string{"manager1", "manager2"},   // 담당자 목록
        "버그 리포트",                        // 제목
        "결제 페이지에서 오류가 발생합니다",    // 상세 내용
    )
    
    // QA 메시지에 Reply
    el.ReplyQA(
        qaId,                               // 부모 QA 로그 ID
        "#qa-channel",                      // 채널
        []string{"manager1"},               // 담당자 목록
        "수정 완료",                          // 제목
        "결제 페이지 오류를 수정했습니다",      // 상세 내용
    )
}

4. 비프로덕션 모드 (로컬 개발)

el.InitLogger("#my-app", "DEV")  // "PROD" 외의 모든 모드

// 원격 서버로 전송되지 않고 stdout에 출력됩니다
el.Info("테스트", "이 메시지는 콘솔에 출력됩니다")
// 출력: INFO: 테스트 이 메시지는 콘솔에 출력됩니다

📊 로그 레벨

레벨	값	설명
el.INFO	0	애플리케이션 흐름에 대한 일반 정보
el.WARN	1	잠재적 문제에 대한 경고 메시지
el.ERROR	2	실패에 대한 오류 메시지
el.FATAL	3	심각한 오류
el.QA	4	QA 메시지

📄 데이터 모델

LogQue 구조체

type LogQue struct {
    ID        string    `json:"_id"`        // SHA256 해시: #앱이름-해시
    AppName   string    `json:"app_name"`   // 애플리케이션 이름
    Title     string    `json:"title"`      // 로그 제목/요약
    Detail    string    `json:"detail"`     // 상세 로그 메시지
    Status    string    `json:"status"`     // 로그 상태 (PENDING)
    Type      string    `json:"type"`       // 로그 타입 (MSG/REPLY)
    Parent    string    `json:"parent"`     // Reply용 부모 로그 ID
    Level     int       `json:"level"`      // 로그 레벨 (0-4)
    CreatedAt time.Time `json:"created_at"` // 타임스탬프
}

QaQueue 구조체

type QaQueue struct {
    *LogQue
    Channel  string   `json:"channel"`   // QA 채널
    Managers []string `json:"managers"`  // 담당자 목록
}

로그 타입

타입	설명
MSG	일반 로그 메시지
REPLY	기존 로그에 대한 답변 (부모 참조 포함)

🔧 API 레퍼런스

패키지: el

초기화

func InitLogger(appName string, mode string)

애플리케이션 이름과 모드로 전역 EL 로거를 초기화합니다.

파라미터:

• appName: 애플리케이션 이름 (예: "#my-service")
• mode: 환경 모드 ("PROD", "STAGE", 또는 로컬용 기타)

기본 로깅 함수

func Info(title string, detail string) string
func Warn(title string, detail string) string
func Error(title string, detail string) string
func Send(level LogLevel, title string, detail string) string

모든 로깅 함수는 생성된 로그 ID를 반환합니다.

Reply 함수

func ReplyInfo(parent string, title string, detail string) string
func ReplyWarn(parent string, title string, detail string) string
func ReplyError(parent string, title string, detail string) string
func Reply(parent string, level LogLevel, title string, detail string) string

Reply 함수는 로그를 부모 로그 ID에 연결합니다.

QA 함수

func AskQA(channel string, managers []string, title string, detail string) string
func SendQA(level LogLevel, channel string, managers []string, title string, detail string) string
func ReplyQA(parent string, channel string, managers []string, title string, detail string) string
func SendReplyQa(parent string, channel string, managers []string, level LogLevel, title string, detail string) string

QA 함수는 채널과 담당자를 지정하여 QA 전용 메시지를 전송합니다.

유틸리티 함수

func Trace(err ...error) string

디버깅을 위한 스택 트레이스 정보를 반환합니다.

🔐 고유 로그 ID 생성

EL 로거는 title:detail:timestamp의 SHA256 해시로 고유 ID를 생성합니다:

// 형식: #앱이름-해시 (SHA256 첫 8바이트의 16진수 문자 16개)
// 예시: #my-service-a1b2c3d4e5f6g7h8

장점:

• 고유성: 타임스탬프로 동일한 title+detail도 고유 ID 보장
• 추적성: 앱 이름 접두사로 쉬운 식별
• 간결함: 16자 해시로 가독성 확보

🌐 서버 설정

모드	서버
PROD	프로덕션 gRPC 서버 (자동 TLS)
STAGE	스테이징 gRPC 서버 (자동 TLS)
기타	로컬 stdout만 (원격 전송 없음)

🎯 사용 사례

애플리케이션 모니터링

id := el.Info("사용자 활동", "사용자 john.doe가 IP 192.168.1.100에서 로그인했습니다")
el.ReplyInfo(id, "세션 생성", "24시간 만료의 새 세션이 생성되었습니다")

컨텍스트가 있는 오류 추적

errId := el.Error("데이터베이스 연결", "주 데이터베이스 연결 실패")
el.ReplyWarn(errId, "폴백 활성화", "백업 데이터베이스로 전환되었습니다")
el.ReplyInfo(errId, "복구 완료", "주 데이터베이스 연결이 복구되었습니다")

비즈니스 프로세스 추적

orderId := el.Info("주문 생성", "고객 john@example.com의 새 주문 #12345")
el.ReplyInfo(orderId, "결제 시작", "결제 처리가 시작되었습니다")
el.ReplyInfo(orderId, "결제 성공", "$99.99 결제가 완료되었습니다")
el.ReplyInfo(orderId, "배송", "FedEx 운송장 #ABC123으로 배송되었습니다")

QA 이슈 추적

qaId := el.AskQA("#bug-report", []string{"dev-team"}, "UI 버그", "모바일에서 버튼이 표시되지 않습니다")
el.ReplyQA(qaId, "#bug-report", []string{"dev-team"}, "분석 중", "재현 환경을 확인하고 있습니다")
el.ReplyQA(qaId, "#bug-report", []string{"dev-team"}, "해결 완료", "CSS 수정으로 해결되었습니다")

🧪 테스트

go test ./el -v

---

🐍 Python 패키지

ezar-logger는 Python에서도 동일한 기능을 사용할 수 있습니다.

설치 (uv 사용)

# SSH 방식
uv pip install "ezar-logger @ git+ssh://git@bitbucket.org/ezardev-admin/ezar-logger.git#subdirectory=python"

# HTTPS 방식
uv pip install "ezar-logger @ git+https://bitbucket.org/ezardev-admin/ezar-logger.git#subdirectory=python"

pyproject.toml 의존성으로 추가

dependencies = [
    "ezar-logger @ git+ssh://git@bitbucket.org/ezardev-admin/ezar-logger.git#subdirectory=python",
]

Python 사용법

import ezar_logger as el

# 로거 초기화
el.init_logger("#my-app", "PROD")

# 기본 로그
log_id = el.info("작업 시작", "데이터 처리를 시작합니다")
el.warn("경고", "메모리 사용량이 높습니다")
el.error("오류", "데이터베이스 연결 실패")

# 응답 로그 (이전 로그에 연결)
el.reply_info(log_id, "작업 완료", "100건 처리 완료")
el.reply_warn(log_id, "부분 완료", "일부 항목 건너뜀")
el.reply_error(log_id, "작업 실패", "처리 중 오류 발생")

# 에러 로그와 스택 트레이스
try:
    raise ValueError("예시 오류")
except Exception as e:
    el.error("오류 발생", el.trace(e))

# QA 알림 (슬랙 채널과 담당자 지정)
el.ask_qa("qa-channel", ["@manager1", "@manager2"], "리뷰 요청", "PR #123 검토 부탁드립니다")
el.reply_qa(log_id, "qa-channel", ["@manager1"], "리뷰 완료", "승인되었습니다")

Python API 매핑

Go	Python
el.InitLogger()	el.init_logger()
el.Info()	el.info()
el.Warn()	el.warn()
el.Error()	el.error()
el.ReplyInfo()	el.reply_info()
el.ReplyWarn()	el.reply_warn()
el.ReplyError()	el.reply_error()
el.AskQA()	el.ask_qa()
el.ReplyQA()	el.reply_qa()
el.Trace()	el.trace()

자세한 Python 사용법은 python/README.md를 참조하세요.

📈 성능 특징

• 지연 연결: 첫 로그 전송 시 gRPC 연결 수립
• 자동 재연결: 연결 끊김 시 자동 재연결
• 30초 타임아웃: 안정성을 위한 설정 가능한 타임아웃
• 비차단 오류: 실패한 작업은 로컬에 로깅, 앱 크래시 없음

🔒 보안

• 단방향 암호화: 로그 ID는 SHA256 해싱 사용 (역산 불가)
• 자동 TLS: 프로덕션 서버(*.ezar.co.kr)에 TLS 자동 활성화
• 안전한 로깅: 실패한 작업은 stdout에 로깅

📝 변경 이력

v1.5.0

• QA 로그 레벨 추가
• AskQA, ReplyQA 함수 추가 (채널, 담당자 지정 가능)
• QaQueue 구조체 추가 (Channel, Managers 필드)
• gRPC LogQue 메시지에 channel, managers 필드 지원
• ezar-grpc v1.18.2로 업그레이드

v1.4.0

• 모든 로깅 함수(Info, Warn, Error)가 로그 ID 반환

v1.3.1

• Parent 필드를 통한 Reply 체인 지원 추가
• Type(MSG/REPLY)과 Status(PENDING) 필드 추가
• ezar-grpc v1.13.3으로 업그레이드
• UpdateLog 기능 제거

v1.3.0

• 초기 gRPC 클라이언트 구현
• SHA256 기반 고유 로그 ID
• 다중 환경 지원 (PROD/STAGE/DEV)

📄 라이선스

이 프로젝트는 MIT 라이선스로 제공됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

🆘 지원

• Bitbucket에서 이슈 생성
• 예제 및 테스트 파일 참조