log

8 分钟阅读

原文：https://pkg.go.dev/log@go1.24.2

Package log implements a simple logging package. It defines a type, Logger, with methods for formatting output. It also has a predefined ‘standard’ Logger accessible through helper functions Print[f|ln], Fatal[f|ln], and Panic[f|ln], which are easier to use than creating a Logger manually. That logger writes to standard error and prints the date and time of each logged message. Every log message is output on a separate line: if the message being printed does not end in a newline, the logger will add one. The Fatal functions call os.Exit(1) after writing the log message. The Panic functions call panic after writing the log message.

log包实现了一个简单的日志包。它定义了一个类型Logger，该类型具有格式化输出的方法。它还有一个预定义的"标准"Logger，可以通过Print[f|ln]、Fatal[f|ln]和Panic[f|ln]帮助函数访问，这比手动创建Logger更容易。该记录器(logger )将写入标准错误，并打印每个记录消息的日期和时间。每条日志消息都在单独的一行上输出：如果要打印的消息没有以换行符结尾，该记录器(logger )将添加一个换行符。Fatal函数在写入日志消息后调用os.Exit(1)。Panic函数在写入日志消息后调用panic。

常量

View Source

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const (
	Ldate         = 1 << iota     // 当地时区的日期：2009/01/23 the date in the local time zone: 2009/01/23
	Ltime                         // 当地时区的时间：01:23:23 the time in the local time zone: 01:23:23
	Lmicroseconds // 微秒级分辨率：01:23:23.123123.假设是Ltime。 microsecond resolution: 01:23:23.123123.  assumes Ltime.
	Llongfile    // 完整的文件名和行数：/a/b/c/d.go:23 full file name and line number: /a/b/c/d.go:23
	Lshortfile  // 最后的文件名元素和行数: d.go:23. 覆盖Llongfile。 final file name element and line number: d.go:23. overrides Llongfile
	LUTC  // 如果设置了Ldate或Ltime，则使用UTC而不是本地时区。 if Ldate or Ltime is set, use UTC rather than the local time zone
	Lmsgprefix  // 将 "前缀"从行首移至信息之前 move the "prefix" from the beginning of the line to before the message
	LstdFlags     = Ldate | Ltime // 标准记录器的初始值 initial values for the standard logger
)

These flags define which text to prefix to each log entry generated by the Logger. Bits are or’ed together to control what’s printed. With the exception of the Lmsgprefix flag, there is no control over the order they appear (the order listed here) or the format they present (as described in the comments). The prefix is followed by a colon only when Llongfile or Lshortfile is specified. For example, flags Ldate | Ltime (or LstdFlags) produce,

这些标志定义了记录器生成每个日志条目时要添加的文本。位或运算将它们连接在一起以控制打印内容。除了 Lmsgprefix 标志外，没有控制它们出现的顺序(按此处列出的顺序)或它们呈现的格式(如注释中所述)。只有当指定了 Llongfile 或 Lshortfile 时，前缀后面才跟有一个冒号。例如，标志 Ldate | Ltime(或 LstdFlags)会产生以下输出：

2009/01/23 01:23:23 message

while flags Ldate | Ltime | Lmicroseconds | Llongfile produce,

而标志 Ldate | Ltime | Lmicroseconds | Llongfile 会产生以下输出：

2009/01/23 01:23:23.123123 /a/b/c/d.go:23: message

变量

This section is empty.

函数

func Fatal

1
func Fatal(v ...any)

Fatal is equivalent to Print() followed by a call to os.Exit(1).

Fatal函数等效于 Print()，然后调用 os.Exit(1)。

func Fatalf

1
func Fatalf(format string, v ...any)

Fatalf is equivalent to Printf() followed by a call to os.Exit(1).

Fatalf函数等效于 Printf()，然后调用 os.Exit(1)。

func Fatalln

1
func Fatalln(v ...any)

Fatalln is equivalent to Println() followed by a call to os.Exit(1).

Fatalln函数等效于 Println()，然后调用 os.Exit(1)。

func Flags

1
func Flags() int

Flags returns the output flags for the standard logger. The flag bits are Ldate, Ltime, and so on.

Flags函数返回标准日志记录器的输出标志。标志位是 Ldate、Ltime 等等。

func Output <- go1.5

1
func Output(calldepth int, s string) error

Output writes the output for a logging event. The string s contains the text to print after the prefix specified by the flags of the Logger. A newline is appended if the last character of s is not already a newline. Calldepth is the count of the number of frames to skip when computing the file name and line number if Llongfile or Lshortfile is set; a value of 1 will print the details for the caller of Output.

