logrus

로그루스

Logrus는 표준 라이브러리 로거와 완벽하게 API 호환되는 Go(golang)용 구조화된 로거입니다.

로그루스가 유지 관리 모드에 있습니다. 우리는 새로운 기능을 도입하지 않을 것입니다. 많은 사람들의 프로젝트를 방해하지 않는 방식으로 수행하는 것은 너무 어렵습니다. 이는 로깅 라이브러리에서 가장 원하지 않는 것입니다(다시 말하지만...).

그렇다고 로그루스가 죽었다는 뜻은 아니다. Logrus는 보안(이전 버전과 호환), 버그 수정, 성능(인터페이스에 의해 제한되는 경우)을 위해 계속 유지 관리됩니다.

나는 Logrus의 가장 큰 공헌이 오늘날 Golang에서 구조화된 로깅이 널리 사용되는 데 한몫을 했다는 것이라고 믿습니다. 환상적인 Go 커뮤니티가 이를 독립적으로 구축했기 때문에 Logrus V2로 반복을 중단하는 주요 작업을 수행할 이유가 없는 것 같습니다. 많은 환상적인 대안이 생겨났습니다. Logrus는 현재 Go의 구조적 로그인에 대해 우리가 알고 있는 내용을 바탕으로 재설계했다면 그러한 모습이었을 것입니다. 예를 들어 Zerolog, Zap 및 Apex를 확인해 보세요.

