Documment logging formats

Co-authored-by: Patrick Ohly <patrick.ohly@intel.com>

1 files changed, 48 insertions, 5 deletions

diff --git a/contributors/devel/sig-instrumentation/logging.md b/contributors/devel/sig-instrumentation/logging.md
index 9ae2aaab..16b6a044 100644
--- a/contributors/devel/sig-instrumentation/logging.md
+++ b/contributors/devel/sig-instrumentation/logging.md
@@ -39,16 +39,36 @@ As per the comments, the practical default level is V(2). Developers and QE
 environments may wish to run at V(3) or V(4). If you wish to change the log
 level, you can pass in `-v=X` where X is the desired maximum level to log.
 
-## Logging header formats
+## Logging Formats
 
-An example logging message is
+Kubernetes supports multiple logging formats to allow users flexibility in picking a format that best matches their needs.
+As new features and logging formats are proposed, we expect that the Kubernetes community might find itself in disagreement about what formats and features should be officially supported.
+This section will serve as a developer documentation describing high level goals of each format, giving a holistic vision of logging options and allowing the community to resolve any future disagreement when making changes.
+
+### Text logging format
+
+* Default format in Kubernetes.
+* Purpose:
+  * Maintain backward compatibility with klog format.
+  * Human-readable
+  * Development
+* Features:
+  * Minimal support for structured metadata - required to maintain backward compatibility.
+  * Marshals object using fmt.Stringer interface allowing to provide a human-readable reference. For example `pod="kube-system/kube-dns"`.
+  * Support for multi-line strings with actual line breaks - allows dumping whole yaml objects for debugging.
+
+Logs written using text format will always have standard header, however message format differ based on whether string formatting (Infof, Errorf, ...) or structured logging method was used to call klog (InfoS, ErrorS).
+
+Examples, first written using Infof, in second InfoS was used.
 ```
-I0528 19:15:22.737538   47512 logtest.go:52] msg...
+I0528 19:15:22.737538   47512 logtest.go:52] Pod kube-system/kube-dns status was updated to ready
+I0528 19:15:22.737538   47512 logtest.go:52] "Pod status was updated" pod="kube-system/kube-dns" status="ready"
 ```
 
-This log line have this form:
+Explanation of header:
 ```
-	Lmmdd hh:mm:ss.uuuuuu threadid file:line] msg...
+Lmmdd hh:mm:ss.uuuuuu threadid file:line] msg...
+
 where the fields are defined as follows:
 	L                A single character, representing the log level (eg 'I' for INFO)
 	mm               The month (zero padded; ie May is '05')
@@ -59,4 +79,27 @@ where the fields are defined as follows:
 	line             The line number
 	msg              The user-supplied message
 ```
+
 See more in [here](https://github.com/kubernetes/klog/blob/9ad246211af1ed84621ee94a26fcce0038b69cd1/klog.go#L581-L597)
+
+### JSON logging format
+
+* Requires passing `--logging-format=json` to enable
+* Purpose:
+  * Provide structured metadata in efficient way.
+  * Optimized for efficient log consumption, processing and querying.
+  * Machine-readable
+* Feature:
+  * Full support for structured metadata, using `logr.MarshalLog` when available.
+  * Multi-line strings are quoted to fit into a single output line.
+
+Example:
+```json
+{"ts": 1580306777.04728,"v": 4,"msg": "Pod status was updated","pod":{"name": "kube-dns","namespace": "kube-system"},"status": "ready"}
+```
+
+Keys with special meaning:
+* ts - timestamp as Unix time (required, float)
+* v - verbosity (only for info and not for error messages, int)
+* err - error string (optional, string)
+* msg - message (required, string)