working commit

2026-03-13 19:02:42 +02:00
parent bebbf79c7a
commit 5c1da77f4c
1329 changed files with 314708 additions and 39 deletions
@@ -0,0 +1,170 @@
+/*
+Copyright 2017 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package buffer
+
+// defaultRingSize defines the default ring size if not specified
+const defaultRingSize = 16
+
+// RingGrowingOptions sets parameters for [RingGrowing] and
+// [TypedRingGrowing].
+type RingGrowingOptions struct {
+	// InitialSize is the number of pre-allocated elements in the
+	// initial underlying storage buffer.
+	InitialSize int
+}
+
+// RingGrowing is a growing ring buffer.
+// Not thread safe.
+//
+// Deprecated: Use TypedRingGrowing[any] instead.
+type RingGrowing = TypedRingGrowing[any]
+
+// NewRingGrowing constructs a new RingGrowing instance with provided parameters.
+//
+// Deprecated: Use NewTypedRingGrowing[any] instead.
+func NewRingGrowing(initialSize int) *RingGrowing {
+	return NewTypedRingGrowing[any](RingGrowingOptions{InitialSize: initialSize})
+}
+
+// TypedRingGrowing is a growing ring buffer.
+// The zero value has an initial size of 0 and is ready to use.
+// Not thread safe.
+type TypedRingGrowing[T any] struct {
+	data     []T
+	n        int // Size of Data
+	beg      int // First available element
+	readable int // Number of data items available
+}
+
+// NewTypedRingGrowing constructs a new TypedRingGrowing instance with provided parameters.
+func NewTypedRingGrowing[T any](opts RingGrowingOptions) *TypedRingGrowing[T] {
+	return &TypedRingGrowing[T]{
+		data: make([]T, opts.InitialSize),
+		n:    opts.InitialSize,
+	}
+}
+
+// ReadOne reads (consumes) first item from the buffer if it is available, otherwise returns false.
+func (r *TypedRingGrowing[T]) ReadOne() (data T, ok bool) {
+	if r.readable == 0 {
+		return
+	}
+	r.readable--
+	element := r.data[r.beg]
+	var zero T
+	r.data[r.beg] = zero // Remove reference to the object to help GC
+	if r.beg == r.n-1 {
+		// Was the last element
+		r.beg = 0
+	} else {
+		r.beg++
+	}
+	return element, true
+}
+
+// WriteOne adds an item to the end of the buffer, growing it if it is full.
+func (r *TypedRingGrowing[T]) WriteOne(data T) {
+	if r.readable == r.n {
+		// Time to grow
+		newN := r.n * 2
+		if newN == 0 {
+			newN = defaultRingSize
+		}
+		newData := make([]T, newN)
+		to := r.beg + r.readable
+		if to <= r.n {
+			copy(newData, r.data[r.beg:to])
+		} else {
+			copied := copy(newData, r.data[r.beg:])
+			copy(newData[copied:], r.data[:(to%r.n)])
+		}
+		r.beg = 0
+		r.data = newData
+		r.n = newN
+	}
+	r.data[(r.readable+r.beg)%r.n] = data
+	r.readable++
+}
+
+// Len returns the number of items in the buffer.
+func (r *TypedRingGrowing[T]) Len() int {
+	return r.readable
+}
+
+// Cap returns the capacity of the buffer.
+func (r *TypedRingGrowing[T]) Cap() int {
+	return r.n
+}
+
+// RingOptions sets parameters for [Ring].
+type RingOptions struct {
+	// InitialSize is the number of pre-allocated elements in the
+	// initial underlying storage buffer.
+	InitialSize int
+	// NormalSize is the number of elements to allocate for new storage
+	// buffers once the Ring is consumed and
+	// can shrink again.
+	NormalSize int
+}
+
+// Ring is a dynamically-sized ring buffer which can grow and shrink as-needed.
+// The zero value has an initial size and normal size of 0 and is ready to use.
+// Not thread safe.
+type Ring[T any] struct {
+	growing    TypedRingGrowing[T]
+	normalSize int // Limits the size of the buffer that is kept for reuse. Read-only.
+}
+
+// NewRing constructs a new Ring instance with provided parameters.
+func NewRing[T any](opts RingOptions) *Ring[T] {
+	return &Ring[T]{
+		growing:    *NewTypedRingGrowing[T](RingGrowingOptions{InitialSize: opts.InitialSize}),
+		normalSize: opts.NormalSize,
+	}
+}
+
+// ReadOne reads (consumes) first item from the buffer if it is available,
+// otherwise returns false. When the buffer has been totally consumed and has
+// grown in size beyond its normal size, it shrinks down to its normal size again.
+func (r *Ring[T]) ReadOne() (data T, ok bool) {
+	element, ok := r.growing.ReadOne()
+
+	if r.growing.readable == 0 && r.growing.n > r.normalSize {
+		// The buffer is empty. Reallocate a new buffer so the old one can be
+		// garbage collected.
+		r.growing.data = make([]T, r.normalSize)
+		r.growing.n = r.normalSize
+		r.growing.beg = 0
+	}
+
+	return element, ok
+}
+
+// WriteOne adds an item to the end of the buffer, growing it if it is full.
+func (r *Ring[T]) WriteOne(data T) {
+	r.growing.WriteOne(data)
+}
+
+// Len returns the number of items in the buffer.
+func (r *Ring[T]) Len() int {
+	return r.growing.Len()
+}
+
+// Cap returns the capacity of the buffer.
+func (r *Ring[T]) Cap() int {
+	return r.growing.Cap()
+}
@@ -0,0 +1,5 @@
+# Exec
+
+This package provides an interface for `os/exec`. It makes it easier to mock
+and replace in tests, especially with the [FakeExec](testing/fake_exec.go)
+struct.
@@ -0,0 +1,18 @@
+/*
+Copyright 2017 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package exec provides an injectable interface and implementations for running commands.
+package exec // import "k8s.io/utils/exec"
@@ -0,0 +1,256 @@
+/*
+Copyright 2017 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package exec
+
+import (
+	"context"
+	"io"
+	"io/fs"
+	osexec "os/exec"
+	"syscall"
+	"time"
+)
+
+// ErrExecutableNotFound is returned if the executable is not found.
+var ErrExecutableNotFound = osexec.ErrNotFound
+
+// Interface is an interface that presents a subset of the os/exec API. Use this
+// when you want to inject fakeable/mockable exec behavior.
+type Interface interface {
+	// Command returns a Cmd instance which can be used to run a single command.
+	// This follows the pattern of package os/exec.
+	Command(cmd string, args ...string) Cmd
+
+	// CommandContext returns a Cmd instance which can be used to run a single command.
+	//
+	// The provided context is used to kill the process if the context becomes done
+	// before the command completes on its own. For example, a timeout can be set in
+	// the context.
+	CommandContext(ctx context.Context, cmd string, args ...string) Cmd
+
+	// LookPath wraps os/exec.LookPath
+	LookPath(file string) (string, error)
+}
+
+// Cmd is an interface that presents an API that is very similar to Cmd from os/exec.
+// As more functionality is needed, this can grow. Since Cmd is a struct, we will have
+// to replace fields with get/set method pairs.
+type Cmd interface {
+	// Run runs the command to the completion.
+	Run() error
+	// CombinedOutput runs the command and returns its combined standard output
+	// and standard error. This follows the pattern of package os/exec.
+	CombinedOutput() ([]byte, error)
+	// Output runs the command and returns standard output, but not standard err
+	Output() ([]byte, error)
+	SetDir(dir string)
+	SetStdin(in io.Reader)
+	SetStdout(out io.Writer)
+	SetStderr(out io.Writer)
+	SetEnv(env []string)
+
+	// StdoutPipe and StderrPipe for getting the process' Stdout and Stderr as
+	// Readers
+	StdoutPipe() (io.ReadCloser, error)
+	StderrPipe() (io.ReadCloser, error)
+
+	// Start and Wait are for running a process non-blocking
+	Start() error
+	Wait() error
+
+	// Stops the command by sending SIGTERM. It is not guaranteed the
+	// process will stop before this function returns. If the process is not
+	// responding, an internal timer function will send a SIGKILL to force
+	// terminate after 10 seconds.
+	Stop()
+}
+
+// ExitError is an interface that presents an API similar to os.ProcessState, which is
+// what ExitError from os/exec is. This is designed to make testing a bit easier and
+// probably loses some of the cross-platform properties of the underlying library.
+type ExitError interface {
+	String() string
+	Error() string
+	Exited() bool
+	ExitStatus() int
+}
+
+// Implements Interface in terms of really exec()ing.
+type executor struct{}
+
+// New returns a new Interface which will os/exec to run commands.
+func New() Interface {
+	return &executor{}
+}
+
+// Command is part of the Interface interface.
+func (executor *executor) Command(cmd string, args ...string) Cmd {
+	return (*cmdWrapper)(maskErrDotCmd(osexec.Command(cmd, args...)))
+}
+
+// CommandContext is part of the Interface interface.
+func (executor *executor) CommandContext(ctx context.Context, cmd string, args ...string) Cmd {
+	return (*cmdWrapper)(maskErrDotCmd(osexec.CommandContext(ctx, cmd, args...)))
+}
+
+// LookPath is part of the Interface interface
+func (executor *executor) LookPath(file string) (string, error) {
+	path, err := osexec.LookPath(file)
+	return path, handleError(maskErrDot(err))
+}
+
+// Wraps exec.Cmd so we can capture errors.
+type cmdWrapper osexec.Cmd
+
+var _ Cmd = &cmdWrapper{}
+
+func (cmd *cmdWrapper) SetDir(dir string) {
+	cmd.Dir = dir
+}
+
+func (cmd *cmdWrapper) SetStdin(in io.Reader) {
+	cmd.Stdin = in
+}
+
+func (cmd *cmdWrapper) SetStdout(out io.Writer) {
+	cmd.Stdout = out
+}
+
+func (cmd *cmdWrapper) SetStderr(out io.Writer) {
+	cmd.Stderr = out
+}
+
+func (cmd *cmdWrapper) SetEnv(env []string) {
+	cmd.Env = env
+}
+
+func (cmd *cmdWrapper) StdoutPipe() (io.ReadCloser, error) {
+	r, err := (*osexec.Cmd)(cmd).StdoutPipe()
+	return r, handleError(err)
+}
+
+func (cmd *cmdWrapper) StderrPipe() (io.ReadCloser, error) {
+	r, err := (*osexec.Cmd)(cmd).StderrPipe()
+	return r, handleError(err)
+}
+
+func (cmd *cmdWrapper) Start() error {
+	err := (*osexec.Cmd)(cmd).Start()
+	return handleError(err)
+}
+
+func (cmd *cmdWrapper) Wait() error {
+	err := (*osexec.Cmd)(cmd).Wait()
+	return handleError(err)
+}
+
+// Run is part of the Cmd interface.
+func (cmd *cmdWrapper) Run() error {
+	err := (*osexec.Cmd)(cmd).Run()
+	return handleError(err)
+}
+
+// CombinedOutput is part of the Cmd interface.
+func (cmd *cmdWrapper) CombinedOutput() ([]byte, error) {
+	out, err := (*osexec.Cmd)(cmd).CombinedOutput()
+	return out, handleError(err)
+}
+
+func (cmd *cmdWrapper) Output() ([]byte, error) {
+	out, err := (*osexec.Cmd)(cmd).Output()
+	return out, handleError(err)
+}
+
+// Stop is part of the Cmd interface.
+func (cmd *cmdWrapper) Stop() {
+	c := (*osexec.Cmd)(cmd)
+
+	if c.Process == nil {
+		return
+	}
+
+	c.Process.Signal(syscall.SIGTERM)
+
+	time.AfterFunc(10*time.Second, func() {
+		if !c.ProcessState.Exited() {
+			c.Process.Signal(syscall.SIGKILL)
+		}
+	})
+}
+
+func handleError(err error) error {
+	if err == nil {
+		return nil
+	}
+
+	switch e := err.(type) {
+	case *osexec.ExitError:
+		return &ExitErrorWrapper{e}
+	case *fs.PathError:
+		return ErrExecutableNotFound
+	case *osexec.Error:
+		if e.Err == osexec.ErrNotFound {
+			return ErrExecutableNotFound
+		}
+	}
+
+	return err
+}
+
+// ExitErrorWrapper is an implementation of ExitError in terms of os/exec ExitError.
+// Note: standard exec.ExitError is type *os.ProcessState, which already implements Exited().
+type ExitErrorWrapper struct {
+	*osexec.ExitError
+}
+
+var _ ExitError = &ExitErrorWrapper{}
+
+// ExitStatus is part of the ExitError interface.
+func (eew ExitErrorWrapper) ExitStatus() int {
+	ws, ok := eew.Sys().(syscall.WaitStatus)
+	if !ok {
+		panic("can't call ExitStatus() on a non-WaitStatus exitErrorWrapper")
+	}
+	return ws.ExitStatus()
+}
+
+// CodeExitError is an implementation of ExitError consisting of an error object
+// and an exit code (the upper bits of os.exec.ExitStatus).
+type CodeExitError struct {
+	Err  error
+	Code int
+}
+
+var _ ExitError = CodeExitError{}
+
+func (e CodeExitError) Error() string {
+	return e.Err.Error()
+}
+
+func (e CodeExitError) String() string {
+	return e.Err.Error()
+}
+
+// Exited is to check if the process has finished
+func (e CodeExitError) Exited() bool {
+	return true
+}
+
+// ExitStatus is for checking the error code
+func (e CodeExitError) ExitStatus() int {
+	return e.Code
+}
@@ -0,0 +1,32 @@
+//go:build !go1.19
+// +build !go1.19
+
+/*
+Copyright 2022 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package exec
+
+import (
+	osexec "os/exec"
+)
+
+func maskErrDotCmd(cmd *osexec.Cmd) *osexec.Cmd {
+	return cmd
+}
+
+func maskErrDot(err error) error {
+	return err
+}
@@ -0,0 +1,40 @@
+//go:build go1.19
+// +build go1.19
+
+/*
+Copyright 2022 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package exec
+
+import (
+	"errors"
+	osexec "os/exec"
+)
+
+// maskErrDotCmd reverts the behavior of osexec.Cmd to what it was before go1.19
+// specifically set the Err field to nil (LookPath returns a new error when the file
+// is resolved to the current directory.
+func maskErrDotCmd(cmd *osexec.Cmd) *osexec.Cmd {
+	cmd.Err = maskErrDot(cmd.Err)
+	return cmd
+}
+
+func maskErrDot(err error) error {
+	if err != nil && errors.Is(err, osexec.ErrDot) {
+		return nil
+	}
+	return err
+}
@@ -0,0 +1,67 @@
+# Trace
+
+This package provides an interface for recording the latency of operations and logging details
+about all operations where the latency exceeds a limit.
+
+## Usage
+
+To create a trace:
+
+```go
+func doSomething() {
+    opTrace := trace.New("operation", Field{Key: "fieldKey1", Value: "fieldValue1"})
+    defer opTrace.LogIfLong(100 * time.Millisecond)
+    // do something
+}
+```
+
+To split an trace into multiple steps:
+
+```go
+func doSomething() {
+    opTrace := trace.New("operation")
+    defer opTrace.LogIfLong(100 * time.Millisecond)
+    // do step 1
+    opTrace.Step("step1", Field{Key: "stepFieldKey1", Value: "stepFieldValue1"})
+    // do step 2
+    opTrace.Step("step2")
+}
+```
+
+To nest traces:
+
+```go
+func doSomething() {
+    rootTrace := trace.New("rootOperation")
+    defer rootTrace.LogIfLong(100 * time.Millisecond)
+    
+    func() {
+        nestedTrace := rootTrace.Nest("nested", Field{Key: "nestedFieldKey1", Value: "nestedFieldValue1"})
+        defer nestedTrace.LogIfLong(50 * time.Millisecond)
+        // do nested operation
+    }()
+}
+```
+
+Traces can also be logged unconditionally or introspected:
+
+```go
+opTrace.TotalTime() // Duration since the Trace was created
+opTrace.Log() // unconditionally log the trace
+```
+
+### Using context.Context to nest traces
+
+`context.Context` can be used to manage nested traces. Create traces by calling `trace.GetTraceFromContext(ctx).Nest`. 
+This is safe even if there is no parent trace already in the context because `(*(Trace)nil).Nest()` returns
+a top level trace.
+
+```go
+func doSomething(ctx context.Context) {
+    opTrace := trace.FromContext(ctx).Nest("operation") // create a trace, possibly nested
+    ctx = trace.ContextWithTrace(ctx, opTrace) // make this trace the parent trace of the context
+    defer opTrace.LogIfLong(50 * time.Millisecond)
+    
+    doSomethingElse(ctx)
+}
+```
@@ -0,0 +1,319 @@
+/*
+Copyright 2015 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package trace
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"math/rand"
+	"sync"
+	"time"
+
+	"k8s.io/klog/v2"
+)
+
+var klogV = func(lvl klog.Level) bool {
+	return klog.V(lvl).Enabled()
+}
+
+// Field is a key value pair that provides additional details about the trace.
+type Field struct {
+	Key   string
+	Value interface{}
+}
+
+func (f Field) format() string {
+	return fmt.Sprintf("%s:%v", f.Key, f.Value)
+}
+
+func writeFields(b *bytes.Buffer, l []Field) {
+	for i, f := range l {
+		b.WriteString(f.format())
+		if i < len(l)-1 {
+			b.WriteString(",")
+		}
+	}
+}
+
+func writeTraceItemSummary(b *bytes.Buffer, msg string, totalTime time.Duration, startTime time.Time, fields []Field) {
+	b.WriteString(fmt.Sprintf("%q ", msg))
+	if len(fields) > 0 {
+		writeFields(b, fields)
+		b.WriteString(" ")
+	}
+
+	b.WriteString(fmt.Sprintf("%vms (%v)", durationToMilliseconds(totalTime), startTime.Format("15:04:05.000")))
+}
+
+func durationToMilliseconds(timeDuration time.Duration) int64 {
+	return timeDuration.Nanoseconds() / 1e6
+}
+
+type traceItem interface {
+	// rLock must be called before invoking time or writeItem.
+	rLock()
+	// rUnlock must be called after processing the item is complete.
+	rUnlock()
+
+	// time returns when the trace was recorded as completed.
+	time() time.Time
+	// writeItem outputs the traceItem to the buffer. If stepThreshold is non-nil, only output the
+	// traceItem if its the duration exceeds the stepThreshold.
+	// Each line of output is prefixed by formatter to visually indent nested items.
+	writeItem(b *bytes.Buffer, formatter string, startTime time.Time, stepThreshold *time.Duration)
+}
+
+type traceStep struct {
+	stepTime time.Time
+	msg      string
+	fields   []Field
+}
+
+// rLock doesn't need to do anything because traceStep instances are immutable.
+func (s traceStep) rLock()   {}
+func (s traceStep) rUnlock() {}
+
+func (s traceStep) time() time.Time {
+	return s.stepTime
+}
+
+func (s traceStep) writeItem(b *bytes.Buffer, formatter string, startTime time.Time, stepThreshold *time.Duration) {
+	stepDuration := s.stepTime.Sub(startTime)
+	if stepThreshold == nil || *stepThreshold == 0 || stepDuration >= *stepThreshold || klogV(4) {
+		b.WriteString(fmt.Sprintf("%s---", formatter))
+		writeTraceItemSummary(b, s.msg, stepDuration, s.stepTime, s.fields)
+	}
+}
+
+// Trace keeps track of a set of "steps" and allows us to log a specific
+// step if it took longer than its share of the total allowed time
+type Trace struct {
+	// constant fields
+	name        string
+	fields      []Field
+	startTime   time.Time
+	parentTrace *Trace
+	// fields guarded by a lock
+	lock       sync.RWMutex
+	threshold  *time.Duration
+	endTime    *time.Time
+	traceItems []traceItem
+}
+
+func (t *Trace) rLock() {
+	t.lock.RLock()
+}
+
+func (t *Trace) rUnlock() {
+	t.lock.RUnlock()
+}
+
+func (t *Trace) time() time.Time {
+	if t.endTime != nil {
+		return *t.endTime
+	}
+	return t.startTime // if the trace is incomplete, don't assume an end time
+}
+
+func (t *Trace) writeItem(b *bytes.Buffer, formatter string, startTime time.Time, stepThreshold *time.Duration) {
+	if t.durationIsWithinThreshold() || klogV(4) {
+		b.WriteString(fmt.Sprintf("%v[", formatter))
+		writeTraceItemSummary(b, t.name, t.TotalTime(), t.startTime, t.fields)
+		if st := t.calculateStepThreshold(); st != nil {
+			stepThreshold = st
+		}
+		t.writeTraceSteps(b, formatter+" ", stepThreshold)
+		b.WriteString("]")
+		return
+	}
+	// If the trace should not be written, still check for nested traces that should be written
+	for _, s := range t.traceItems {
+		if nestedTrace, ok := s.(*Trace); ok {
+			nestedTrace.writeItem(b, formatter, startTime, stepThreshold)
+		}
+	}
+}
+
+// New creates a Trace with the specified name. The name identifies the operation to be traced. The
+// Fields add key value pairs to provide additional details about the trace, such as operation inputs.
+func New(name string, fields ...Field) *Trace {
+	return &Trace{name: name, startTime: time.Now(), fields: fields}
+}
+
+// Step adds a new step with a specific message. Call this at the end of an execution step to record
+// how long it took. The Fields add key value pairs to provide additional details about the trace
+// step.
+func (t *Trace) Step(msg string, fields ...Field) {
+	t.lock.Lock()
+	defer t.lock.Unlock()
+	if t.traceItems == nil {
+		// traces almost always have less than 6 steps, do this to avoid more than a single allocation
+		t.traceItems = make([]traceItem, 0, 6)
+	}
+	t.traceItems = append(t.traceItems, traceStep{stepTime: time.Now(), msg: msg, fields: fields})
+}
+
+// Nest adds a nested trace with the given message and fields and returns it.
+// As a convenience, if the receiver is nil, returns a top level trace. This allows
+// one to call FromContext(ctx).Nest without having to check if the trace
+// in the context is nil.
+func (t *Trace) Nest(msg string, fields ...Field) *Trace {
+	newTrace := New(msg, fields...)
+	if t != nil {
+		newTrace.parentTrace = t
+		t.lock.Lock()
+		t.traceItems = append(t.traceItems, newTrace)
+		t.lock.Unlock()
+	}
+	return newTrace
+}
+
+// Log is used to dump all the steps in the Trace. It also logs the nested trace messages using indentation.
+// If the Trace is nested it is not immediately logged. Instead, it is logged when the trace it is nested within
+// is logged.
+func (t *Trace) Log() {
+	endTime := time.Now()
+	t.lock.Lock()
+	t.endTime = &endTime
+	t.lock.Unlock()
+	// an explicit logging request should dump all the steps out at the higher level
+	if t.parentTrace == nil && klogV(2) { // We don't start logging until Log or LogIfLong is called on the root trace
+		t.logTrace()
+	}
+}
+
+// LogIfLong only logs the trace if the duration of the trace exceeds the threshold.
+// Only steps that took longer than their share or the given threshold are logged.
+// If klog is at verbosity level 4 or higher and the trace took longer than the threshold,
+// all substeps and subtraces are logged. Otherwise, only those which took longer than
+// their own threshold.
+// If the Trace is nested it is not immediately logged. Instead, it is logged when the trace it
+// is nested within is logged.
+func (t *Trace) LogIfLong(threshold time.Duration) {
+	t.lock.Lock()
+	t.threshold = &threshold
+	t.lock.Unlock()
+	t.Log()
+}
+
+// logTopLevelTraces finds all traces in a hierarchy of nested traces that should be logged but do not have any
+// parents that will be logged, due to threshold limits, and logs them as top level traces.
+func (t *Trace) logTrace() {
+	t.lock.RLock()
+	defer t.lock.RUnlock()
+	if t.durationIsWithinThreshold() {
+		var buffer bytes.Buffer
+		traceNum := rand.Int31()
+
+		totalTime := t.endTime.Sub(t.startTime)
+		buffer.WriteString(fmt.Sprintf("Trace[%d]: %q ", traceNum, t.name))
+		if len(t.fields) > 0 {
+			writeFields(&buffer, t.fields)
+			buffer.WriteString(" ")
+		}
+
+		// if any step took more than it's share of the total allowed time, it deserves a higher log level
+		buffer.WriteString(fmt.Sprintf("(%v) (total time: %vms):", t.startTime.Format("02-Jan-2006 15:04:05.000"), totalTime.Milliseconds()))
+		stepThreshold := t.calculateStepThreshold()
+		t.writeTraceSteps(&buffer, fmt.Sprintf("\nTrace[%d]: ", traceNum), stepThreshold)
+		buffer.WriteString(fmt.Sprintf("\nTrace[%d]: [%v] [%v] END\n", traceNum, t.endTime.Sub(t.startTime), totalTime))
+
+		klog.Info(buffer.String())
+		return
+	}
+
+	// If the trace should not be logged, still check if nested traces should be logged
+	for _, s := range t.traceItems {
+		if nestedTrace, ok := s.(*Trace); ok {
+			nestedTrace.logTrace()
+		}
+	}
+}
+
+func (t *Trace) writeTraceSteps(b *bytes.Buffer, formatter string, stepThreshold *time.Duration) {
+	lastStepTime := t.startTime
+	for _, stepOrTrace := range t.traceItems {
+		stepOrTrace.rLock()
+		stepOrTrace.writeItem(b, formatter, lastStepTime, stepThreshold)
+		lastStepTime = stepOrTrace.time()
+		stepOrTrace.rUnlock()
+	}
+}
+
+func (t *Trace) durationIsWithinThreshold() bool {
+	if t.endTime == nil { // we don't assume incomplete traces meet the threshold
+		return false
+	}
+	return t.threshold == nil || *t.threshold == 0 || t.endTime.Sub(t.startTime) >= *t.threshold
+}
+
+// TotalTime can be used to figure out how long it took since the Trace was created
+func (t *Trace) TotalTime() time.Duration {
+	return time.Since(t.startTime)
+}
+
+// calculateStepThreshold returns a threshold for the individual steps of a trace, or nil if there is no threshold and
+// all steps should be written.
+func (t *Trace) calculateStepThreshold() *time.Duration {
+	if t.threshold == nil {
+		return nil
+	}
+	lenTrace := len(t.traceItems) + 1
+	traceThreshold := *t.threshold
+	for _, s := range t.traceItems {
+		nestedTrace, ok := s.(*Trace)
+		if ok {
+			nestedTrace.lock.RLock()
+			if nestedTrace.threshold != nil {
+				traceThreshold = traceThreshold - *nestedTrace.threshold
+				lenTrace--
+			}
+			nestedTrace.lock.RUnlock()
+		}
+	}
+
+	// the limit threshold is used when the threshold(
+	//remaining after subtracting that of the child trace) is getting very close to zero to prevent unnecessary logging
+	limitThreshold := *t.threshold / 4
+	if traceThreshold < limitThreshold {
+		traceThreshold = limitThreshold
+		lenTrace = len(t.traceItems) + 1
+	}
+
+	stepThreshold := traceThreshold / time.Duration(lenTrace)
+	return &stepThreshold
+}
+
+// ContextTraceKey provides a common key for traces in context.Context values.
+type ContextTraceKey struct{}
+
+// FromContext returns the trace keyed by ContextTraceKey in the context values, if one
+// is present, or nil If there is no trace in the Context.
+// It is safe to call Nest() on the returned value even if it is nil because ((*Trace)nil).Nest returns a top level
+// trace.
+func FromContext(ctx context.Context) *Trace {
+	if v, ok := ctx.Value(ContextTraceKey{}).(*Trace); ok {
+		return v
+	}
+	return nil
+}
+
+// ContextWithTrace returns a context with trace included in the context values, keyed by ContextTraceKey.
+func ContextWithTrace(ctx context.Context, trace *Trace) context.Context {
+	return context.WithValue(ctx, ContextTraceKey{}, trace)
+}