Output 方法用于写入日志事件的输出。字符串 s 包含在 Logger 的标志指定前缀之后要打印的文本。如果 s 的最后一个字符不是换行符，则会附加一个换行符。当设置 Llongfile 或 Lshortfile 标志时，calldepth 是要跳过的帧数，以计算文件名和行号；当 calldepth 的值为 1 时，将会打印 Output 的调用者的细节信息。

func Panic

1
func Panic(v ...any)

Panic is equivalent to Print() followed by a call to panic().

Panic函数等效于 Print()，然后调用 panic()。

func Panicf

1
func Panicf(format string, v ...any)

Panicf is equivalent to Printf() followed by a call to panic().

Panicf函数相当于调用Printf()后再调用panic()。

func Panicln

1
func Panicln(v ...any)

Panicln is equivalent to Println() followed by a call to panic().

Panicln函数相当于调用Println()后再调用panic()。

func Prefix

1
func Prefix() string

Prefix returns the output prefix for the standard logger.

Prefix函数返回标准记录器的输出前缀。

func Print

1
func Print(v ...any)

Print calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.

Print函数通过调用Output函数向标准记录器打印内容。参数的处理方式类似于fmt.Print。

func Printf

1
func Printf(format string, v ...any)

Printf calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.

Printf函数通过调用Output函数向标准记录器打印内容。参数的处理方式类似于fmt.Printf。

func Println

1
func Println(v ...any)

Println calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Println.

Println函数通过调用Output函数向标准记录器打印内容。参数的处理方式类似于fmt.Println。

func SetFlags

1
func SetFlags(flag int)

SetFlags sets the output flags for the standard logger. The flag bits are Ldate, Ltime, and so on.

SetFlags函数设置标准记录器的输出标志。标志位包括Ldate、Ltime等等。

func SetOutput

1
func SetOutput(w io.Writer)

SetOutput sets the output destination for the standard logger.

SetOutput函数设置标准记录器的输出目的地。

func SetPrefix

1
func SetPrefix(prefix string)

SetPrefix sets the output prefix for the standard logger.

SetPrefix函数设置标准记录器的输出前缀。

func Writer <- go1.13

1
func Writer() io.Writer

Writer returns the output destination for the standard logger.

Writer函数返回标准记录器的输出目的地。

类型

type Logger

1
2
3
4
5
6
7
8
type Logger struct {
    mu        sync.Mutex // 保证原子写入；保护以下字段
	prefix    string // 每行日志前缀以标识记录器(参见 Lmsgprefix)
	flag      int        // 属性
	out       io.Writer  // 输出目的地
	buf       []byte     // 用于累积要写入的文本
	isDiscard int32 // 原子布尔值：是否 out == io.Discard
}

A Logger represents an active logging object that generates lines of output to an io.Writer. Each logging operation makes a single call to the Writer’s Write method. A Logger can be used simultaneously from multiple goroutines; it guarantees to serialize access to the Writer.

Logger表示一个活动的日志记录对象，它生成输出行到一个io.Writer。每个日志操作都会调用Writer的Write方法。一个Logger可以同时从多个goroutine使用；它保证对Writer的访问是序列化的。

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
package main

import (
	"bytes"
	"fmt"
	"log"
)

func main() {
	var (
		buf    bytes.Buffer
		logger = log.New(&buf, "logger: ", log.Lshortfile)
	)

	logger.Print("Hello, log file!")

	fmt.Print(&buf)
}
Output:

logger: example_test.go:19: Hello, log file!

func Default <- go1.16

1
func Default() *Logger

Default returns the standard logger used by the package-level output functions.

Default函数返回由包级别输出函数使用的标准记录器。

func New

1
func New(out io.Writer, prefix string, flag int) *Logger

New creates a new Logger. The out variable sets the destination to which log data will be written. The prefix appears at the beginning of each generated log line, or after the log header if the Lmsgprefix flag is provided. The flag argument defines the logging properties.

New创建一个新的Logger。out变量设置将写入日志数据的目的地。prefix出现在每个生成的日志行的开头，或者如果提供了Lmsgprefix标志，则出现在日志标题之后。flag参数定义日志属性。

(*Logger) Fatal

1
func (l *Logger) Fatal(v ...any)

Fatal is equivalent to l.Print() followed by a call to os.Exit(1).

