Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

update migration-to-structured-logging.md #6719

Merged
merged 1 commit into from
Jun 30, 2022
Merged

update migration-to-structured-logging.md #6719

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
17 changes: 14 additions & 3 deletions contributors/devel/sig-instrumentation/migration-to-structured-logging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,15 @@ func KObj(obj KMetadata) ObjectRef
// >> I1025 00:15:15.525108 1 controller_utils.go:116] "Pod status updated" pod="kube-system/kubedns" status="ready"
func KRef(namespace, name string) ObjectRef

// KObjSlice takes a slice of objects that implement the KMetadata interface
// and returns an object that gets logged as a slice of ObjectRef values or a
// string containing those values, depending on whether the logger prefers text
// output or structured output.
// >> klog.InfoS("Pods status updated", "pods", klog.KObjSlice(pods), "status", "ready")
// output:
// >> I1025 00:15:15.525108 1 controller_utils.go:116] "Pods status updated" pods="[kube-system/kubedns kube-system/metrics-server]" status="ready"
func KObjSlice(arg interface{}) interface{}

// ObjectRef represents a reference to a kubernetes object used for logging purpose
// In text logs it is serialized into "{namespace}/{name}" or "{name}" if namespace is empty
type ObjectRef struct {
Expand Down Expand Up @@ -467,16 +476,18 @@ func ChangePodStatus(newStatus, currentStatus string) {
## Good practice for passing values in structured logging

When passing a value for a key-value pair, please use following rules:
* Prefer using Kubernetes objects (for example `*v1.Pod`) and log them using `klog.KObj`
* Prefer using Kubernetes objects and log them using `klog.KObj` or `klog.KObjSlice`
* When the original object is not available, use `klog.KRef` instead
* when only one object (for example `*v1.Pod`), we use`klog.KObj`
* When type is object slice (for example `[]*v1.Pod`), we use `klog.KObjSlice`
* Pass structured values directly (avoid calling `.String()` on them first)
* When the goal is to log a `[]byte` array as string, explicitly convert with `string(<byte array>)`.

### Prefer using Kubernetes objects (for example `*v1.Pod`) and log them using `klog.KObj`
### Prefer using Kubernetes objects (for example `*v1.Pod` or `[]*v1.Pod`) and log them using `klog.KObj` or `klog.KObjSlice`

As part of the structured logging migration, we want to ensure that Kubernetes object references are
consistent within the
codebase. Two new utility functions were introduced to klog: `klog.KObj` and `klog.KRef`.
codebase. Three new utility functions were introduced to klog: `klog.KObj` `klog.KObjSlice` and `klog.KRef`.

Any existing logging code that makes a reference (such as name, namespace) to a Kubernetes
object (for example: Pod, Node, Deployment, CustomResourceDefinition) should be rewritten to
Expand Down