@homecheck/logger/README.md

A simple logger for Web, Node, Capacitor apps.

<div align="center">
  
# 🪵 @homecheck/logger

간단한 웹, 노드, 캐퍼시터 앱을 위한 로깅 라이브러리

</div>

> [!NOTE]
> 이 라이브러리는 다양한 환경(웹, 노드, 캐퍼시터)에서 로그를 기록하고 서버로 전송할 수 있는 기능을 제공합니다.

## 📋 특징

- 다양한 로그 레벨 지원 (debug, info, warn, error, fatal)
- 오프라인 상태에서도 로그 저장 및 온라인 시 자동 전송
- 여러 서버로 로그 전송 가능
- 배치 모드 지원으로 효율적인 로그 전송
- 스택 트레이스 자동 수집
- 타입스크립트 지원

## 🚀 설치

```
pnpm add @homecheck/logger
# 또는
npm install @homecheck/logger
# 또는
yarn add @homecheck/logger
```

## 🔧 기본 사용법

### 초기화

```
import Logger from '@homecheck/logger'

Logger.initialize({
  utc: 9, // 한국 시간대
  projectName: '프로젝트명',
  reportServers: {
    example-server-1: {
      url: 'https://your-log-server.com/api/logs',
      token: 'your-auth-token', // optional
      batch: true // 배치 모드 활성화 (optional, 기본값 false, true시 배열로 전송)
    },
    example-slack: {
      url: 'https://hooks.slack.com/services/your-webhook-url',
      token: 'your-auth-token', // optional
      slackChannel: '#errors' // slack의 채널ID (optional)
    }
  },
  maxQueueSize: 1000, // 최대 로그 큐 크기 (optional, 기본값 1000)
  batchSize: 50, // 배치 전송 크기 (optional, 기본값 50)
  retryInterval: 30000 // 재시도 간격 (optional, 기본값 30000ms)
})
```

### 로그 기록

```
import Logger from '@homecheck/logger'

// 기본 로그 기록
Logger.info('일반 정보 로그')
Logger.warn('경고 로그')
Logger.error('에러 로그')
Logger.debug('디버그 로그')
Logger.fatal('치명적 오류 로그')

// 객체 로깅
Logger.info({ user: 'user123', action: 'login' })

// 에러 객체 로깅
try {
  throw new Error('에러 발생!')
} catch (error) {
  Logger.error(error)
}
```

### 로그 전송

```
// 특정 서버로만 로그 전송
Logger.error(error).report(['example-server-1'])

// 여러 서버로 로그 전송
Logger.warn('주의 필요').report(['example-slack', 'example-server-1'])

// 모든 서버로 로그 전송
Logger.info('로그').report()
```

## 📝 로그 레벨

- `DEBUG`: 개발 중 디버깅 목적의 상세 정보
- `INFO`: 일반적인 정보성 메시지
- `WARN`: 잠재적 문제 경고
- `ERROR`: 오류 발생
- `FATAL`: 애플리케이션 중단 가능성이 있는 심각한 오류

## 🔄 오프라인 지원

@homecheck/logger는 오프라인 상태에서도 로그를 저장하고 네트워크 연결이 복구되면 자동으로 서버에 전송합니다.
지원하는 플랫폼은 아래와 같습니다.

- 모던 브라우저 (Chromium, Firefox, etc...)
- CapacitorJS
- NodeJS

<div align="center">
  <b>© 2025 Homecheck</b>
</div>