zerolog - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #golang #docker #java #windows #awesome #cli #vue #pytorch #security #openai #mcp #open-source

zerolog

(★ 12,492)

Zero Allocation JSON Logger

파일 탐색기

최종 버전 다운로드 (.zip)

🚀 설치 가이드

1. 코드 내려받기

git clone https://github.com/rs/zerolog

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd zerolog

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Go

보통 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Go Go 언어 컴파일러 및 도구 모음입니다.

go build -tags binary_log .

Go 프로그램을 컴파일해 실행 파일을 만듭니다.

✅ 빌드가 에러 없이 끝나면 성공입니다. go run . 을 썼다면 터미널 출력을 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

3. Make

보통

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Make Linux/macOS는 보통 기본 설치되어 있습니다. Windows는 별도 설치(예: MSYS2, WSL)가 필요합니다.

cd internal/cbor/examples

이 프로젝트의 관련 파일이 하위 폴더 안에 있어서, 먼저 그 폴더로 이동합니다.

make

생성된 빌드 설정을 바탕으로 실제 컴파일을 진행해 실행 파일을 만듭니다.

✅ 에러 없이 끝나면 성공입니다. 생성된 실행 파일을 직접 실행해보세요.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 제로 할당 JSON 로거

[![godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/rs/zerolog) [![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://raw.githubusercontent.com/rs/zerolog/master/LICENSE) [![Build Status](https://github.com/rs/zerolog/actions/workflows/test.yml/badge.svg)](https://github.com/rs/zerolog/actions/workflows/test.yml) [![Go Coverage](https://github.com/rs/zerolog/wiki/coverage.svg)](https://raw.githack.com/wiki/rs/zerolog/coverage.html)

zerolog 패키지는 JSON 출력에 특화된 빠르고 심플한 로거를 제공합니다.

zerolog의 API는 훌륭한 개발자 경험과 놀라운 [성능](#benchmarks)을 모두 제공하도록 설계되었습니다. 독창적인 체이닝 API를 통해 zerolog는 메모리 할당과 리플렉션을 방지하면서 JSON (또는 CBOR) 로그 이벤트를 기록할 수 있습니다.

Uber의 [zap](https://godoc.org/go.uber.org/zap) 라이브러리가 이 접근 방식을 선구적으로 개척했습니다. zerolog는 사용하기 더 간단한 API와 훨씬 더 뛰어난 성능으로 이 개념을 한 단계 더 끌어올렸습니다.

코드베이스와 API를 단순하게 유지하기 위해, zerolog는 효율적인 구조화된 로깅에만 집중합니다. 콘솔에서의 보기 좋은(Pretty) 로깅은 제공되는 (하지만 비효율적인) [`zerolog.ConsoleWriter`](#pretty-logging)를 사용하여 가능합니다.

![Pretty Logging Image](https://raw.githubusercontent.com/rs/zerolog/master/pretty.png)

## zerolog를 사용하는 곳

[zerolog를 사용하는 곳](https://github.com/rs/zerolog/wiki/Who-uses-zerolog)을 확인하고 여러분의 회사나 프로젝트를 목록에 추가해 보세요.

## 특징

- [엄청나게 빠른 속도](#benchmarks)
- [낮은 할당량 또는 제로 할당](#benchmarks)
- [레벨별 로깅](#leveled-logging)
- [샘플링](#log-sampling)
- [훅 (Hooks)](#hooks)
- [컨텍스트 필드](#contextual-logging)
- [`context.Context` 통합](#contextcontext-integration)
- [`net/http` 통합](#integration-with-nethttp)
- [JSON 및 CBOR 인코딩 형식](#binary-encoding)
- [개발을 위한 예쁜(Pretty) 로깅](#pretty-logging)
- [에러 로깅 (선택적 스택 트레이스 포함)](#error-logging)
- [`log/slog` 통합](#integration-with-logslog)

## 설치

```bash
go get -u github.com/rs/zerolog/log
```

## 시작하기

### 간단한 로깅 예제

간단한 로깅을 위해 글로벌 로거 패키지인 **github.com/rs/zerolog/log**를 임포트하세요.

```go
package main

import (
    "github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    // UNIX 타임스탬프는 대부분의 타임스탬프보다 빠르고 작습니다.
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix

log.Print("hello world")
}

// Output: {"time":1516134303,"level":"debug","message":"hello world"}
```

> 참고: 기본적으로 로그는 `os.Stderr`에 기록됩니다.
> 참고: `log.Print`의 기본 로그 레벨은 _trace_ 입니다.

### 컨텍스트 로깅

**zerolog**를 사용하면 key:value 쌍 형태로 로그 메시지에 데이터를 추가할 수 있습니다. 메시지에 추가된 데이터는 디버깅뿐만 아니라 수많은 다른 용도로 매우 중요할 수 있는 로그 이벤트에 대한 "컨텍스트"를 제공합니다. 아래는 그 예시입니다:

```go
package main

import (
    "github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix

log.Debug().
        Str("Scale", "833 cents").
        Float64("Interval", 833.09).
        Msg("Fibonacci is everywhere")

log.Debug().
        Str("Name", "Tom").
        Send()
}

// Output: {"level":"debug","Scale":"833 cents","Interval":833.09,"time":1562212768,"message":"Fibonacci is everywhere"}
// Output: {"level":"debug","Name":"Tom","time":1562212768}
```

> 위 예제에서 볼 수 있듯이, 컨텍스트 필드를 추가할 때 해당 필드들은 강하게 타입이 지정됩니다. 지원되는 필드의 전체 목록은 [여기](#standard-types)에서 찾을 수 있습니다.

### 레벨별 로깅

#### 간단한 레벨별 로깅 예제

```go
package main

import (
    "github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix

log.Info().Msg("hello world")
}

// Output: {"time":1516134303,"level":"info","message":"hello world"}
```

> 위에서 보여준 것과 같이 (`log.Info().Msg("hello world"`), **zerolog** 체이닝 API를 사용할 때는 체인에 반드시 `Msg` 또는 `Msgf` 메서드 호출이 포함되어야 한다는 점을 매우 주의해야 합니다. 이 중 하나를 추가하는 것을 잊어버리면 로그가 기록되지 않으며, 이를 경고해 주는 컴파일 타임 오류도 발생하지 않습니다.

**zerolog**는 다음 레벨(높은 것부터 낮은 것 순서)로 로깅을 지원합니다.

- panic (`zerolog.PanicLevel`, 5)
- fatal (`zerolog.FatalLevel`, 4)
- error (`zerolog.ErrorLevel`, 3)
- warn (`zerolog.WarnLevel`, 2)
- info (`zerolog.InfoLevel`, 1)
- debug (`zerolog.DebugLevel`, 0)
- trace (`zerolog.TraceLevel`, -1)

zerolog 패키지의 `SetGlobalLevel` 함수에 위의 상수 중 하나를 전달하여 전역 로깅 레벨을 이러한 옵션 중 하나로 설정할 수 있습니다. 예를 들어 `zerolog.InfoLevel`은 "info" 레벨이 됩니다. 어떤 레벨이 선택되든 해당 레벨보다 크거나 같은 모든 로그가 기록됩니다. 로깅을 완전히 끄려면 `zerolog.Disabled` 상수를 전달하세요.

#### 전역 로그 레벨 설정

이 예제에서는 선택한 로그 레벨에 따라 다양한 출력을 보여주기 위해 커맨드라인 플래그를 사용합니다.

```go
package main

import (
    "flag"

"github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
    debug := flag.Bool("debug", false, "sets log level to debug")

flag.Parse()

// Default level for this example is info, unless debug flag is present
    zerolog.SetGlobalLevel(zerolog.InfoLevel)
    if *debug {
        zerolog.SetGlobalLevel(zerolog.DebugLevel)
    }

log.Debug().Msg("This message appears only when log level set to Debug")
    log.Info().Msg("This message appears when log level set to Debug or Info")

if e := log.Debug(); e.Enabled() {
        // Compute log output only if enabled.
        value := "bar"
        e.Str("foo", value).Msg("some debug message")
    }
}
```

Info 출력 (플래그 없음)

```bash
$ ./logLevelExample
{"time":1516387492,"level":"info","message":"This message appears when log level set to Debug or Info"}
```

Debug 출력 (debug 플래그 설정)

```bash
$ ./logLevelExample -debug
{"time":1516387573,"level":"debug","message":"This message appears only when log level set to Debug"}
{"time":1516387573,"level":"info","message":"This message appears when log level set to Debug or Info"}
{"time":1516387573,"level":"debug","foo":"bar","message":"some debug message"}
```

#### 레벨 또는 메시지 없는 로깅

`Log` 메서드를 사용하여 특정 레벨 없이 로깅하도록 선택할 수 있습니다. 또한 `Msg` 메서드의 `msg string` 파라미터에 빈 문자열을 설정하여 메시지 없이 작성할 수도 있습니다. 두 가지 모두 아래 예제에 나와 있습니다.

```go
package main

import (
    "github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix

log.Log().
        Str("foo", "bar").
        Msg("")
}

// Output: {"time":1494567715,"foo":"bar"}
```

### 에러 로깅

`Err` 메서드를 사용하여 에러를 로깅할 수 있습니다.

```go
package main

import (
    "errors"

"github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix

err := errors.New("seems we have an error here")
    log.Error().Err(err).Msg("")
}

// Output: {"level":"error","error":"seems we have an error here","time":1609085256}
```

> 에러의 기본 필드 이름은 `error`입니다. 필요에 따라 `zerolog.ErrorFieldName`을 설정하여 이를 변경할 수 있습니다.

#### 스택트레이스를 포함한 에러 로깅

`github.com/pkg/errors`를 사용하면 에러에 포맷된 스택트레이스를 추가할 수 있습니다.

```go
package main

import (
    "github.com/pkg/errors"
    "github.com/rs/zerolog/pkgerrors"

"github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
    zerolog.ErrorStackMarshaler = pkgerrors.MarshalStack

err := outer()
    log.Error().Stack().Err(err).Msg("")
}

func inner() error {
    return errors.New("seems we have an error here")
}
```

```go
func middle() error {
    err := inner()
    if err != nil {
        return err
    }
    return nil
}

func outer() error {
    err := middle()
    if err != nil {
        return err
    }
    return nil
}

// Output: {"level":"error","stack":[{"func":"inner","line":"20","source":"errors.go"},{"func":"middle","line":"24","source":"errors.go"},{"func":"outer","line":"32","source":"errors.go"},{"func":"main","line":"15","source":"errors.go"},{"func":"main","line":"204","source":"proc.go"},{"func":"goexit","line":"1374","source":"asm_amd64.s"}],"error":"seems we have an error here","time":1609086683}
```

> 스택이 제대로 출력되려면 `zerolog.ErrorStackMarshaler`가 설정되어 있어야 합니다.

#### 치명적인 메시지 로깅하기 (Logging Fatal Messages)

```go
package main

import (
    "errors"

"github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    err := errors.New("A repo man spends his life getting into tense situations")
    service := "myservice"

zerolog.TimeFieldFormat = zerolog.TimeFormatUnix

log.Fatal().
        Err(err).
        Str("service", service).
        Msgf("Cannot start %s", service)
}

// Output: {"time":1516133263,"level":"fatal","error":"A repo man spends his life getting into tense situations","service":"myservice","message":"Cannot start myservice"}
//         exit status 1
```

> 참고: `Msgf`를 사용하면 로거가 비활성화된 경우에도 메모리 할당이 한 번 발생합니다.

### 서로 다른 출력을 관리하기 위한 로거 인스턴스 생성

```go
logger := zerolog.New(os.Stderr).With().Timestamp().Logger()

logger.Info().Str("foo", "bar").Msg("hello world")

// Output: {"level":"info","time":1494567715,"message":"hello world","foo":"bar"}
```

### 서브 로거를 사용하면 추가 컨텍스트와 함께 로거를 체이닝할 수 있습니다

```go
sublogger := log.With().
                 Str("component", "foo").
                 Logger()
sublogger.Info().Msg("hello world")

// Output: {"level":"info","time":1494567715,"message":"hello world","component":"foo"}
```

### 보기 좋은 로깅 (Pretty logging)

사람이 읽기 편하고 색상이 지정된 출력을 로깅하려면 `zerolog.ConsoleWriter`를 사용하세요:

```go
log.Logger = log.Output(zerolog.ConsoleWriter{Out: os.Stderr})

log.Info().Str("foo", "bar").Msg("Hello world")

// Output: 3:04PM INF Hello World foo=bar
```

설정 및 포맷을 사용자 정의하려면:

```go
output := zerolog.ConsoleWriter{Out: os.Stdout, TimeFormat: time.RFC3339}
output.FormatLevel = func(i interface{}) string {
    return strings.ToUpper(fmt.Sprintf("| %-6s|", i))
}
output.FormatMessage = func(i interface{}) string {
    return fmt.Sprintf("***%s****", i)
}
output.FormatFieldName = func(i interface{}) string {
    return fmt.Sprintf("%s:", i)
}
output.FormatFieldValue = func(i interface{}) string {
    return strings.ToUpper(fmt.Sprintf("%s", i))
}

log := zerolog.New(output).With().Timestamp().Logger()

log.Info().Str("foo", "bar").Msg("Hello World")

// Output: 2006-01-02T15:04:05Z07:00 | INFO  | ***Hello World**** foo:BAR
```

고급 사용자 정의 포맷을 사용하려면:

```go
output := zerolog.ConsoleWriter{Out: os.Stdout, NoColor: true,
    PartsOrder:    []string{"level", "one", "two", "three", "message"},
    FieldsExclude: []string{"one", "two", "three"}}
output.FormatLevel = func(i interface{}) string { return strings.ToUpper(fmt.Sprintf("%-6s", i)) }
output.FormatFieldName = func(i interface{}) string { return fmt.Sprintf("%s:", i) }
output.FormatPartValueByName = func(i interface{}, s string) string {
    var ret string
    switch s {
    case "one":
        ret = strings.ToUpper(fmt.Sprintf("%s", i))
    case "two":
        ret = strings.ToLower(fmt.Sprintf("%s", i))
    case "three":
        ret = strings.ToLower(fmt.Sprintf("(%s)", i))
    }
    return ret
}
log := zerolog.New(output)

log.Info().Str("foo", "bar").
    Str("two", "TEST_TWO").
    Str("one", "test_one").
    Str("three", "test_three").
    Msg("Hello World")

// Output: INFO   TEST_ONE test_two (test_three) Hello World foo:bar
```

### 서브 딕셔너리 (Sub dictionary)

```go
log.Info().
    Str("foo", "bar").
    Dict("dict", zerolog.Dict().
        Str("bar", "baz").
        Int("n", 1),
    ).Msg("hello world")

// Output: {"level":"info","time":1494567715,"foo":"bar","dict":{"bar":"baz","n":1},"message":"hello world"}
```

### 자동 필드 이름 사용자 지정

```go
zerolog.TimestampFieldName = "t"
zerolog.LevelFieldName = "l"
zerolog.MessageFieldName = "m"

log.Info().Msg("hello world")

// Output: {"l":"info","t":1494567715,"m":"hello world"}
```

### 글로벌 로거에 컨텍스트 필드 추가

```go
log.Logger = log.With().Str("foo", "bar").Logger()
```

### 로그에 파일 및 줄 번호 추가

`Llongfile`과 동일한 기능:

```go
log.Logger = log.With().Caller().Logger()
log.Info().Msg("hello world")

// Output: {"level": "info", "message": "hello world", "caller": "/go/src/your_project/some_file:21"}
```

`Lshortfile`과 동일한 기능:

```go
zerolog.CallerMarshalFunc = func(pc uintptr, file string, line int) string {
    return filepath.Base(file) + ":" + strconv.Itoa(line)
}
log.Logger = log.With().Caller().Logger()
log.Info().Msg("hello world")

// Output: {"level": "info", "message": "hello world", "caller": "some_file:21"}
```

### 스레드 안전, 락 프리, 논블로킹 라이터

라이터가 느리거나 스레드에 안전하지 않을 수 있고, 로그 생산자가 느린 라이터 때문에 속도가 저하되는 것을 방지해야 하는 경우 다음과 같이 `diode.Writer`를 사용할 수 있습니다:

```go
wr := diode.NewWriter(os.Stdout, 1000, 10*time.Millisecond, func(missed int) {
        fmt.Printf("Logger Dropped %d messages", missed)
    })
log := zerolog.New(wr)
log.Print("test")
```

이 기능을 사용하려면 `code.cloudfoundry.org/go-diodes`를 설치해야 합니다.

### 로그 샘플링

```go
sampled := log.Sample(&zerolog.BasicSampler{N: 10})
sampled.Info().Msg("will be logged every 10 messages")

// Output: {"time":1494567715,"level":"info","message":"will be logged every 10 messages"}
```

더 고급 샘플링:

```go
// 1초 주당 5개의 디버그 메시지를 허용합니다.
// 5개의 디버그 메시지를 초과하면, 100개의 디버그 메시지 중 1개가 기록됩니다.
// 다른 레벨은 샘플링되지 않습니다.
sampled := log.Sample(zerolog.LevelSampler{
    DebugSampler: &zerolog.BurstSampler{
        Burst: 5,
        Period: 1*time.Second,
        NextSampler: &zerolog.BasicSampler{N: 100},
    },
})
sampled.Debug().Msg("hello world")

// Output: {"time":1494567715,"level":"debug","message":"hello world"}
```

### 훅 (Hooks)

```go
type SeverityHook struct{}

func (h SeverityHook) Run(e *zerolog.Event, level zerolog.Level, msg string) {
    if level != zerolog.NoLevel {
        e.Str("severity", level.String())
    }
}

hooked := log.Hook(SeverityHook{})
hooked.Warn().Msg("")

// Output: {"level":"warn","severity":"warn"}
```

### 컨텍스트를 통한 서브 로거 전달

```go
ctx := log.With().Str("component", "module").Logger().WithContext(ctx)

log.Ctx(ctx).Info().Msg("hello world")

// Output: {"component":"module","level":"info","message":"hello world"}
```

### 표준 로거 출력으로 설정

```go
log := zerolog.New(os.Stdout).With().
    Str("foo", "bar").
    Logger()

stdlog.SetFlags(0)
stdlog.SetOutput(log)

stdlog.Print("hello world")

// Output: {"foo":"bar","message":"hello world"}
```

### context.Context 통합

Go 컨텍스트는 Go 코드 전반에 걸쳐 흔히 전달되며, 이를 통해 주입하기 어려울 수 있는 곳으로 로거를 쉽게 전달할 수 있습니다. `Logger` 인스턴스는 `Logger.WithContext(ctx)`를 사용하여 Go 컨텍스트(`context.Context`)에 첨부할 수 있으며, `zerolog.Ctx(ctx)`를 사용하여 추출할 수 있습니다.
예를 들면 다음과 같습니다:

```go
func f() {
    logger := zerolog.New(os.Stdout)
    ctx := context.Background()

// context.Context에 Logger 첨부
    ctx = logger.WithContext(ctx)
    someFunc(ctx)
}

func someFunc(ctx context.Context) {
    // Go 컨텍스트에서 Logger를 가져옵니다. nil인 경우,
    // `zerolog.DefaultContextLogger`가 반환되며,
    // `DefaultContextLogger`마저 nil인 경우 비활성화된 로거가 반환됩니다.
    logger := zerolog.Ctx(ctx)
    logger.Info().Msg("Hello")
}
```

`context.Context` 통합의 두 번째 방법은 현재의 `context.Context`를 로깅된 이벤트에 전달하고 훅(hook)에서 이를 가져오는 것입니다. 이는 Go 컨텍스트에 저장된 추적(trace) 및 스팬(span) ID나 기타 정보를 로깅하는 데 유용하며, 일부 시스템에서 로깅과 추적을 통합하는 것을 용이하게 합니다.

```go
type TracingHook struct{}

func (h TracingHook) Run(e *zerolog.Event, level zerolog.Level, msg string) {
    ctx := e.GetCtx()
    spanId := getSpanIdFromContext(ctx) // 사용 중인 트레이싱 프레임워크에 맞게 구현
    e.Str("span-id", spanId)
}

func f() {
    // 로거 설정
    logger := zerolog.New(os.Stdout)
    logger = logger.Hook(TracingHook{})

ctx := context.Background()
    // Ctx 함수를 사용하여 훅에서 컨텍스트를 사용할 수 있도록 합니다.
    logger.Info().Ctx(ctx).Msg("Hello")
}
```

### `net/http`와의 통합

`github.com/rs/zerolog/hlog` 패키지는 zerolog를 `http.Handler`와 통합하기 위한 몇 가지 헬퍼를 제공합니다.

이 예제에서는 가독성을 높이기 위해 [alice](https://github.com/justinas/alice)를 사용하여 로거를 설치합니다.

```go
log := zerolog.New(os.Stdout).With().
    Timestamp().
    Str("role", "my-service").
    Str("host", host).
    Logger()

c := alice.New()

// 콘솔의 기본 출력과 함께 로거 핸들러를 설치합니다.
c = c.Append(hlog.NewHandler(log))

// 요청의 컨텍스트 필드를 설정하기 위해 제공되는 몇 가지 추가 핸들러를 설치합니다.
// 이 핸들러 덕분에 모든 로그에 미리 채워진 필드가 포함되어 출력됩니다.
c = c.Append(hlog.AccessHandler(func(r *http.Request, status, size int, duration time.Duration) {
    hlog.FromRequest(r).Info().
        Str("method", r.Method).
        Stringer("url", r.URL).
        Int("status", status).
        Int("size", size).
        Dur("duration", duration).
        Msg("")
}))
c = c.Append(hlog.RemoteAddrHandler("ip"))
c = c.Append(hlog.UserAgentHandler("user_agent"))
c = c.Append(hlog.RefererHandler("referer"))
c = c.Append(hlog.RequestIDHandler("req_id", "Request-Id"))

// 최종 핸들러입니다.
h := c.Then(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    // 요청의 컨텍스트에서 로거를 가져옵니다. 핸들러가 제거되더라도
    // hlog.FromRequest는 noop 로거를 반환하므로 항상 존재한다고
    // 안전하게 가정할 수 있습니다.
    hlog.FromRequest(r).Info().
        Str("user", "current user").
        Str("status", "ok").
        Msg("Something happened")

// Output: {"level":"info","time":"2001-02-03T04:05:06Z","role":"my-service","host":"local-hostname","req_id":"b4g0l5t6tfid6dtrapu0","user":"current user","status":"ok","message":"Something happened"}
}))
http.Handle("/", h)

if err := http.ListenAndServe(":8080", nil); err != nil {
    log.Fatal().Err(err).Msg("Startup failed")
}
```

## 다중 로그 출력

로그 메시지를 여러 출력으로 보내려면 `zerolog.MultiLevelWriter`를 사용할 수 있습니다.

이 예제에서는 로그 메시지를 `os.Stdout`과 내장된 `ConsoleWriter` 모두로 보냅니다.

```go
func main() {
    consoleWriter := zerolog.ConsoleWriter{Out: os.Stdout}
    multi := zerolog.MultiLevelWriter(consoleWriter, os.Stdout)
    logger := zerolog.New(multi).With().Timestamp().Logger()
    logger.Info().Msg("Hello World!")
}

// Output (Line 1: Console; Line 2: Stdout)
// 12:36PM INF Hello World!
// {"level":"info","time":"2019-11-07T12:36:38+03:00","message":"Hello World!"}
```

## 전역 설정

일부 설정은 변경할 수 있으며 모든 로거에 적용됩니다.

- `log.Logger`: 글로벌 로거(패키지 레벨 메서드에서 사용되는 로거)를 커스터마이즈하기 위해 이 값을 설정할 수 있습니다.
- `zerolog.SetGlobalLevel`: 모든 로거의 최소 레벨을 높일 수 있습니다. 로깅을 완전히 비활성화(조용한 모드)하려면 `zerolog.Disabled`와 함께 호출하세요.
- `zerolog.DisableSampling`: 인자가 `true`인 경우, 샘플링된 모든 로거는 샘플링을 중지하고 로그 이벤트의 100%를 발행합니다.
- `zerolog.TimestampFieldName`: `Timestamp` 필드 이름을 커스터마이즈하도록 설정할 수 있습니다.
- `zerolog.LevelFieldName`: 레벨 필드 이름을 커스터마이즈하도록 설정할 수 있습니다.
- `zerolog.MessageFieldName`: 메시지 필드 이름을 커스터마이즈하도록 설정할 수 있습니다.
- `zerolog.ErrorFieldName`: `Err` 필드 이름을 커스터마이즈하도록 설정할 수 있습니다.
- `zerolog.TimeFieldFormat`: 시간 필드 값의 형식을 커스터마이즈하도록 설정할 수 있습니다. `zerolog.TimeFormatUnix`, `zerolog.TimeFormatUnixMs`, 또는 `zerolog.TimeFormatUnixMicro`로 설정하면 시간이 UNIX 타임스탬프 형식으로 포맷됩니다.
- `zerolog.DurationFieldUnit`: `Dur`에 의해 추가된 time.Duration 타입 필드의 단위를 커스터마이즈하기 위해 설정할 수 있습니다 (기본값: `time.Millisecond`).
- `zerolog.DurationFieldFormat`: `Duration`을 각각 `Float64`, `Int64`로 추가하거나 `String()`을 호출하여 추가하도록 `DurationFormatFloat`, `DurationFormatInt`, 또는 `DurationFormatString`으로 설정할 수 있습니다 (기본값: `DurationFormatFloat`).
- `zerolog.DurationFieldInteger`: `true`로 설정하면 `Dur` 필드가 부동소수점 대신 정수로 포맷됩니다 (기본값: `false`). 지원 중단됨(Deprecated): 대신 `zerolog.DurationFieldFormat = DurationFormatInt`를 사용하세요.
- `zerolog.ErrorHandler`: zerolog가 출력에 이벤트를 쓰는 데 실패할 때마다 호출됩니다. 설정하지 않으면 stderr에 에러가 출력됩니다. 이 핸들러는 스레드 안전(thread-safe)하고 논블로킹(non-blocking)이어야 합니다.
- `zerolog.FloatingPointPrecision`: -1이 아닌 값으로 설정하면 JSON에서 부동소수점 숫자를 포맷할 때 자릿수를 제어합니다. 자세한 내용은 [strconv.FormatFloat](https://pkg.go.dev/strconv#FormatFloat)을 참조하세요.

## 필드 타입

### 표준 타입

- `Str`
- `Bool`
- `Int`, `Int8`, `Int16`, `Int32`, `Int64`
- `Uint`, `Uint8`, `Uint16`, `Uint32`, `Uint64`
- `Float32`, `Float64`

### 고급 필드

- `Err`: `error`를 받아 `zerolog.ErrorFieldName` 필드 이름을 사용하여 문자열로 렌더링합니다.
- `Func`: 레벨이 활성화된 경우에만 `func`를 실행합니다.
- `Timestamp`: `zerolog.TimestampFieldName` 필드 이름을 가진 타임스탬프 필드를 삽입하며, `zerolog.TimeFieldFormat`을 사용하여 포맷됩니다.
- `Time`: `zerolog.TimeFieldFormat`으로 포맷된 시간 필드를 추가합니다.
- `Dur`: `time.Duration` 필드를 추가합니다.
- `Dict`: 이벤트의 필드로 서브 키/값을 추가합니다.
- `RawJSON`: 이미 인코딩된 JSON(`[]byte`) 필드를 추가합니다.
- `Hex`: 1진수(hexadecimal) 문자열(`[]byte`)로 포맷된 값의 필드를 추가합니다.
- `Interface`: 리플렉션을 사용하여 타입을 마샬링합니다.
- `IPAddr`: `net.IP` 필드를 추가합니다.
- `IPPrefix`: `net.IPNet` 필드를 추가합니다.
- `MACAddr`: `net.HardwareAddr` 필드를 추가합니다.

대부분의 필드는 슬라이스 형식으로도 사용할 수 있습니다 (`[]string`의 경우 `Strs`, `[]error`의 경우 `Errs` 등).

## 바이너리 인코딩

기본 JSON 인코딩 외에도, `zerolog`는 [CBOR](https://cbor.io) 인코딩을 사용하여 바이너리 로그를 생성할 수 있습니다. 인코딩 방식은 다음과 같이 빌드 태그 `binary_log`를 사용하여 컴파일 시점에 결정할 수 있습니다:

```bash
go build -tags binary_log .
```

바이너리로 인코딩된 로그 파일을 디코딩하려면 아무 CBOR 디코더나 사용할 수 있습니다. zerolog 라이브러리와 함께 작동하는 것으로 테스트된 디코더 중 하나는 [CSD](https://github.com/toravir/csd/)입니다.

## `log/slog`와의 연동

zerolog는 `log/slog` 레코드를 zerolog 로거를 통해 라우팅하는 `slog.Handler` 구현을 제공합니다. 이를 통해 zerolog의 성능과 인코딩을 유지하면서 표준 라이브러리의 `slog` API를 사용할 수 있습니다:

```go
package main

import (
    "log/slog"

"github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

func main() {
    zl := log.Logger
    handler := zerolog.NewSlogHandler(zl)
    logger := slog.New(handler)

logger.Info("user logged in", "user", "alice", "role", "admin")
}
```

// Output: {"level":"info","user":"alice","role":"admin","time":"...","message":"user logged in"}
```

이 핸들러는 `WithAttrs`, `WithGroup`, 중첩 그룹, 그리고 `LogValuer` 해제를 포함한 모든 `slog` 기능을 지원합니다. slog 레벨은 zerolog 레벨로 매핑됩니다 (예: `slog.LevelDebug`는 `zerolog.DebugLevel`로 매핑).

## 관련 프로젝트

- [grpc-zerolog](https://github.com/cheapRoc/grpc-zerolog): `zerolog`를 사용한 `grpclog.LoggerV2` 인터페이스 구현
- [overlog](https://github.com/Trendyol/overlog): `zerolog`를 사용한 `Mapped Diagnostic Context` 인터페이스 구현
- [zerologr](https://github.com/go-logr/zerologr): `zerolog`를 사용한 `logr.LogSink` 인터페이스 구현
- [logze](https://github.com/maxbolgarin/logze): `zerolog`를 사용한 `log/slog` 인터페이스 구현

## 벤치마크

더 포괄적이고최신화된 벤치마크는 [logbench](http://bench.zerolog.io/)를참고하세요.

모든 연산은 메모리 할당이 발생하지 않습니다 (수치에는 JSON 인코딩이 _포함됨_):

```text
BenchmarkLogEmpty-8        100000000    19.1 ns/op     0 B/op       0 allocs/op
BenchmarkDisabled-8        500000000    4.07 ns/op     0 B/op       0 allocs/op
BenchmarkInfo-8            30000000     42.5 ns/op     0 B/op       0 allocs/op
BenchmarkContextFields-8   30000000     44.9 ns/op     0 B/op       0 allocs/op
BenchmarkLogFields-8       10000000     184 ns/op      0 B/op       0 allocs/op
```

zerolog가 포함된 몇 가지 Go 로깅 벤치마크 및 비교 자료입니다.

- [imkira/go-loggers-bench](https://github.com/imkira/go-loggers-bench)
- [uber-common/zap](https://github.com/uber-go/zap#performance)

Uber의 zap 비교 벤치마크 사용:

메시지 하나와 10개의 필드 로깅:

| 라이브러리          |    시간     | 할당된 바이트     | 할당된 객체       |
| :------------------ | :---------: | :-------------: | :---------------: |
| zerolog             |  767 ns/op  |    552 B/op     |    6 allocs/op    |
| :zap: zap           |  848 ns/op  |    704 B/op     |    2 allocs/op    |
| :zap: zap (sugared) | 1363 ns/op  |    1610 B/op    |   20 allocs/op    |
| go-kit              | 3614 ns/op  |    2895 B/op    |   66 allocs/op    |
| lion                | 5392 ns/op  |    5807 B/op    |   63 allocs/op    |
| logrus              | 5661 ns/op  |    6092 B/op    |   78 allocs/op    |
| apex/log            | 15332 ns/op |    3832 B/op    |   65 allocs/op    |
| log15               | 20657 ns/op |    5632 B/op    |   93 allocs/op    |

이미 10개의 컨텍스트 필드를 가지고 있는 로거로 메시지 로깅:

| 라이브러리          |    시간     | 할당된 바이트     | 할당된 객체       |
| :------------------ | :---------: | :-------------: | :---------------: |
| zerolog             |  52 ns/op   |     0 B/op      |    0 allocs/op    |
| :zap: zap           |  283 ns/op  |     0 B/op      |    0 allocs/op    |
| :zap: zap (sugared) |  337 ns/op  |     80 B/op     |    2 allocs/op    |
| lion                | 2702 ns/op  |    4074 B/op    |   38 allocs/op    |
| go-kit              | 3378 ns/op  |    3046 B/op    |   52 allocs/op    |
| logrus              | 4309 ns/op  |    4564 B/op    |   63 allocs/op    |
| apex/log            | 13456 ns/op |    2898 B/op    |   51 allocs/op    |
| log15               | 14179 ns/op |    2642 B/op    |   44 allocs/op    |

컨텍스트나 `printf` 스타일의 템플릿 없이 정적 문자열 로깅:

| 라이브러리 | 시간 | 할당된 바이트 | 할당된 객체 수 |
| :------------------ | :--------: | :-------------: | :---------------: |
| zerolog | 50 ns/op | 0 B/op | 0 allocs/op |
| :zap: zap | 236 ns/op | 0 B/op | 0 allocs/op |
| standard library | 453 ns/op | 80 B/op | 2 allocs/op |
| :zap: zap (sugared) | 337 ns/op | 80 B/op | 2 allocs/op |
| go-kit | 508 ns/op | 656 B/op | 13 allocs/op |
| lion | 771 ns/op | 1224 B/op | 10 allocs/op |
| logrus | 1244 ns/op | 1505 B/op | 27 allocs/op |
| apex/log | 2751 ns/op | 584 B/op | 11 allocs/op |
| log15 | 5181 ns/op | 1592 B/op | 26 allocs/op |

## 주의 사항

### 필드 중복

zerolog는 필드 중복 제거를 수행하지 않습니다. 동일한 키를 여러 번 사용하면 최종 JSON에 여러 개의 키가 생성됩니다:

```go
logger := zerolog.New(os.Stderr).With().Timestamp().Logger()
logger.Info().
       Timestamp().
       Msg("dup")
// Output: {"level":"info","time":1494567715,"time":1494567715,"message":"dup"}
```

이 경우 많은 소비자가 마지막 값을 사용하겠지만, 이는 보장되지 않습니다. 확실하지 않은 경우 사용하는 시스템을 확인하세요.

### 동시성 안전성

`UpdateContext`를 호출할 때 주의하세요. 동시성에 안전하지 않습니다. 자식 로거를 생성하려면 `With()` 메서드를 사용하세요:

```go
func handler(w http.ResponseWriter, r *http.Request) {
    // 동시성 안전성을 위해 자식 로거 생성
    logger := log.Logger.With().Logger()

// 컨텍스트 필드 추가, 예를 들어 HTTP 헤더의 User-Agent
    logger.UpdateContext(func(c zerolog.Context) zerolog.Context {
        ...
    })
}
```

`Logger` 레벨별 메시지 함수(예: `Log()`, `Trace()`, `Debug()` 등)에서 반환된 `Event` 객체는 `sync.Pool` 메모리에 할당되며, `Msg()`, `Msgf()`, `Send()`, 또는 `MsgFunc()`가 메시지를 기록하는 즉시 풀로 반환되므로 **절대 이후에 접근해서는 안 됩니다**.

콜백 함수나 자신의 코드 내에서 `*Event`에 대한 참조를 유지**하지 마세요**. 이는 특히 `Hook.Run()` 및 `HookFunc` 함수나 `MarshalZerologObject(e *Event)` 콜백(예: `LogObjectMarshaler` 구현체)에서 매우 중요합니다.

`Context.CreateArray()` 또는 `Event.CreateArray()`에서 반환된 모든 `Array` 객체는 `sync.Pool`에서 온 것이므로, `Context.Array()` 또는 `Event.Array()` 호출에 의해 버퍼링된 후에는 지워져 풀로 반환되므로 어떠한 `MarshalZerologArray(a *Array)` 콜백(예: `LogArrayMarshaler` 구현체)이나 자신의 코드 내에서도 참조를 유지**하지 마세요**.

`Context.CreateDict()` 또는 `Event.CreateDict()`에서 반환된 모든 _dictionary_ `Event`는 `Array.Dict()`, `Context.Dict()`, 또는 `Event.Dict()` 호출에 의해 버퍼링된 후에 지워져 풀로 반환되므로 참조**해서는 안 됩니다**.