keyvalues.go 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355
  1. /*
  2. Copyright 2021 The Kubernetes Authors.
  3. Licensed under the Apache License, Version 2.0 (the "License");
  4. you may not use this file except in compliance with the License.
  5. You may obtain a copy of the License at
  6. http://www.apache.org/licenses/LICENSE-2.0
  7. Unless required by applicable law or agreed to in writing, software
  8. distributed under the License is distributed on an "AS IS" BASIS,
  9. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  10. See the License for the specific language governing permissions and
  11. limitations under the License.
  12. */
  13. package serialize
  14. import (
  15. "bytes"
  16. "encoding/json"
  17. "fmt"
  18. "strconv"
  19. "github.com/go-logr/logr"
  20. )
  21. type textWriter interface {
  22. WriteText(*bytes.Buffer)
  23. }
  24. // WithValues implements LogSink.WithValues. The old key/value pairs are
  25. // assumed to be well-formed, the new ones are checked and padded if
  26. // necessary. It returns a new slice.
  27. func WithValues(oldKV, newKV []interface{}) []interface{} {
  28. if len(newKV) == 0 {
  29. return oldKV
  30. }
  31. newLen := len(oldKV) + len(newKV)
  32. hasMissingValue := newLen%2 != 0
  33. if hasMissingValue {
  34. newLen++
  35. }
  36. // The new LogSink must have its own slice.
  37. kv := make([]interface{}, 0, newLen)
  38. kv = append(kv, oldKV...)
  39. kv = append(kv, newKV...)
  40. if hasMissingValue {
  41. kv = append(kv, missingValue)
  42. }
  43. return kv
  44. }
  45. // MergeKVs deduplicates elements provided in two key/value slices.
  46. //
  47. // Keys in each slice are expected to be unique, so duplicates can only occur
  48. // when the first and second slice contain the same key. When that happens, the
  49. // key/value pair from the second slice is used. The first slice must be well-formed
  50. // (= even key/value pairs). The second one may have a missing value, in which
  51. // case the special "missing value" is added to the result.
  52. func MergeKVs(first, second []interface{}) []interface{} {
  53. maxLength := len(first) + (len(second)+1)/2*2
  54. if maxLength == 0 {
  55. // Nothing to do at all.
  56. return nil
  57. }
  58. if len(first) == 0 && len(second)%2 == 0 {
  59. // Nothing to be overridden, second slice is well-formed
  60. // and can be used directly.
  61. return second
  62. }
  63. // Determine which keys are in the second slice so that we can skip
  64. // them when iterating over the first one. The code intentionally
  65. // favors performance over completeness: we assume that keys are string
  66. // constants and thus compare equal when the string values are equal. A
  67. // string constant being overridden by, for example, a fmt.Stringer is
  68. // not handled.
  69. overrides := map[interface{}]bool{}
  70. for i := 0; i < len(second); i += 2 {
  71. overrides[second[i]] = true
  72. }
  73. merged := make([]interface{}, 0, maxLength)
  74. for i := 0; i+1 < len(first); i += 2 {
  75. key := first[i]
  76. if overrides[key] {
  77. continue
  78. }
  79. merged = append(merged, key, first[i+1])
  80. }
  81. merged = append(merged, second...)
  82. if len(merged)%2 != 0 {
  83. merged = append(merged, missingValue)
  84. }
  85. return merged
  86. }
  87. type Formatter struct {
  88. AnyToStringHook AnyToStringFunc
  89. }
  90. type AnyToStringFunc func(v interface{}) string
  91. // MergeKVsInto is a variant of MergeKVs which directly formats the key/value
  92. // pairs into a buffer.
  93. func (f Formatter) MergeAndFormatKVs(b *bytes.Buffer, first, second []interface{}) {
  94. if len(first) == 0 && len(second) == 0 {
  95. // Nothing to do at all.
  96. return
  97. }
  98. if len(first) == 0 && len(second)%2 == 0 {
  99. // Nothing to be overridden, second slice is well-formed
  100. // and can be used directly.
  101. for i := 0; i < len(second); i += 2 {
  102. f.KVFormat(b, second[i], second[i+1])
  103. }
  104. return
  105. }
  106. // Determine which keys are in the second slice so that we can skip
  107. // them when iterating over the first one. The code intentionally
  108. // favors performance over completeness: we assume that keys are string
  109. // constants and thus compare equal when the string values are equal. A
  110. // string constant being overridden by, for example, a fmt.Stringer is
  111. // not handled.
  112. overrides := map[interface{}]bool{}
  113. for i := 0; i < len(second); i += 2 {
  114. overrides[second[i]] = true
  115. }
  116. for i := 0; i < len(first); i += 2 {
  117. key := first[i]
  118. if overrides[key] {
  119. continue
  120. }
  121. f.KVFormat(b, key, first[i+1])
  122. }
  123. // Round down.
  124. l := len(second)
  125. l = l / 2 * 2
  126. for i := 1; i < l; i += 2 {
  127. f.KVFormat(b, second[i-1], second[i])
  128. }
  129. if len(second)%2 == 1 {
  130. f.KVFormat(b, second[len(second)-1], missingValue)
  131. }
  132. }
  133. func MergeAndFormatKVs(b *bytes.Buffer, first, second []interface{}) {
  134. Formatter{}.MergeAndFormatKVs(b, first, second)
  135. }
  136. const missingValue = "(MISSING)"
  137. // KVListFormat serializes all key/value pairs into the provided buffer.
  138. // A space gets inserted before the first pair and between each pair.
  139. func (f Formatter) KVListFormat(b *bytes.Buffer, keysAndValues ...interface{}) {
  140. for i := 0; i < len(keysAndValues); i += 2 {
  141. var v interface{}
  142. k := keysAndValues[i]
  143. if i+1 < len(keysAndValues) {
  144. v = keysAndValues[i+1]
  145. } else {
  146. v = missingValue
  147. }
  148. f.KVFormat(b, k, v)
  149. }
  150. }
  151. func KVListFormat(b *bytes.Buffer, keysAndValues ...interface{}) {
  152. Formatter{}.KVListFormat(b, keysAndValues...)
  153. }
  154. // KVFormat serializes one key/value pair into the provided buffer.
  155. // A space gets inserted before the pair.
  156. func (f Formatter) KVFormat(b *bytes.Buffer, k, v interface{}) {
  157. b.WriteByte(' ')
  158. // Keys are assumed to be well-formed according to
  159. // https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/migration-to-structured-logging.md#name-arguments
  160. // for the sake of performance. Keys with spaces,
  161. // special characters, etc. will break parsing.
  162. if sK, ok := k.(string); ok {
  163. // Avoid one allocation when the key is a string, which
  164. // normally it should be.
  165. b.WriteString(sK)
  166. } else {
  167. b.WriteString(fmt.Sprintf("%s", k))
  168. }
  169. // The type checks are sorted so that more frequently used ones
  170. // come first because that is then faster in the common
  171. // cases. In Kubernetes, ObjectRef (a Stringer) is more common
  172. // than plain strings
  173. // (https://github.com/kubernetes/kubernetes/pull/106594#issuecomment-975526235).
  174. switch v := v.(type) {
  175. case textWriter:
  176. writeTextWriterValue(b, v)
  177. case fmt.Stringer:
  178. writeStringValue(b, StringerToString(v))
  179. case string:
  180. writeStringValue(b, v)
  181. case error:
  182. writeStringValue(b, ErrorToString(v))
  183. case logr.Marshaler:
  184. value := MarshalerToValue(v)
  185. // A marshaler that returns a string is useful for
  186. // delayed formatting of complex values. We treat this
  187. // case like a normal string. This is useful for
  188. // multi-line support.
  189. //
  190. // We could do this by recursively formatting a value,
  191. // but that comes with the risk of infinite recursion
  192. // if a marshaler returns itself. Instead we call it
  193. // only once and rely on it returning the intended
  194. // value directly.
  195. switch value := value.(type) {
  196. case string:
  197. writeStringValue(b, value)
  198. default:
  199. f.formatAny(b, value)
  200. }
  201. case []byte:
  202. // In https://github.com/kubernetes/klog/pull/237 it was decided
  203. // to format byte slices with "%+q". The advantages of that are:
  204. // - readable output if the bytes happen to be printable
  205. // - non-printable bytes get represented as unicode escape
  206. // sequences (\uxxxx)
  207. //
  208. // The downsides are that we cannot use the faster
  209. // strconv.Quote here and that multi-line output is not
  210. // supported. If developers know that a byte array is
  211. // printable and they want multi-line output, they can
  212. // convert the value to string before logging it.
  213. b.WriteByte('=')
  214. b.WriteString(fmt.Sprintf("%+q", v))
  215. default:
  216. f.formatAny(b, v)
  217. }
  218. }
  219. func KVFormat(b *bytes.Buffer, k, v interface{}) {
  220. Formatter{}.KVFormat(b, k, v)
  221. }
  222. // formatAny is the fallback formatter for a value. It supports a hook (for
  223. // example, for YAML encoding) and itself uses JSON encoding.
  224. func (f Formatter) formatAny(b *bytes.Buffer, v interface{}) {
  225. b.WriteRune('=')
  226. if f.AnyToStringHook != nil {
  227. b.WriteString(f.AnyToStringHook(v))
  228. return
  229. }
  230. encoder := json.NewEncoder(b)
  231. l := b.Len()
  232. if err := encoder.Encode(v); err != nil {
  233. // This shouldn't happen. We discard whatever the encoder
  234. // wrote and instead dump an error string.
  235. b.Truncate(l)
  236. b.WriteString(fmt.Sprintf(`"<internal error: %v>"`, err))
  237. return
  238. }
  239. // Remove trailing newline.
  240. b.Truncate(b.Len() - 1)
  241. }
  242. // StringerToString converts a Stringer to a string,
  243. // handling panics if they occur.
  244. func StringerToString(s fmt.Stringer) (ret string) {
  245. defer func() {
  246. if err := recover(); err != nil {
  247. ret = fmt.Sprintf("<panic: %s>", err)
  248. }
  249. }()
  250. ret = s.String()
  251. return
  252. }
  253. // MarshalerToValue invokes a marshaler and catches
  254. // panics.
  255. func MarshalerToValue(m logr.Marshaler) (ret interface{}) {
  256. defer func() {
  257. if err := recover(); err != nil {
  258. ret = fmt.Sprintf("<panic: %s>", err)
  259. }
  260. }()
  261. ret = m.MarshalLog()
  262. return
  263. }
  264. // ErrorToString converts an error to a string,
  265. // handling panics if they occur.
  266. func ErrorToString(err error) (ret string) {
  267. defer func() {
  268. if err := recover(); err != nil {
  269. ret = fmt.Sprintf("<panic: %s>", err)
  270. }
  271. }()
  272. ret = err.Error()
  273. return
  274. }
  275. func writeTextWriterValue(b *bytes.Buffer, v textWriter) {
  276. b.WriteByte('=')
  277. defer func() {
  278. if err := recover(); err != nil {
  279. fmt.Fprintf(b, `"<panic: %s>"`, err)
  280. }
  281. }()
  282. v.WriteText(b)
  283. }
  284. func writeStringValue(b *bytes.Buffer, v string) {
  285. data := []byte(v)
  286. index := bytes.IndexByte(data, '\n')
  287. if index == -1 {
  288. b.WriteByte('=')
  289. // Simple string, quote quotation marks and non-printable characters.
  290. b.WriteString(strconv.Quote(v))
  291. return
  292. }
  293. // Complex multi-line string, show as-is with indention like this:
  294. // I... "hello world" key=<
  295. // <tab>line 1
  296. // <tab>line 2
  297. // >
  298. //
  299. // Tabs indent the lines of the value while the end of string delimiter
  300. // is indented with a space. That has two purposes:
  301. // - visual difference between the two for a human reader because indention
  302. // will be different
  303. // - no ambiguity when some value line starts with the end delimiter
  304. //
  305. // One downside is that the output cannot distinguish between strings that
  306. // end with a line break and those that don't because the end delimiter
  307. // will always be on the next line.
  308. b.WriteString("=<\n")
  309. for index != -1 {
  310. b.WriteByte('\t')
  311. b.Write(data[0 : index+1])
  312. data = data[index+1:]
  313. index = bytes.IndexByte(data, '\n')
  314. }
  315. if len(data) == 0 {
  316. // String ended with line break, don't add another.
  317. b.WriteString(" >")
  318. } else {
  319. // No line break at end of last line, write rest of string and
  320. // add one.
  321. b.WriteByte('\t')
  322. b.Write(data)
  323. b.WriteString("\n >")
  324. }
  325. }