Source file src/log/slog/doc.go
1 // Copyright 2022 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. 4 5 /* 6 Package slog provides structured logging, 7 in which log records include a message, 8 a severity level, and various other attributes 9 expressed as key-value pairs. 10 11 It defines a type, [Logger], 12 which provides several methods (such as [Logger.Info] and [Logger.Error]) 13 for reporting events of interest. 14 15 Each Logger is associated with a [Handler]. 16 A Logger output method creates a [Record] from the method arguments 17 and passes it to the Handler, which decides how to handle it. 18 There is a default Logger accessible through top-level functions 19 (such as [Info] and [Error]) that call the corresponding Logger methods. 20 21 A log record consists of a time, a level, a message, and a set of key-value 22 pairs, where the keys are strings and the values may be of any type. 23 As an example, 24 25 slog.Info("hello", "count", 3) 26 27 creates a record containing the time of the call, 28 a level of Info, the message "hello", and a single 29 pair with key "count" and value 3. 30 31 The [Info] top-level function calls the [Logger.Info] method on the default Logger. 32 In addition to [Logger.Info], there are methods for Debug, Warn and Error levels. 33 Besides these convenience methods for common levels, 34 there is also a [Logger.Log] method which takes the level as an argument. 35 Each of these methods has a corresponding top-level function that uses the 36 default logger. 37 38 The default handler formats the log record's message, time, level, and attributes 39 as a string and passes it to the [log] package. 40 41 2022/11/08 15:28:26 INFO hello count=3 42 43 For more control over the output format, create a logger with a different handler. 44 This statement uses [New] to create a new logger with a [TextHandler] 45 that writes structured records in text form to standard error: 46 47 logger := slog.New(slog.NewTextHandler(os.Stderr, nil)) 48 49 [TextHandler] output is a sequence of key=value pairs, easily and unambiguously 50 parsed by machine. This statement: 51 52 logger.Info("hello", "count", 3) 53 54 produces this output: 55 56 time=2022-11-08T15:28:26.000-05:00 level=INFO msg=hello count=3 57 58 The package also provides [JSONHandler], whose output is line-delimited JSON: 59 60 logger := slog.New(slog.NewJSONHandler(os.Stdout, nil)) 61 logger.Info("hello", "count", 3) 62 63 produces this output: 64 65 {"time":"2022-11-08T15:28:26.000000000-05:00","level":"INFO","msg":"hello","count":3} 66 67 Both [TextHandler] and [JSONHandler] can be configured with [HandlerOptions]. 68 There are options for setting the minimum level (see Levels, below), 69 displaying the source file and line of the log call, and 70 modifying attributes before they are logged. 71 72 Setting a logger as the default with 73 74 slog.SetDefault(logger) 75 76 will cause the top-level functions like [Info] to use it. 77 [SetDefault] also updates the default logger used by the [log] package, 78 so that existing applications that use [log.Printf] and related functions 79 will send log records to the logger's handler without needing to be rewritten. 80 81 Some attributes are common to many log calls. 82 For example, you may wish to include the URL or trace identifier of a server request 83 with all log events arising from the request. 84 Rather than repeat the attribute with every log call, you can use [Logger.With] 85 to construct a new Logger containing the attributes: 86 87 logger2 := logger.With("url", r.URL) 88 89 The arguments to With are the same key-value pairs used in [Logger.Info]. 90 The result is a new Logger with the same handler as the original, but additional 91 attributes that will appear in the output of every call. 92 93 # Levels 94 95 A [Level] is an integer representing the importance or severity of a log event. 96 The higher the level, the more severe the event. 97 This package defines constants for the most common levels, 98 but any int can be used as a level. 99 100 In an application, you may wish to log messages only at a certain level or greater. 101 One common configuration is to log messages at Info or higher levels, 102 suppressing debug logging until it is needed. 103 The built-in handlers can be configured with the minimum level to output by 104 setting [HandlerOptions.Level]. 105 The program's `main` function typically does this. 106 The default value is LevelInfo. 107 108 Setting the [HandlerOptions.Level] field to a [Level] value 109 fixes the handler's minimum level throughout its lifetime. 110 Setting it to a [LevelVar] allows the level to be varied dynamically. 111 A LevelVar holds a Level and is safe to read or write from multiple 112 goroutines. 113 To vary the level dynamically for an entire program, first initialize 114 a global LevelVar: 115 116 var programLevel = new(slog.LevelVar) // Info by default 117 118 Then use the LevelVar to construct a handler, and make it the default: 119 120 h := slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{Level: programLevel}) 121 slog.SetDefault(slog.New(h)) 122 123 Now the program can change its logging level with a single statement: 124 125 programLevel.Set(slog.LevelDebug) 126 127 # Groups 128 129 Attributes can be collected into groups. 130 A group has a name that is used to qualify the names of its attributes. 131 How this qualification is displayed depends on the handler. 132 [TextHandler] separates the group and attribute names with a dot. 133 [JSONHandler] treats each group as a separate JSON object, with the group name as the key. 134 135 Use [Group] to create a Group attribute from a name and a list of key-value pairs: 136 137 slog.Group("request", 138 "method", r.Method, 139 "url", r.URL) 140 141 TextHandler would display this group as 142 143 request.method=GET request.url=http://example.com 144 145 JSONHandler would display it as 146 147 "request":{"method":"GET","url":"http://example.com"} 148 149 Use [Logger.WithGroup] to qualify all of a Logger's output 150 with a group name. Calling WithGroup on a Logger results in a 151 new Logger with the same Handler as the original, but with all 152 its attributes qualified by the group name. 153 154 This can help prevent duplicate attribute keys in large systems, 155 where subsystems might use the same keys. 156 Pass each subsystem a different Logger with its own group name so that 157 potential duplicates are qualified: 158 159 logger := slog.Default().With("id", systemID) 160 parserLogger := logger.WithGroup("parser") 161 parseInput(input, parserLogger) 162 163 When parseInput logs with parserLogger, its keys will be qualified with "parser", 164 so even if it uses the common key "id", the log line will have distinct keys. 165 166 # Contexts 167 168 Some handlers may wish to include information from the [context.Context] that is 169 available at the call site. One example of such information 170 is the identifier for the current span when tracing is enabled. 171 172 The [Logger.Log] and [Logger.LogAttrs] methods take a context as a first 173 argument, as do their corresponding top-level functions. 174 175 Although the convenience methods on Logger (Info and so on) and the 176 corresponding top-level functions do not take a context, the alternatives ending 177 in "Context" do. For example, 178 179 slog.InfoContext(ctx, "message") 180 181 It is recommended to pass a context to an output method if one is available. 182 183 # Attrs and Values 184 185 An [Attr] is a key-value pair. The Logger output methods accept Attrs as well as 186 alternating keys and values. The statement 187 188 slog.Info("hello", slog.Int("count", 3)) 189 190 behaves the same as 191 192 slog.Info("hello", "count", 3) 193 194 There are convenience constructors for [Attr] such as [Int], [String], and [Bool] 195 for common types, as well as the function [Any] for constructing Attrs of any 196 type. 197 198 The value part of an Attr is a type called [Value]. 199 Like an [any], a Value can hold any Go value, 200 but it can represent typical values, including all numbers and strings, 201 without an allocation. 202 203 For the most efficient log output, use [Logger.LogAttrs]. 204 It is similar to [Logger.Log] but accepts only Attrs, not alternating 205 keys and values; this allows it, too, to avoid allocation. 206 207 The call 208 209 logger.LogAttrs(ctx, slog.LevelInfo, "hello", slog.Int("count", 3)) 210 211 is the most efficient way to achieve the same output as 212 213 slog.InfoContext(ctx, "hello", "count", 3) 214 215 # Customizing a type's logging behavior 216 217 If a type implements the [LogValuer] interface, the [Value] returned from its LogValue 218 method is used for logging. You can use this to control how values of the type 219 appear in logs. For example, you can redact secret information like passwords, 220 or gather a struct's fields in a Group. See the examples under [LogValuer] for 221 details. 222 223 A LogValue method may return a Value that itself implements [LogValuer]. The [Value.Resolve] 224 method handles these cases carefully, avoiding infinite loops and unbounded recursion. 225 Handler authors and others may wish to use [Value.Resolve] instead of calling LogValue directly. 226 227 # Wrapping output methods 228 229 The logger functions use reflection over the call stack to find the file name 230 and line number of the logging call within the application. This can produce 231 incorrect source information for functions that wrap slog. For instance, if you 232 define this function in file mylog.go: 233 234 func Infof(logger *slog.Logger, format string, args ...any) { 235 logger.Info(fmt.Sprintf(format, args...)) 236 } 237 238 and you call it like this in main.go: 239 240 Infof(slog.Default(), "hello, %s", "world") 241 242 then slog will report the source file as mylog.go, not main.go. 243 244 A correct implementation of Infof will obtain the source location 245 (pc) and pass it to NewRecord. 246 The Infof function in the package-level example called "wrapping" 247 demonstrates how to do this. 248 249 # Working with Records 250 251 Sometimes a Handler will need to modify a Record 252 before passing it on to another Handler or backend. 253 A Record contains a mixture of simple public fields (e.g. Time, Level, Message) 254 and hidden fields that refer to state (such as attributes) indirectly. This 255 means that modifying a simple copy of a Record (e.g. by calling 256 [Record.Add] or [Record.AddAttrs] to add attributes) 257 may have unexpected effects on the original. 258 Before modifying a Record, use [Record.Clone] to 259 create a copy that shares no state with the original, 260 or create a new Record with [NewRecord] 261 and build up its Attrs by traversing the old ones with [Record.Attrs]. 262 263 # Performance considerations 264 265 If profiling your application demonstrates that logging is taking significant time, 266 the following suggestions may help. 267 268 If many log lines have a common attribute, use [Logger.With] to create a Logger with 269 that attribute. The built-in handlers will format that attribute only once, at the 270 call to [Logger.With]. The [Handler] interface is designed to allow that optimization, 271 and a well-written Handler should take advantage of it. 272 273 The arguments to a log call are always evaluated, even if the log event is discarded. 274 If possible, defer computation so that it happens only if the value is actually logged. 275 For example, consider the call 276 277 slog.Info("starting request", "url", r.URL.String()) // may compute String unnecessarily 278 279 The URL.String method will be called even if the logger discards Info-level events. 280 Instead, pass the URL directly: 281 282 slog.Info("starting request", "url", &r.URL) // calls URL.String only if needed 283 284 The built-in [TextHandler] will call its String method, but only 285 if the log event is enabled. 286 Avoiding the call to String also preserves the structure of the underlying value. 287 For example [JSONHandler] emits the components of the parsed URL as a JSON object. 288 If you want to avoid eagerly paying the cost of the String call 289 without causing the handler to potentially inspect the structure of the value, 290 wrap the value in a fmt.Stringer implementation that hides its Marshal methods. 291 292 You can also use the [LogValuer] interface to avoid unnecessary work in disabled log 293 calls. Say you need to log some expensive value: 294 295 slog.Debug("frobbing", "value", computeExpensiveValue(arg)) 296 297 Even if this line is disabled, computeExpensiveValue will be called. 298 To avoid that, define a type implementing LogValuer: 299 300 type expensive struct { arg int } 301 302 func (e expensive) LogValue() slog.Value { 303 return slog.AnyValue(computeExpensiveValue(e.arg)) 304 } 305 306 Then use a value of that type in log calls: 307 308 slog.Debug("frobbing", "value", expensive{arg}) 309 310 Now computeExpensiveValue will only be called when the line is enabled. 311 312 The built-in handlers acquire a lock before calling [io.Writer.Write] 313 to ensure that exactly one [Record] is written at a time in its entirety. 314 Although each log record has a timestamp, 315 the built-in handlers do not use that time to sort the written records. 316 User-defined handlers are responsible for their own locking and sorting. 317 318 # Writing a handler 319 320 For a guide to writing a custom handler, see https://golang.org/s/slog-handler-guide. 321 */ 322 package slog 323