roy-wonji/logmacro

**Swift 매크로를 활용한 고성능 로깅 라이브러리**

✨ 주요 특징

🚀 컴파일 타임 최적화 - Swift 매크로로 런타임 오버헤드 제거 🎯 직관적인 API - 매크로와 정적 메서드 두 가지 사용 방식 📱 iOS 12+ 완벽 지원 - 구버전까지 완벽 호환 🔧 OSLog 기반 - Apple의 공식 로깅 프레임워크 활용 🎨 다양한 로그 레벨 - Debug, Info, Network, Error, Test, Custom 지원 🔒 DEBUG 전용 - Release 빌드에서 자동으로 제거되어 성능 영향 없음

📚 상세 문서

📖 완전한 문서 보기 - 아키텍처, API 참조, 고급 사용법 🌐 온라인 문서) - 인터랙티브 API 문서

🛠 기술적 기반

이 라이브러리는 다음 기술들을 기반으로 구현되었습니다:

OSLog: Apple의 공식 통합 로깅 시스템
Swift Macros: Swift 5.9+ 매크로 시스템
SwiftSyntax: 구문 분석 및 코드 생성

📦 설치 방법

Swift Package Manager (권장)

Package.swift에 다음을 추가하세요:

let package = Package(
    name: "YourProject",
    dependencies: [
        .package(url: "https://github.com/Roy-wonji/LogMacro.git", from: "1.0.5")
    ],
    targets: [
        .target(
            name: "YourTarget",
            dependencies: ["LogMacro"]
        )
    ]
)

또는 Xcode에서 File → Add Package Dependencies...로 추가:

https://github.com/Roy-wonji/LogMacro.git

라이브러리 import

import LogMacro

🚀 빠른 시작

기본 사용법

LogMacro는 두 가지 방식으로 사용할 수 있습니다:

1️⃣ 매크로 방식 (권장)

#logDebug("디버깅 정보", userId, timestamp)
#logInfo("앱 시작됨", appVersion)
#logError("네트워크 오류", error.localizedDescription)

2️⃣ 정적 메서드 방식

Log.debug("디버깅 정보", userId, timestamp)
Log.info("앱 시작됨", appVersion)  
Log.error("네트워크 오류", error.localizedDescription)

📊 지원하는 로그 레벨

| 레벨 | 아이콘 | 매크로 | 정적 메서드 | 용도 | |------|--------|--------|-------------|------| | Debug | 🟡 | #logDebug | Log.debug | 개발 중 디버깅 정보 | | Info | 🟠 | #logInfo | Log.info | 일반적인 정보성 메시지 | | Network | 🔵 | #logNetwork | Log.network | 네트워크 관련 이벤트 | | Error | 🔴 | #logError | Log.error | 오류 및 예외 상황 | | Test | 🟡 | #logTest | Log.test | 테스트 실행 로그 | | Custom | 🟢 | #logCustom | Log.custom | 사용자 정의 카테고리 |

💡 상세 사용 예시

🟡 Debug - 개발 중 디버깅

// 기본 사용
Log.debug("현재 상태 확인")
#logDebug("변수 값", userId, userName)

// 복합 정보 로깅  
Log.debug("사용자 정보", "ID:", user.id, "이름:", user.name, "상태:", user.status)

🟠 Info - 일반 정보

// 앱 라이프사이클
Log.info("앱 시작됨", "버전:", appVersion)
#logInfo("초기화 완료", "소요시간:", initTime, "ms")

// 기능 실행 정보
Log.info("데이터 로딩 완료", "아이템 수:", items.count)

🔵 Network - 네트워크 이벤트

// API 요청/응답 로깅
Log.network("API 요청 시작", endpoint, method)
#logNetwork("응답 수신", "상태코드:", response.statusCode, "크기:", data.count)

// 실제 사용 예시
class NetworkService {
    func fetchUserProfile(userId: String) async {
        #logNetwork("사용자 프로필 요청", "userId:", userId)
        
        do {
            let profile = try await apiClient.fetchProfile(userId)
            Log.network("프로필 수신 성공", "데이터 크기:", profile.data.count)
        } catch {
            Log.error("프로필 요청 실패", error.localizedDescription)
        }
    }
}

🔴 Error - 오류 상황

// 에러 처리
Log.error("인증 실패", error.localizedDescription)
#logError("데이터베이스 연결 오류", "코드:", errorCode)

