loggur 0.1.0

# Loggur 사용 설명서

`loggur`는 시각적으로 풍부한 Rust 로깅 크레이트입니다. tracing 생태계와 통합되어 구조화된 로깅과 진행 상태 표시 기능을 제공합니다.

## 목차

- [기능](#기능)
- [설치 방법](#설치-방법)
- [기본 사용법](#기본-사용법)
- [고급 사용법](#고급-사용법)
- [crates.io 배포 방법](#cratesio-배포-방법)

## 기능

- [tracing](https://crates.io/crates/tracing) 생태계와 완벽하게 통합
- [tracing-indicatif](https://crates.io/crates/tracing-indicatif)를 활용한 자동 진행 상태 표시
- 다양한 로그 레벨 지원 (TRACE, DEBUG, INFO, WARN, ERROR)
- 컬러 및 스타일링된 로그 출력
- 이모지 지원
- 파일 로깅 지원
- 구조화된 로깅 (필드 기반)
- span 기반 컨텍스트 추적
- 시간 측정 및 표시 기능

## 설치 방법

`Cargo.toml` 파일에 다음 의존성을 추가하세요:

```toml
[dependencies]
loggur = "0.1.0"
```

또는 cargo 명령어를 사용하세요:

```bash
cargo add loggur
```

## 기본 사용법

### 로거 초기화

`loggur`는 다양한 초기화 방법을 제공합니다:

```rust
use loggur::{Loggur, Level};

// 기본 로거 초기화
Loggur::init(Level::DEBUG);

// 파일 로깅 초기화
let _guard = Loggur::init_with_file(Level::INFO, "./app.log");

// 진행 상태 표시 기능 초기화
Loggur::init_with_progress(Level::INFO);

// 모든 기능 통합 초기화
let _guard = Loggur::init_full(Level::DEBUG, Some("./app.log"));
```

### 로깅 매크로

`loggur`는 tracing 매크로와 호환되는 로깅 매크로를 제공합니다:

```rust
use loggur::{trace, debug, info, warn, error};

trace!("추적 메시지입니다");
debug!("디버그 메시지입니다");
info!("정보 메시지입니다");
warn!("경고 메시지입니다");
error!("오류 메시지입니다");
```

### 구조화된 로깅

필드를 포함한 구조화된 로깅이 가능합니다:

```rust
info!(user = "ferris", action = "login", "사용자가 로그인했습니다");
error!(code = 404, path = "/api/users", "리소스를 찾을 수 없습니다");
```

### span 및 진행 상태 표시

span을 사용하여 컨텍스트를 추적하고 진행 상태를 표시할 수 있습니다:

```rust
use loggur::{info_span, progress_span, progress_inc};

// 일반 span
let span = info_span!("데이터베이스_쿼리", table = "users");
let _enter = span.enter();

// 진행 상태 표시 span
let total_items = 100;
let span = progress_span!("작업 진행", total_items);
let _enter = span.enter();

for i in 0..total_items {
    // 작업 수행
    // ...
    
    // 진행 상태 업데이트
    progress_inc!(1);
}
```

### 시간 측정

`time_it` 매크로를 사용하여 코드 블록의 실행 시간을 측정할 수 있습니다:

```rust
use loggur::time_it;

time_it!("복잡한 계산", {
    // 복잡한 계산 수행
    // ...
});
```

## 고급 사용법

### 환경 변수를 통한 로그 레벨 제어

`RUST_LOG` 환경 변수를 설정하여 로그 레벨을 제어할 수 있습니다:

```bash
# 전체 로그 레벨 설정
RUST_LOG=info cargo run

# 특정 모듈의 로그 레벨 설정
RUST_LOG=debug,my_module=trace cargo run
```

### 커스텀 진행 상태 표시 스타일

tracing-indicatif의 기능을 활용하여 진행 상태 표시 스타일을 커스터마이즈할 수 있습니다:

```rust
use loggur::{Loggur, Level};
use indicatif::ProgressStyle;
use tracing_indicatif::IndicatifLayer;
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;
use tracing_subscriber::{EnvFilter, Registry};

// 커스텀 진행 상태 표시 스타일 설정
let env_filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info"));

let fmt_layer = tracing_subscriber::fmt::layer()
    .with_target(true)
    .with_ansi(true);

let progress_layer = IndicatifLayer::new()
    .with_progress_style(
        ProgressStyle::with_template(
            "{spinner:.green} [{elapsed_precise}] {bar:40.cyan/blue} {pos:>7}/{len:7} {msg}",
        )
        .unwrap()
        .progress_chars("##-"),
    );

Registry::default()
    .with(env_filter)
    .with(fmt_layer)
    .with(progress_layer)
    .init();
```

## crates.io 배포 방법

### 1. 계정 설정

crates.io에 크레이트를 배포하기 위해서는 먼저 계정을 설정해야 합니다:

```bash
# cargo login 명령어 실행
cargo login

# API 토큰 입력 (https://crates.io/me에서 확인 가능)
```

### 2. 크레이트 준비

배포 전에 다음 사항을 확인하세요:

1. `Cargo.toml` 파일에 필요한 메타데이터가 모두 포함되어 있는지 확인:
   ```toml
   [package]
   name = "loggur"
   version = "0.1.0"
   edition = "2024"
   authors = ["Your Name <your.email@example.com>"]
   description = "시각적으로 풍부한 로깅 크레이트"
   license = "MIT"
   readme = "README.md"
   repository = "https://github.com/username/loggur"
   documentation = "https://docs.rs/loggur"
   keywords = ["logging", "tracing", "cli", "progress"]
   categories = ["command-line-utilities", "development-tools::debugging"]
   ```

2. `README.md` 파일이 있고 크레이트 사용법이 잘 설명되어 있는지 확인

3. `LICENSE` 파일이 있는지 확인

4. `.gitignore`에 불필요한 파일이 제외되어 있는지 확인

### 3. 크레이트 검증

배포 전에 크레이트를 검증하세요:

```bash
# 크레이트 빌드
cargo build --release

# 테스트 실행
cargo test

# 문서 생성 및 확인
cargo doc --open

# 패키지 검증
cargo package --list
```

### 4. 크레이트 배포

검증이 완료되면 크레이트를 배포하세요:

```bash
# 크레이트 배포
cargo publish
```

### 5. 버전 업데이트

크레이트를 업데이트할 때는 `Cargo.toml` 파일의 버전 번호를 변경하고 다시 배포하세요:

```toml
[package]
name = "loggur"
version = "0.1.1"  # 버전 번호 증가
```

```bash
# 변경된 버전으로 배포
cargo publish
```

### 6. 배포 취소

배포 후 문제가 발견되면 해당 버전을 취소할 수 있습니다 (배포 후 24시간 이내에만 가능):

```bash
# 특정 버전 취소
cargo yank --vers 0.1.0
```

### 7. 배포 자동화

GitHub Actions를 사용하여 배포를 자동화할 수 있습니다:

```yaml
# .github/workflows/publish.yml
name: Publish

on:
  push:
    tags:
      - 'v*'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          override: true
      - uses: katyo/publish-crates@v1
        with:
          registry-token: ${{ secrets.CARGO_REGISTRY_TOKEN }}
```

이 설정은 `v0.1.0`과 같은 태그를 푸시할 때 자동으로 크레이트를 배포합니다.