[chore] Update log.AddSink docs to clarify confusing behavior

pkg/log/log.go

@@ -137,7 +137,10 @@ func AddSentry(l logr.Logger, opts sentry.ClientOptions, tags map[string]string)
 }
 
 // AddSink extends an existing logr.Logger with a new sink. It returns the new
-// logr.Logger, a cleanup function, and an error.
+// logr.Logger, a cleanup function, and an error. Note that values added to the
+// existing logr.Logger via [logr.WithValues] before calling this function will
+// not be propagated to the new sink, but they will continue to be written to
+// the existing sink.
 func AddSink(l logr.Logger, sink logConfig) (logr.Logger, func() error, error) {
 	if sink.err != nil {
 		return l, nil, sink.err

pkg/log/log_test.go

@@ -163,6 +163,27 @@ func TestAddSink(t *testing.T) {
 	assert.Contains(t, buf2.String(), "line 2")
 }
 
+// TestAddSinkDoesNotPropagateValues is a pinning test to document that the
+// existing functionality of AddSink will not propagate values added to the
+// logger.
+func TestAddSinkDoesNotPropagateValues(t *testing.T) {
+	var buf1, buf2 bytes.Buffer
+	logger, _ := New("service-name",
+		WithConsoleSink(&buf1),
+	)
+	logger = logger.WithValues("foo", "bar")
+	logger.Info("line 1")
+	logger, flush, err := AddSink(logger, WithConsoleSink(&buf2))
+	assert.Nil(t, err)
+	logger.Info("line 2")
+	assert.Nil(t, flush())
+
+	bufLines1 := strings.Split(buf1.String(), "\n")
+	assert.Contains(t, bufLines1[0], "foo")     // line1 contains "foo"
+	assert.Contains(t, bufLines1[1], "foo")     // line2 contains "foo"
+	assert.NotContains(t, buf2.String(), "foo") // "foo" not found anywhere in the added sink
+}
+
 func TestStaticLevelSink(t *testing.T) {
 	var buf1, buf2 bytes.Buffer
 	l1 := zap.NewAtomicLevel()