src/log/slog/record.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 package slog
   6
   7 import (
   8         "runtime"
   9         "slices"
  10         "time"
  11 )
  12
  13 const nAttrsInline = 5
  14
  15 // A Record holds information about a log event.
  16 // Copies of a Record share state.
  17 // Do not modify a Record after handing out a copy to it.
  18 // Use [Record.Clone] to create a copy with no shared state.
  19 type Record struct {
  20         // The time at which the output method (Log, Info, etc.) was called.
  21         Time time.Time
  22
  23         // The log message.
  24         Message string
  25
  26         // The level of the event.
  27         Level Level
  28
  29         // The program counter at the time the record was constructed, as determined
  30         // by runtime.Callers. If zero, no program counter is available.
  31         //
  32         // The only valid use for this value is as an argument to
  33         // [runtime.CallersFrames]. In particular, it must not be passed to
  34         // [runtime.FuncForPC].
  35         PC uintptr
  36
  37         // Allocation optimization: an inline array sized to hold
  38         // the majority of log calls (based on examination of open-source
  39         // code). It holds the start of the list of Attrs.
  40         front [nAttrsInline]Attr
  41
  42         // The number of Attrs in front.
  43         nFront int
  44
  45         // The list of Attrs except for those in front.
  46         // Invariants:
  47         //   - len(back) > 0 iff nFront == len(front)
  48         //   - Unused array elements are zero. Used to detect mistakes.
  49         back []Attr
  50 }
  51
  52 // NewRecord creates a Record from the given arguments.
  53 // Use [Record.AddAttrs] to add attributes to the Record.
  54 //
  55 // NewRecord is intended for logging APIs that want to support a [Handler] as
  56 // a backend.
  57 func NewRecord(t time.Time, level Level, msg string, pc uintptr) Record {
  58         return Record{
  59                 Time:    t,
  60                 Message: msg,
  61                 Level:   level,
  62                 PC:      pc,
  63         }
  64 }
  65
  66 // frame returns the runtime.Frame of the log event.
  67 // If the Record was created without the necessary information,
  68 // or if the location is unavailable, it returns a zero Frame.
  69 func (r Record) frame() runtime.Frame {
  70         fs := runtime.CallersFrames([]uintptr{r.PC})
  71         f, _ := fs.Next()
  72         return f
  73 }
  74
  75 // Clone returns a copy of the record with no shared state.
  76 // The original record and the clone can both be modified
  77 // without interfering with each other.
  78 func (r Record) Clone() Record {
  79         r.back = slices.Clip(r.back) // prevent append from mutating shared array
  80         return r
  81 }
  82
  83 // NumAttrs returns the number of attributes in the Record.
  84 func (r Record) NumAttrs() int {
  85         return r.nFront + len(r.back)
  86 }
  87
  88 // Attrs calls f on each Attr in the Record.
  89 // Iteration stops if f returns false.
  90 func (r Record) Attrs(f func(Attr) bool) {
  91         for i := 0; i < r.nFront; i++ {
  92                 if !f(r.front[i]) {
  93                         return
  94                 }
  95         }
  96         for _, a := range r.back {
  97                 if !f(a) {
  98                         return
  99                 }
 100         }
 101 }
 102
 103 // AddAttrs appends the given Attrs to the Record's list of Attrs.
 104 func (r *Record) AddAttrs(attrs ...Attr) {
 105         n := copy(r.front[r.nFront:], attrs)
 106         r.nFront += n
 107         // Check if a copy was modified by slicing past the end
 108         // and seeing if the Attr there is non-zero.
 109         if cap(r.back) > len(r.back) {
 110                 end := r.back[:len(r.back)+1][len(r.back)]
 111                 if !end.isEmpty() {
 112                         panic("copies of a slog.Record were both modified")
 113                 }
 114         }
 115         r.back = append(r.back, attrs[n:]...)
 116 }
 117
 118 // Add converts the args to Attrs as described in [Logger.Log],
 119 // then appends the Attrs to the Record's list of Attrs.
 120 func (r *Record) Add(args ...any) {
 121         var a Attr
 122         for len(args) > 0 {
 123                 a, args = argsToAttr(args)
 124                 if r.nFront < len(r.front) {
 125                         r.front[r.nFront] = a
 126                         r.nFront++
 127                 } else {
 128                         if r.back == nil {
 129                                 r.back = make([]Attr, 0, countAttrs(args))
 130                         }
 131                         r.back = append(r.back, a)
 132                 }
 133         }
 134
 135 }
 136
 137 // countAttrs returns the number of Attrs that would be created from args.
 138 func countAttrs(args []any) int {
 139         n := 0
 140         for i := 0; i < len(args); i++ {
 141                 n++
 142                 if _, ok := args[i].(string); ok {
 143                         i++
 144                 }
 145         }
 146         return n
 147 }
 148
 149 const badKey = "!BADKEY"
 150
 151 // argsToAttr turns a prefix of the nonempty args slice into an Attr
 152 // and returns the unconsumed portion of the slice.
 153 // If args[0] is an Attr, it returns it.
 154 // If args[0] is a string, it treats the first two elements as
 155 // a key-value pair.
 156 // Otherwise, it treats args[0] as a value with a missing key.
 157 func argsToAttr(args []any) (Attr, []any) {
 158         switch x := args[0].(type) {
 159         case string:
 160                 if len(args) == 1 {
 161                         return String(badKey, x), nil
 162                 }
 163                 return Any(x, args[1]), args[2:]
 164
 165         case Attr:
 166                 return x, args[1:]
 167
 168         default:
 169                 return Any(badKey, x), args[1:]
 170         }
 171 }