대소문자를 구분하는 이상한 문제가 보이나요? 과거에는 Logrus를 대문자와 소문자로 모두 가져오는 것이 가능했습니다. Go 패키지 환경으로 인해 커뮤니티에서 문제가 발생했으며 표준이 필요했습니다. 일부 환경에서는 대문자 변형에 문제가 발생하여 소문자로 결정되었습니다. logrus 사용하는 모든 것은 소문자( github.com/sirupsen/logrus 를 사용해야 합니다. 그렇지 않은 패키지는 변경되어야 합니다.

Glide를 수정하려면 다음 설명을 참조하세요. 케이싱 문제에 대한 자세한 설명은 이 의견을 참조하세요.

개발 중 색상이 잘 구분되어 있습니다(TTY가 연결된 경우, 그렇지 않으면 일반 텍스트임).

log.SetFormatter(&log.JSONFormatter{}) 사용하면 logstash 또는 Splunk로 쉽게 구문 분석할 수 있습니다.

 {"animal":"walrus","level":"info","msg":"A group of walrus emerges from the
ocean","size":10,"time":"2014-03-10 19:57:38.562264131 -0400 EDT"}

{"level":"warning","msg":"The group's number increased tremendously!",
"number":122,"omg":true,"time":"2014-03-10 19:57:38.562471297 -0400 EDT"}

{"animal":"walrus","level":"info","msg":"A giant walrus appears!",
"size":10,"time":"2014-03-10 19:57:38.562500591 -0400 EDT"}

{"animal":"walrus","level":"info","msg":"Tremendously sized cow enters the ocean.",
"size":9,"time":"2014-03-10 19:57:38.562527896 -0400 EDT"}

{"level":"fatal","msg":"The ice breaks!","number":100,"omg":true,
"time":"2014-03-10 19:57:38.562543128 -0400 EDT"}

TTY가 연결되지 않은 경우 기본 log.SetFormatter(&log.TextFormatter{}) 사용하면 출력이 logfmt 형식과 호환됩니다.

 time="2015-03-26T01:27:38-04:00" level=debug msg="Started observing beach" animal=walrus number=8
time="2015-03-26T01:27:38-04:00" level=info msg="A group of walrus emerges from the ocean" animal=walrus size=10
time="2015-03-26T01:27:38-04:00" level=warning msg="The group's number increased tremendously!" number=122 omg=true
time="2015-03-26T01:27:38-04:00" level=debug msg="Temperature changes" temperature=-4
time="2015-03-26T01:27:38-04:00" level=panic msg="It's over 9000!" animal=orca size=9009
time="2015-03-26T01:27:38-04:00" level=fatal msg="The ice breaks!" err=&{0x2082280c0 map[animal:orca size:9009] 2015-03-26 01:27:38.441574009 -0400 EDT panic It's over 9000!} number=100 omg=true

TTY가 연결된 경우에도 이 동작을 보장하려면 포맷터를 다음과 같이 설정하십시오.

	log . SetFormatter ( & log. TextFormatter {
		DisableColors : true ,
		FullTimestamp : true ,
	})

로깅 방법 이름

호출 메소드를 필드로 추가하려면 다음을 통해 로거에 지시하십시오.

 log . SetReportCaller ( true )

이렇게 하면 호출자를 '메서드'로 추가합니다.

{ "animal" : " penguin " , "level" : " fatal " , "method" : " github.com/sirupsen/arcticcreatures.migrate " , "msg" : " a penguin swims by " ,
"time" : " 2014-03-10 19:57:38.562543129 -0400 EDT " }

 time="2015-03-26T01:27:38-04:00" level=fatal method=github.com/sirupsen/arcticcreatures.migrate msg="a penguin swims by" animal=penguin

이는 측정 가능한 오버헤드를 추가한다는 점에 유의하세요. 비용은 Go 버전에 따라 다르지만 최근 1.6과 1.7 테스트에서는 20~40% 사이입니다. 벤치마크를 통해 귀하의 환경에서 이를 검증할 수 있습니다.

 go test -bench=.*CallerTracing

대소문자 구분

조직의 이름이 소문자로 변경되었으며 다시 변경되지 않습니다. 대소문자 구분으로 인해 가져오기 충돌이 발생하는 경우 소문자 가져오기( github.com/sirupsen/logrus 를 사용하세요.

예

Logrus를 사용하는 가장 간단한 방법은 패키지 수준에서 내보낸 로거를 사용하는 것입니다.

 package main

import (
  log "github.com/sirupsen/logrus"
)

func main () {
  log . WithFields (log. Fields {
    "animal" : "walrus" ,
  }). Info ( "A walrus appears" )
}

stdlib 로거와 완전히 API 호환되므로 어디서나 log 가져오기를 log "github.com/sirupsen/logrus" 로 대체할 수 있으며 이제 Logrus의 유연성을 갖게 됩니다. 원하는 대로 맞춤설정할 수 있습니다.

 package main

import (
  "os"
  log "github.com/sirupsen/logrus"
)

func init () {
  // Log as JSON instead of the default ASCII formatter.
  log . SetFormatter ( & log. JSONFormatter {})

  // Output to stdout instead of the default stderr
  // Can be any io.Writer, see below for File example
  log . SetOutput ( os . Stdout )

  // Only log the warning severity or above.
  log . SetLevel ( log . WarnLevel )
}

func main () {
  log . WithFields (log. Fields {
    "animal" : "walrus" ,
    "size" :   10 ,
  }). Info ( "A group of walrus emerges from the ocean" )

  log . WithFields (log. Fields {
    "omg" :    true ,
    "number" : 122 ,
  }). Warn ( "The group's number increased tremendously!" )

  log . WithFields (log. Fields {
    "omg" :    true ,
    "number" : 100 ,
  }). Fatal ( "The ice breaks!" )

  // A common pattern is to re-use fields between logging statements by re-using
  // the logrus.Entry returned from WithFields()
  contextLogger := log . WithFields (log. Fields {
    "common" : "this is a common field" ,
    "other" : "I also should be logged always" ,
  })

  contextLogger . Info ( "I'll be logged with common and other field" )
  contextLogger . Info ( "Me too" )
}

동일한 애플리케이션에서 여러 위치에 로깅하는 등의 고급 사용을 위해 logrus Logger의 인스턴스를 생성할 수도 있습니다.

 package main

import (
  "os"
  "github.com/sirupsen/logrus"
)

// Create a new instance of the logger. You can have any number of instances.
var log = logrus . New ()

func main () {
  // The API for setting attributes is a little different than the package level
  // exported logger. See Godoc.
  log . Out = os . Stdout

  // You could set this to any `io.Writer` such as a file
  // file, err := os.OpenFile("logrus.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
  // if err == nil {
  //  log.Out = file
  // } else {
  //  log.Info("Failed to log to file, using default stderr")
  // }

  log . WithFields (logrus. Fields {
    "animal" : "walrus" ,
    "size" :   10 ,
  }). Info ( "A group of walrus emerges from the ocean" )
}

전지

Logrus는 길고 구문 분석할 수 없는 오류 메시지 대신 로깅 필드를 통해 신중하고 구조화된 로깅을 권장합니다. 예를 들어 log.Fatalf("Failed to send event %s to topic %s with key %d") 대신 훨씬 더 검색 가능한 내용을 기록해야 합니다.

 log . WithFields (log. Fields {
  "event" : event ,
  "topic" : topic ,
  "key" : key ,
}). Fatal ( "Failed to send event" )

우리는 이 API가 훨씬 더 유용한 로깅 메시지를 생성하는 방식으로 로깅에 대해 생각하게 한다는 것을 발견했습니다. 우리는 이미 존재하는 로그 문에 필드 하나만 추가하면 시간을 절약할 수 있는 상황을 셀 수 없이 많이 겪었습니다. WithFields 호출은 선택 사항입니다.

일반적으로 Logrus에서 printf -family 함수를 사용하는 것은 필드를 추가해야 한다는 힌트로 간주되어야 하지만 Logrus에서 printf -family 함수를 계속 사용할 수 있습니다.

기본 필드

애플리케이션이나 그 일부의 로그 문에 항상 필드를 연결하는 것이 도움이 되는 경우가 많습니다. 예를 들어 요청 컨텍스트에서 항상 request_id 및 user_ip 기록할 수 있습니다. 모든 줄에 log.WithFields(log.Fields{"request_id": request_id, "user_ip": user_ip}) 작성하는 대신 logrus.Entry 를 생성하여 전달할 수 있습니다.

 requestLogger := log . WithFields (log. Fields { "request_id" : request_id , "user_ip" : user_ip })
requestLogger. Info ( "something happened on that request" ) # will log request_id and user_ip
requestLogger . Warn ( "something not great happened" )

후크

로깅 수준에 대한 후크를 추가할 수 있습니다. 예를 들어 Error , Fatal 및 Panic 에 대한 예외 추적 서비스에 오류를 보내고 정보를 StatsD에 보내거나 syslog와 같은 여러 위치에 동시에 기록합니다.

Logrus에는 후크가 내장되어 있습니다. init 에 해당 후크 또는 사용자 정의 후크를 추가하십시오.

 import (
  log "github.com/sirupsen/logrus"
  "gopkg.in/gemnasium/logrus-airbrake-hook.v2" // the package is named "airbrake"
  logrus_syslog "github.com/sirupsen/logrus/hooks/syslog"
  "log/syslog"
)

func init () {

  // Use the Airbrake hook to report errors that have Error severity or above to
  // an exception tracker. You can create custom hooks, see the Hooks section.
  log . AddHook ( airbrake . NewHook ( 123 , "xyz" , "production" ))

  hook , err := logrus_syslog . NewSyslogHook ( "udp" , "localhost:514" , syslog . LOG_INFO , "" )
  if err != nil {
    log . Error ( "Unable to connect to local syslog daemon" )
  } else {
    log . AddHook ( hook )
  }
}

참고: Syslog 후크는 로컬 syslog(예: "/dev/log", "/var/run/syslog" 또는 "/var/run/log")에 대한 연결도 지원합니다. 자세한 내용은 syslog 후크 README를 확인하세요.

현재 알려진 서비스 후크 목록은 이 위키 페이지에서 찾을 수 있습니다.

레벨 로깅

Logrus에는 추적, 디버그, 정보, 경고, 오류, 치명적 및 패닉의 7가지 로깅 수준이 있습니다.

 log . Trace ( "Something very low level." )
log . Debug ( "Useful debugging information." )
log . Info ( "Something noteworthy happened!" )
log . Warn ( "You should probably take a look at this." )
log . Error ( "Something failed but I'm not quitting." )
// Calls os.Exit(1) after logging
log . Fatal ( "Bye." )
// Calls panic() after logging
log . Panic ( "I'm bailing." )

Logger 에서 로깅 수준을 설정하면 해당 심각도 또는 그 이상의 심각도를 가진 항목만 기록됩니다.

 // Will log anything that is info or above (warn, error, fatal, panic). Default.
log . SetLevel ( log . InfoLevel )

애플리케이션에 있는 경우 디버그 또는 자세한 환경에서 log.Level = logrus.DebugLevel 설정하는 것이 유용할 수 있습니다.

참고: 전역( log.SetLevel(...) ) 및 syslog 로깅에 대해 서로 다른 로그 수준을 원하는 경우 syslog 후크 README를 확인하세요.

항목

WithField 또는 WithFields 로 추가된 필드 외에도 일부 필드는 모든 로깅 이벤트에 자동으로 추가됩니다.

1. time . 항목이 생성된 타임스탬프입니다.
2. msg . AddFields 호출 후 {Info,Warn,Error,Fatal,Panic} 에 전달된 로깅 메시지입니다. 예: Failed to send event.
3. level . 로깅 수준입니다. 예를 들어 info .

환경

로그루스는 환경에 대한 개념이 없습니다.

특정 환경에서만 후크와 포맷터를 사용하려면 직접 처리해야 합니다. 예를 들어, 애플리케이션에 환경을 문자열로 표현하는 전역 변수 Environment 있는 경우 다음을 수행할 수 있습니다.

 import (
  log "github.com/sirupsen/logrus"
)

func init () {
  // do something here to set environment depending on an environment variable
  // or command-line flag
  if Environment == "production" {
    log . SetFormatter ( & log. JSONFormatter {})
  } else {
    // The TextFormatter is default, you don't actually have to do this.
    log . SetFormatter ( & log. TextFormatter {})
  }
}

이 구성은 logrus 사용하기 위한 방법이지만 프로덕션에서 JSON은 Splunk 또는 Logstash와 같은 도구를 사용하여 로그 집계를 수행하는 경우에만 유용합니다.

포맷터

내장된 로깅 포맷터는 다음과 같습니다:

• logrus.TextFormatter . stdout이 tty이면 색상으로 이벤트를 기록하고, 그렇지 않으면 색상 없이 이벤트를 기록합니다.
  • 참고: TTY가 없을 때 컬러 출력을 강제하려면 ForceColors 필드를 true 로 설정하세요. TTY가 있는 경우에도 컬러 출력을 강제하지 않으려면 DisableColors 필드를 true 로 설정합니다. Windows의 경우 github.com/mattn/go-colorable을 참조하세요.
  • 색상이 활성화되면 기본적으로 레벨이 4자로 잘립니다. 잘림을 비활성화하려면 DisableLevelTruncation 필드를 true 로 설정하세요.
  • TTY로 출력할 때 모든 레벨의 너비가 동일한 열을 시각적으로 스캔하는 것이 도움이 되는 경우가 많습니다. PadLevelText 필드를 true 로 설정하면 레벨 텍스트에 패딩을 추가하여 이 동작을 활성화할 수 있습니다.
  • 모든 옵션은 생성된 문서에 나열되어 있습니다.
• logrus.JSONFormatter . 필드를 JSON으로 기록합니다.
  • 모든 옵션은 생성된 문서에 나열되어 있습니다.

타사 로깅 포맷터:

• FluentdFormatter . Kubernetes 및 Google Container Engine에서 파싱할 수 있는 항목의 형식을 지정합니다.
• GELF . Graylog의 GELF 1.1 사양을 준수하도록 항목의 형식을 지정합니다.
• logstash . 필드를 Logstash 이벤트로 기록합니다.
• prefixed 대체 레이아웃과 함께 로그 항목 소스를 표시합니다.
• zalgo . 잘고의 힘을 발동합니다.
• nested-logrus-formatter . Logrus 필드를 중첩된 구조로 변환합니다.
• powerful-logrus-formatter . 로그를 인쇄할 때 파일 이름, 로그 줄 번호 및 최신 함수 이름을 가져옵니다. 로그를 파일에 저장합니다.
• caption-json-formatter . 사람이 읽을 수 있는 캡션이 추가된 logrus의 메시지 json 포맷터.

Formatter 인터페이스를 구현하여 Format 메소드를 요구하는 포맷터를 정의할 수 있습니다. Format *Entry 사용됩니다. entry.Data 는 모든 필드와 기본 필드를 포함하는 Fields 유형( map[string]interface{} )입니다(위의 항목 섹션 참조).

 type MyJSONFormatter struct {
}

log . SetFormatter ( new ( MyJSONFormatter ))

func ( f * MyJSONFormatter ) Format ( entry * Entry ) ([] byte , error ) {
  // Note this doesn't include Time, Level and Message which are available on
  // the Entry. Consult `godoc` on information about those fields or read the
  // source of the official loggers.
  serialized , err := json . Marshal ( entry . Data )
    if err != nil {
      return nil , fmt . Errorf ( "Failed to marshal fields to JSON, %w" , err )
    }
  return append ( serialized , 'n' ), nil
}

io.Writer 로서의 로거

Logrus는 io.Writer 로 변환될 수 있습니다. 해당 작성자는 io.Pipe 의 끝이며 이를 닫는 것은 귀하의 책임입니다.

 w := logger . Writer ()
defer w . Close ()

srv := http. Server {
    // create a stdlib log.Logger that writes to
    // logrus.Logger.
    ErrorLog : log . New ( w , "" , 0 ),
}

해당 작성자에게 작성된 각 줄은 포맷터와 후크를 사용하여 일반적인 방식으로 인쇄됩니다. 해당 항목의 수준은 info 입니다.

이는 표준 라이브러리 로거를 쉽게 재정의할 수 있음을 의미합니다.

 logger := logrus . New ()
logger . Formatter = & logrus. JSONFormatter {}

// Use logrus for standard log output
// Note that `log` here references stdlib's log
// Not logrus imported under the name `log`.
log . SetOutput ( logger . Writer ())

회전

Logrus에서는 로그 회전이 제공되지 않습니다. 로그 회전은 오래된 로그 항목을 압축하고 삭제할 수 있는 외부 프로그램(예: logrotate(8) )에 의해 수행되어야 합니다. 이는 애플리케이션 수준 로거의 기능이 아니어야 합니다.

도구

도구	설명
로그루스 메이트	Logrus mate는 Logrus가 로거를 관리하는 도구입니다. 구성 파일별로 로거의 레벨, 후크 및 포맷터를 초기화할 수 있으며, 로거는 다양한 환경에서 다양한 구성으로 생성됩니다.
로그루스 바이퍼 도우미	송곳니로 구성을 로드하기 위해 spf13/Viper로 래핑하는 Logrus 주변의 도우미! Logrus 구성을 단순화하려면 Logrus Mate의 일부 동작을 사용하십시오. 견본

테스트

Logrus에는 로그 메시지의 존재를 확인하는 기능이 내장되어 있습니다. 이는 test 후크를 통해 구현되며 다음을 제공합니다.

• 기본적으로 test 후크만 추가하는 기존 로거( test.NewLocal 및 test.NewGlobal )용 데코레이터
• 로그 메시지만 기록하고 아무 것도 출력하지 않는 테스트 로거( test.NewNullLogger ):

 import (
  "github.com/sirupsen/logrus"
  "github.com/sirupsen/logrus/hooks/test"
  "github.com/stretchr/testify/assert"
  "testing"
)

func TestSomething ( t * testing. T ){
  logger , hook := test . NewNullLogger ()
  logger . Error ( "Helloerror" )

  assert . Equal ( t , 1 , len ( hook . Entries ))
  assert . Equal ( t , logrus . ErrorLevel , hook . LastEntry (). Level )
  assert . Equal ( t , "Helloerror" , hook . LastEntry (). Message )

  hook . Reset ()
  assert . Nil ( t , hook . LastEntry ())
}

치명적인 핸들러

로그러스는 fatal 수준의 메시지가 기록될 때 호출되는 하나 이상의 함수를 등록할 수 있습니다. 등록된 핸들러는 Logrus가 os.Exit(1) 을 수행하기 전에 실행됩니다. 이 동작은 호출자가 정상적으로 종료해야 하는 경우 도움이 될 수 있습니다. 지연된 recover 로 가로챌 수 panic("Something went wrong...") 호출과 달리 os.Exit(1) 에 대한 호출은 가로챌 수 없습니다.

 ...
handler := func() {
  // gracefully shutdown something...
}
logrus.RegisterExitHandler(handler)
...

스레드 안전성

기본적으로 Logger는 동시 쓰기를 위한 뮤텍스로 보호됩니다. 후크를 호출하고 로그를 작성할 때 뮤텍스가 유지됩니다. 그러한 잠금이 필요하지 않다고 확신하는 경우 logger.SetNoLock()을 호출하여 잠금을 비활성화할 수 있습니다.

잠금이 필요하지 않은 상황은 다음과 같습니다.

• 등록된 후크가 없거나 후크 호출이 이미 스레드로부터 안전합니다.

• logger.Out에 쓰기는 이미 스레드로부터 안전합니다. 예를 들면 다음과 같습니다.

  1. logger.Out은 잠금으로 보호됩니다.

  2. logger.Out은 O_APPEND 플래그로 열리는 os.File 핸들러이며 모든 쓰기는 4k보다 작습니다. (이것은 다중 스레드/다중 프로세스 쓰기를 허용합니다)

     (http://www.notthewizard.com/2014/06/17/are-files-appends-really-atomic/ 참조)