// 실제 사용 예시
do {
    try performRiskyOperation()
} catch let error as NetworkError {
    Log.error("네트워크 오류 발생", "타입:", error.type, "메시지:", error.message)
} catch {
    #logError("예상치 못한 오류", error)
}

🟡 Test - 테스트 실행

// 단위 테스트에서
func testUserLogin() {
    Log.test("로그인 테스트 시작", "사용자:", testUser.email)
    
    // 테스트 로직...
    
    #logTest("테스트 완료", "결과:", success ? "성공" : "실패")
}

🟢 Custom - 사용자 정의 카테고리

// 특정 기능별 로깅
Log.custom(category: "Analytics", "이벤트 추적", eventName, parameters)
#logCustom("Performance", "함수 실행시간", functionName, executionTime, "ms")

// 실제 사용 예시  
class AnalyticsManager {
    func trackEvent(_ name: String, parameters: [String: Any]) {
        Log.custom(category: "Analytics", "이벤트 추적", "이름:", name, "매개변수:", parameters)
        
        // 실제 분석 로직...
    }
}

🎯 실전 활용 예시

iOS 앱에서의 통합 사용

import LogMacro
import UIKit

class LoginViewController: UIViewController {
    @IBAction func loginButtonTapped(_ sender: UIButton) {
        #logInfo("로그인 버튼 터치됨")
        
        guard let email = emailTextField.text, !email.isEmpty else {
            Log.error("이메일 입력 누락")
            return
        }
        
        Task {
            await performLogin(email: email)
        }
    }
    
    private func performLogin(email: String) async {
        Log.debug("로그인 프로세스 시작", "이메일:", email)
        
        do {
            #logNetwork("로그인 API 호출")
            let result = try await AuthService.shared.login(email: email)
            
            Log.custom(category: "Auth", "로그인 성공", "userId:", result.userId)
            navigateToMainScreen()
            
        } catch {
            Log.error("로그인 실패", error.localizedDescription)
            showErrorAlert()
        }
    }
}

🔍 디버깅 및 로그 확인

Xcode에서 로그 보기

디버그 영역: Xcode 하단의 Console에서 실시간 확인
필터링: 검색창에 카테고리나 앱 이름으로 필터링

Console.app에서 로그 보기

macOS Console 앱 실행
기기 또는 시뮬레이터 선택
앱 Bundle ID로 필터링하여 로그 확인

성능 최적화

Release 빌드: 모든 로그 코드가 자동으로 제거됨
컴파일 타임 최적화: 매크로로 런타임 오버헤드 최소화
지연 평가: 필요한 경우에만 문자열 변환 수행

🛠 시스템 요구사항

| 구분 | 최소 버전 | 권장 버전 | |------|-----------|-----------| | iOS | 12.0+ | 14.0+ | | macOS | 10.15+ | 11.0+ | | Swift | 5.9+ | 6.0+ | | Xcode | 15.0+ | 15.0+ |

⚡ 성능 특징

Zero Cost in Release: Release 빌드에서 완전히 제거되어 성능 영향 없음
Compile-time Optimization: 매크로를 통한 컴파일 타임 최적화
Type Safety: Swift의 강력한 타입 시스템으로 런타임 에러 방지
Memory Efficient: 지연 평가를 통한 메모리 사용량 최적화

🤝 기여하기

LogMacro를 더 좋게 만들어주세요!

기여 방법

이슈 제기: GitHub Issues에서 버그 리포트나 기능 요청
Pull Request: 개선사항이나 새로운 기능을 직접 구현해서 기여
문서 개선: README나 문서의 오타, 개선사항 제안

개발 환경 설정

git clone https://github.com/Roy-wonji/LogMacro.git
cd LogMacro
swift build
swift test

👨‍💻 개발자 정보

서원지 (Roy) 📧 suhwj81@gmail.com 🐙 GitHub

📄 라이선스

LogMacro는 MIT 라이선스 하에 배포됩니다.

MIT License

Copyright (c) 2024 서원지 (Roy)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

자세한 내용은 LICENSE 파일을 참조해주세요.

LogMacro와 함께 더 나은 Swift 개발 경험을 만들어가세요! 🚀

⭐ 이 프로젝트가 도움이 되었다면 Star를 눌러주세요! ⭐

</div>

Package Metadata

Repository: roy-wonji/logmacro

Default branch: main

README: README.md