Fatal方法相当于 l.Print() 后面跟一个 os.Exit(1) 的调用。

(*Logger) Fatalf

1
func (l *Logger) Fatalf(format string, v ...any)

Fatalf is equivalent to l.Printf() followed by a call to os.Exit(1).

Fatalf方法相当于 l.Printf() 后面跟一个 os.Exit(1) 的调用。

(*Logger) Fatalln

1
func (l *Logger) Fatalln(v ...any)

Fatalln is equivalent to l.Println() followed by a call to os.Exit(1).

Fatalln方法相当于 l.Println() 后面跟一个 os.Exit(1) 的调用。

(*Logger) Flags

1
func (l *Logger) Flags() int

Flags returns the output flags for the logger. The flag bits are Ldate, Ltime, and so on.

Flags方法返回 Logger 的输出标志。标志位包括 Ldate、Ltime 等。

(*Logger) Output

1
func (l *Logger) Output(calldepth int, s string) error

Output writes the output for a logging event. The string s contains the text to print after the prefix specified by the flags of the Logger. A newline is appended if the last character of s is not already a newline. Calldepth is used to recover the PC and is provided for generality, although at the moment on all pre-defined paths it will be 2.

Output方法写入日志事件的输出。字符串 s 包含在 Logger 的标志指定的前缀之后要打印的文本。如果 s 的最后一个字符不是换行符，则附加一个换行符。Calldepth 用于恢复 PC，并提供一般性，尽管目前在所有预定义的路径上它将是 2。

Output Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
package main

import (
	"bytes"
	"fmt"
	"log"
)

func main() {
	var (
		buf    bytes.Buffer
		logger = log.New(&buf, "INFO: ", log.Lshortfile)

		infof = func(info string) {
			logger.Output(2, info)
		}
	)

	infof("Hello world")

	fmt.Print(&buf)
}
Output:

INFO: example_test.go:36: Hello world

(*Logger) Panic

1
func (l *Logger) Panic(v ...any)

Panic is equivalent to l.Print() followed by a call to panic().

Panic方法相当于 l.Print() 后面跟一个 panic() 的调用。

(*Logger) Panicf

1
func (l *Logger) Panicf(format string, v ...any)

Panicf is equivalent to l.Printf() followed by a call to panic().

Panicf方法相当于 l.Printf() 后面跟一个 panic() 的调用。

(*Logger) Panicln

1
func (l *Logger) Panicln(v ...any)

Panicln is equivalent to l.Println() followed by a call to panic().

Panicln方法相当于 l.Println() 后面跟一个 panic() 的调用。

(*Logger) Prefix

1
func (l *Logger) Prefix() string

Prefix returns the output prefix for the logger.

Prefix方法返回 Logger 的输出前缀。

(*Logger) Print

1
func (l *Logger) Print(v ...any)

Print calls l.Output to print to the logger. Arguments are handled in the manner of fmt.Print.

Print方法调用 l.Output 来向 Logger 打印信息。参数的处理方式类似于 fmt.Print。

(*Logger) Printf

1
func (l *Logger) Printf(format string, v ...any)

Printf calls l.Output to print to the logger. Arguments are handled in the manner of fmt.Printf.

Printf方法调用 l.Output 来向 Logger 打印信息。参数的处理方式类似于 fmt.Printf。

(*Logger) Println

1
func (l *Logger) Println(v ...any)

Println calls l.Output to print to the logger. Arguments are handled in the manner of fmt.Println.

Println方法调用 l.Output 来向 Logger 打印信息。参数的处理方式类似于 fmt.Println。

(*Logger) SetFlags

1
func (l *Logger) SetFlags(flag int)

SetFlags sets the output flags for the logger. The flag bits are Ldate, Ltime, and so on.

SetFlags方法设置 Logger 的输出标志。标志位包括 Ldate、Ltime 等。

(*Logger) SetOutput <- go1.5

1
func (l *Logger) SetOutput(w io.Writer)

SetOutput sets the output destination for the logger.

SetOutput方法设置 Logger 的输出目的地。

(*Logger) SetPrefix

1
func (l *Logger) SetPrefix(prefix string)

SetPrefix sets the output prefix for the logger.

SetPrefix方法设置Logger 的输出前缀。

(*Logger) Writer <- go1.12

1
func (l *Logger) Writer() io.Writer

Writer returns the output destination for the logger.

Writer方法返回Logger 的输出目的地。

最后修改 April 2, 2025: 更新 (adce14e7)