1 // Copyright 2009 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
5 // Package log implements a simple logging package. It defines a type, Logger,
6 // with methods for formatting output. It also has a predefined 'standard'
7 // Logger accessible through helper functions Print[f|ln], Fatal[f|ln], and
8 // Panic[f|ln], which are easier to use than creating a Logger manually.
9 // That logger writes to standard error and prints the date and time
10 // of each logged message.
11 // Every log message is output on a separate line: if the message being
12 // printed does not end in a newline, the logger will add one.
13 // The Fatal functions call os.Exit(1) after writing the log message.
14 // The Panic functions call panic after writing the log message.
26 // These flags define which text to prefix to each log entry generated by the Logger.
27 // Bits are or'ed together to control what's printed.
28 // With the exception of the Lmsgprefix flag, there is no
29 // control over the order they appear (the order listed here)
30 // or the format they present (as described in the comments).
31 // The prefix is followed by a colon only when Llongfile or Lshortfile
33 // For example, flags Ldate | Ltime (or LstdFlags) produce,
34 // 2009/01/23 01:23:23 message
35 // while flags Ldate | Ltime | Lmicroseconds | Llongfile produce,
36 // 2009/01/23 01:23:23.123123 /a/b/c/d.go:23: message
38 Ldate
= 1 << iota // the date in the local time zone: 2009/01/23
39 Ltime
// the time in the local time zone: 01:23:23
40 Lmicroseconds
// microsecond resolution: 01:23:23.123123. assumes Ltime.
41 Llongfile
// full file name and line number: /a/b/c/d.go:23
42 Lshortfile
// final file name element and line number: d.go:23. overrides Llongfile
43 LUTC
// if Ldate or Ltime is set, use UTC rather than the local time zone
44 Lmsgprefix
// move the "prefix" from the beginning of the line to before the message
45 LstdFlags
= Ldate | Ltime
// initial values for the standard logger
48 // A Logger represents an active logging object that generates lines of
49 // output to an io.Writer. Each logging operation makes a single call to
50 // the Writer's Write method. A Logger can be used simultaneously from
51 // multiple goroutines; it guarantees to serialize access to the Writer.
53 mu sync
.Mutex
// ensures atomic writes; protects the following fields
54 prefix
string // prefix on each line to identify the logger (but see Lmsgprefix)
55 flag
int // properties
56 out io
.Writer
// destination for output
57 buf
[]byte // for accumulating text to write
60 // New creates a new Logger. The out variable sets the
61 // destination to which log data will be written.
62 // The prefix appears at the beginning of each generated log line, or
63 // after the log header if the Lmsgprefix flag is provided.
64 // The flag argument defines the logging properties.
65 func New(out io
.Writer
, prefix
string, flag
int) *Logger
{
66 return &Logger
{out
: out
, prefix
: prefix
, flag
: flag
}
69 // SetOutput sets the output destination for the logger.
70 func (l
*Logger
) SetOutput(w io
.Writer
) {
76 var std
= New(os
.Stderr
, "", LstdFlags
)
78 // Cheap integer to fixed-width decimal ASCII. Give a negative width to avoid zero-padding.
79 func itoa(buf
*[]byte, i
int, wid
int) {
80 // Assemble decimal in reverse order.
83 for i
>= 10 || wid
> 1 {
86 b
[bp
] = byte('0' + i
- q
*10)
92 *buf
= append(*buf
, b
[bp
:]...)
95 // formatHeader writes log header to buf in following order:
96 // * l.prefix (if it's not blank and Lmsgprefix is unset),
97 // * date and/or time (if corresponding flags are provided),
98 // * file and line number (if corresponding flags are provided),
99 // * l.prefix (if it's not blank and Lmsgprefix is set).
100 func (l
*Logger
) formatHeader(buf
*[]byte, t time
.Time
, file
string, line
int) {
101 if l
.flag
&Lmsgprefix
== 0 {
102 *buf
= append(*buf
, l
.prefix
...)
104 if l
.flag
&(Ldate|Ltime|Lmicroseconds
) != 0 {
105 if l
.flag
&LUTC
!= 0 {
108 if l
.flag
&Ldate
!= 0 {
109 year
, month
, day
:= t
.Date()
111 *buf
= append(*buf
, '/')
112 itoa(buf
, int(month
), 2)
113 *buf
= append(*buf
, '/')
115 *buf
= append(*buf
, ' ')
117 if l
.flag
&(Ltime|Lmicroseconds
) != 0 {
118 hour
, min
, sec
:= t
.Clock()
120 *buf
= append(*buf
, ':')
122 *buf
= append(*buf
, ':')
124 if l
.flag
&Lmicroseconds
!= 0 {
125 *buf
= append(*buf
, '.')
126 itoa(buf
, t
.Nanosecond()/1e3
, 6)
128 *buf
= append(*buf
, ' ')
131 if l
.flag
&(Lshortfile|Llongfile
) != 0 {
132 if l
.flag
&Lshortfile
!= 0 {
134 for i
:= len(file
) - 1; i
> 0; i
-- {
142 *buf
= append(*buf
, file
...)
143 *buf
= append(*buf
, ':')
145 *buf
= append(*buf
, ": "...)
147 if l
.flag
&Lmsgprefix
!= 0 {
148 *buf
= append(*buf
, l
.prefix
...)
152 // Output writes the output for a logging event. The string s contains
153 // the text to print after the prefix specified by the flags of the
154 // Logger. A newline is appended if the last character of s is not
155 // already a newline. Calldepth is used to recover the PC and is
156 // provided for generality, although at the moment on all pre-defined
157 // paths it will be 2.
158 func (l
*Logger
) Output(calldepth
int, s
string) error
{
159 now
:= time
.Now() // get this early.
164 if l
.flag
&(Lshortfile|Llongfile
) != 0 {
165 // Release lock while getting caller info - it's expensive.
168 _
, file
, line
, ok
= runtime
.Caller(calldepth
)
176 l
.formatHeader(&l
.buf
, now
, file
, line
)
177 l
.buf
= append(l
.buf
, s
...)
178 if len(s
) == 0 || s
[len(s
)-1] != '\n' {
179 l
.buf
= append(l
.buf
, '\n')
181 _
, err
:= l
.out
.Write(l
.buf
)
185 // Printf calls l.Output to print to the logger.
186 // Arguments are handled in the manner of fmt.Printf.
187 func (l
*Logger
) Printf(format
string, v
...interface{}) {
188 l
.Output(2, fmt
.Sprintf(format
, v
...))
191 // Print calls l.Output to print to the logger.
192 // Arguments are handled in the manner of fmt.Print.
193 func (l
*Logger
) Print(v
...interface{}) { l
.Output(2, fmt
.Sprint(v
...)) }
195 // Println calls l.Output to print to the logger.
196 // Arguments are handled in the manner of fmt.Println.
197 func (l
*Logger
) Println(v
...interface{}) { l
.Output(2, fmt
.Sprintln(v
...)) }
199 // Fatal is equivalent to l.Print() followed by a call to os.Exit(1).
200 func (l
*Logger
) Fatal(v
...interface{}) {
201 l
.Output(2, fmt
.Sprint(v
...))
205 // Fatalf is equivalent to l.Printf() followed by a call to os.Exit(1).
206 func (l
*Logger
) Fatalf(format
string, v
...interface{}) {
207 l
.Output(2, fmt
.Sprintf(format
, v
...))
211 // Fatalln is equivalent to l.Println() followed by a call to os.Exit(1).
212 func (l
*Logger
) Fatalln(v
...interface{}) {
213 l
.Output(2, fmt
.Sprintln(v
...))
217 // Panic is equivalent to l.Print() followed by a call to panic().
218 func (l
*Logger
) Panic(v
...interface{}) {
219 s
:= fmt
.Sprint(v
...)
224 // Panicf is equivalent to l.Printf() followed by a call to panic().
225 func (l
*Logger
) Panicf(format
string, v
...interface{}) {
226 s
:= fmt
.Sprintf(format
, v
...)
231 // Panicln is equivalent to l.Println() followed by a call to panic().
232 func (l
*Logger
) Panicln(v
...interface{}) {
233 s
:= fmt
.Sprintln(v
...)
238 // Flags returns the output flags for the logger.
239 // The flag bits are Ldate, Ltime, and so on.
240 func (l
*Logger
) Flags() int {
246 // SetFlags sets the output flags for the logger.
247 // The flag bits are Ldate, Ltime, and so on.
248 func (l
*Logger
) SetFlags(flag
int) {
254 // Prefix returns the output prefix for the logger.
255 func (l
*Logger
) Prefix() string {
261 // SetPrefix sets the output prefix for the logger.
262 func (l
*Logger
) SetPrefix(prefix
string) {
268 // Writer returns the output destination for the logger.
269 func (l
*Logger
) Writer() io
.Writer
{
275 // SetOutput sets the output destination for the standard logger.
276 func SetOutput(w io
.Writer
) {
278 defer std
.mu
.Unlock()
282 // Flags returns the output flags for the standard logger.
283 // The flag bits are Ldate, Ltime, and so on.
288 // SetFlags sets the output flags for the standard logger.
289 // The flag bits are Ldate, Ltime, and so on.
290 func SetFlags(flag
int) {
294 // Prefix returns the output prefix for the standard logger.
295 func Prefix() string {
299 // SetPrefix sets the output prefix for the standard logger.
300 func SetPrefix(prefix
string) {
301 std
.SetPrefix(prefix
)
304 // Writer returns the output destination for the standard logger.
305 func Writer() io
.Writer
{
309 // These functions write to the standard logger.
311 // Print calls Output to print to the standard logger.
312 // Arguments are handled in the manner of fmt.Print.
313 func Print(v
...interface{}) {
314 std
.Output(2, fmt
.Sprint(v
...))
317 // Printf calls Output to print to the standard logger.
318 // Arguments are handled in the manner of fmt.Printf.
319 func Printf(format
string, v
...interface{}) {
320 std
.Output(2, fmt
.Sprintf(format
, v
...))
323 // Println calls Output to print to the standard logger.
324 // Arguments are handled in the manner of fmt.Println.
325 func Println(v
...interface{}) {
326 std
.Output(2, fmt
.Sprintln(v
...))
329 // Fatal is equivalent to Print() followed by a call to os.Exit(1).
330 func Fatal(v
...interface{}) {
331 std
.Output(2, fmt
.Sprint(v
...))
335 // Fatalf is equivalent to Printf() followed by a call to os.Exit(1).
336 func Fatalf(format
string, v
...interface{}) {
337 std
.Output(2, fmt
.Sprintf(format
, v
...))
341 // Fatalln is equivalent to Println() followed by a call to os.Exit(1).
342 func Fatalln(v
...interface{}) {
343 std
.Output(2, fmt
.Sprintln(v
...))
347 // Panic is equivalent to Print() followed by a call to panic().
348 func Panic(v
...interface{}) {
349 s
:= fmt
.Sprint(v
...)
354 // Panicf is equivalent to Printf() followed by a call to panic().
355 func Panicf(format
string, v
...interface{}) {
356 s
:= fmt
.Sprintf(format
, v
...)
361 // Panicln is equivalent to Println() followed by a call to panic().
362 func Panicln(v
...interface{}) {
363 s
:= fmt
.Sprintln(v
...)
368 // Output writes the output for a logging event. The string s contains
369 // the text to print after the prefix specified by the flags of the
370 // Logger. A newline is appended if the last character of s is not
371 // already a newline. Calldepth is the count of the number of
372 // frames to skip when computing the file name and line number
373 // if Llongfile or Lshortfile is set; a value of 1 will print the details
374 // for the caller of Output.
375 func Output(calldepth
int, s
string) error
{
376 return std
.Output(calldepth
+1, s
) // +1 for this frame.