log,*: require explicit channel selection for logging API

kyle-a-wong · kyle-a-wong · commit 65d6d9c65852 · 2025-08-27T14:52:00.000-05:00
Updated the deprecation comment on the generated logging APIS to adhere to the golang documentation. As a result, usage of these APIs will now cause lint failures due to lint check: SA1019. Epic: CRDB-53410 Release note: None
diff --git a/pkg/acceptance/cluster/docker.go b/pkg/acceptance/cluster/docker.go
@@ -317,10 +317,10 @@ func (c *Container) WaitUntilNotRunning(ctx context.Context) error {
 			// NB: TEST_UNDECLARED_OUTPUTS_DIR is set for remote Bazel tests.
 			undeclaredOutsDir := os.Getenv("TEST_UNDECLARED_OUTPUTS_DIR")
 			if undeclaredOutsDir != "" {
-				log.Shoutf(ctx, severity.INFO, "command left-over files in %s",
+				log.Dev.Shoutf(ctx, severity.INFO, "command left-over files in %s",
 					strings.Replace(volumesDir, undeclaredOutsDir, "outputs.zip", 1))
 			} else {
-				log.Shoutf(ctx, severity.INFO, "command left-over files in %s", volumesDir)
+				log.Dev.Shoutf(ctx, severity.INFO, "command left-over files in %s", volumesDir)
 			}
 		}
 
diff --git a/pkg/backup/restore_job.go b/pkg/backup/restore_job.go
@@ -259,7 +259,7 @@ func restoreWithRetry(
 					ctx, txn, "error", fmt.Sprintf("restore encountered error: %v", err),
 				)
 			}); err != nil {
-				log.Warningf(ctx, "failed to record job error message: %v", err)
+				log.Dev.Warningf(ctx, "failed to record job error message: %v", err)
 			}
 		}
 
@@ -330,7 +330,7 @@ func maybeResetRetry(
 		// If the previous persisted spans are different than the current, it
 		// implies that further progress has been persisted.
 		rt.Reset()
-		log.Infof(ctx, "restored frontier has advanced since last retry, resetting retry counter")
+		log.Dev.Infof(ctx, "restored frontier has advanced since last retry, resetting retry counter")
 	}
 	return currProgress
 }
diff --git a/pkg/ccl/changefeedccl/schemafeed/table_event_filter.go b/pkg/ccl/changefeedccl/schemafeed/table_event_filter.go
@@ -128,9 +128,9 @@ func (filter tableEventFilter) shouldFilter(
 	et := classifyTableEvent(e)
 
 	if log.V(2) {
-		log.Infof(ctx, "table event %v classified as %v", e, et)
+		log.Dev.Infof(ctx, "table event %v classified as %v", e, et)
 		defer func() {
-			log.Infof(ctx, "should filter table event %v: %t", e, ok)
+			log.Dev.Infof(ctx, "should filter table event %v: %t", e, ok)
 		}()
 	}
 
diff --git a/pkg/cli/cli.go b/pkg/cli/cli.go
@@ -356,7 +356,7 @@ func debugSignalSetup() func() {
 				case <-exit:
 					return
 				case <-debugSignalCh:
-					log.Shout(ctx, severity.INFO, "setting up localhost debugging endpoint...")
+					log.Dev.Shout(ctx, severity.INFO, "setting up localhost debugging endpoint...")
 					mux := http.NewServeMux()
 					mux.HandleFunc("/debug/pprof/", pprof.Index)
 					mux.HandleFunc("/debug/pprof/cmdline", pprof.Cmdline)
@@ -367,7 +367,7 @@ func debugSignalSetup() func() {
 					listenAddr := "localhost:0"
 					listener, err := net.Listen("tcp", listenAddr)
 					if err != nil {
-						log.Shoutf(ctx, severity.WARNING, "debug server could not start listening on %s: %v", listenAddr, err)
+						log.Dev.Shoutf(ctx, severity.WARNING, "debug server could not start listening on %s: %v", listenAddr, err)
 						continue
 					}
 
@@ -377,7 +377,7 @@ func debugSignalSetup() func() {
 							log.Dev.Warningf(ctx, "debug server: %v", err)
 						}
 					}()
-					log.Shoutf(ctx, severity.INFO, "debug server listening on %s", listener.Addr())
+					log.Dev.Shoutf(ctx, severity.INFO, "debug server listening on %s", listener.Addr())
 					<-exit
 					if err := server.Shutdown(ctx); err != nil {
 						log.Dev.Warningf(ctx, "error shutting down debug server: %s", err)
diff --git a/pkg/cli/start.go b/pkg/cli/start.go
@@ -1472,7 +1472,7 @@ func setupAndInitializeLoggingAndProfiling(
 				"to databases, the --locality flag must contain a \"region\" tier.\n" +
 				"For more information, see:\n\n" +
 				"- %s"
-			log.Shoutf(ctx, severity.WARNING, warningString,
+			log.Dev.Shoutf(ctx, severity.WARNING, warningString,
 				redact.Safe(docs.URL("cockroach-start.html#locality")))
 		}
 	}
diff --git a/pkg/crosscluster/logical/logical_replication_job.go b/pkg/crosscluster/logical/logical_replication_job.go
@@ -348,7 +348,7 @@ func (r *logicalReplicationResumer) ingest(
 			case <-t.C:
 				newDest, err := reloadDest(ctx, ingestionJob.ID(), jobExecCtx.ExecCfg())
 				if err != nil {
-					log.Warningf(ctx, "failed to check for updated configuration: %v", err)
+					log.Dev.Warningf(ctx, "failed to check for updated configuration: %v", err)
 				} else if newDest != resolvedDest {
 					return errors.Mark(errors.Newf("replan due to detail change: old=%s, new=%s", resolvedDest, newDest), sql.ErrPlanChanged)
 				}
diff --git a/pkg/kv/kvclient/rangefeed/rangefeedcache/watcher.go b/pkg/kv/kvclient/rangefeed/rangefeedcache/watcher.go
@@ -312,7 +312,7 @@ func (s *Watcher[E]) Run(ctx context.Context) error {
 		rangefeed.WithDiff(s.withPrevValue),
 		rangefeed.WithRowTimestampInInitialScan(s.withRowTSInInitialScan),
 		rangefeed.WithOnInitialScanError(func(ctx context.Context, err error) (shouldFail bool) {
-			log.VInfof(ctx, 1, "initial scan error: %s", err)
+			log.Dev.VInfof(ctx, 1, "initial scan error: %s", err)
 			// TODO(irfansharif): Consider if there are other errors which we
 			// want to treat as permanent. This was cargo culted from the
 			// settings watcher.
diff --git a/pkg/kv/kvserver/allocator/allocatorimpl/allocator.go b/pkg/kv/kvserver/allocator/allocatorimpl/allocator.go
@@ -966,9 +966,9 @@ func (a *Allocator) ComputeAction(
 	// priority inversion. If the priority is not -1, the range might be re-queued
 	// to be processed with the correct priority.
 	if priority == -1 && buildutil.CrdbTestBuild {
-		log.Fatalf(ctx, "allocator returned -1 priority for range %s: %v", desc, action)
+		log.Dev.Fatalf(ctx, "allocator returned -1 priority for range %s: %v", desc, action)
 	} else {
-		log.Warningf(ctx, "allocator returned -1 priority for range %s: %v", desc, action)
+		log.Dev.Warningf(ctx, "allocator returned -1 priority for range %s: %v", desc, action)
 	}
 	return action, priority
 }
diff --git a/pkg/kv/kvserver/batcheval/cmd_add_sstable.go b/pkg/kv/kvserver/batcheval/cmd_add_sstable.go
@@ -475,7 +475,7 @@ func computeSSTStatsDiffWithFallback(
 	stats, err := storage.ComputeSSTStatsDiff(
 		ctx, sst, readWriter, nowNanos, start, end)
 	if errors.IsAny(err, storage.ComputeSSTStatsDiffReaderHasRangeKeys, storage.ComputeStatsDiffViolation) {
-		log.Warningf(ctx, "computing SST stats as estimates because of ComputeSSTStatsDiff error: %s", err)
+		log.Dev.Warningf(ctx, "computing SST stats as estimates because of ComputeSSTStatsDiff error: %s", err)
 		sstStats, err := computeSSTStats(ctx, sst, nowNanos)
 		if err != nil {
 			return enginepb.MVCCStats{}, errors.Wrap(err, "error computing SST stats during fallback")
diff --git a/pkg/server/import_ts.go b/pkg/server/import_ts.go
@@ -128,15 +128,15 @@ func maybeImportTS(ctx context.Context, s *topLevelServer) (returnErr error) {
 			}
 			storeToNode[roachpb.StoreID(si)] = roachpb.NodeID(ni)
 		}
-		log.Infof(ctx, "Using embedded store-to-node mapping from the tsdump file itself. "+
+		log.Dev.Infof(ctx, "Using embedded store-to-node mapping from the tsdump file itself. "+
 			"Skipped check for explicit store-to-node mapping file.")
 	} else {
 		// Reset file to beginning for subsequent decoding.
 		if _, err := f.Seek(0, io.SeekStart); err != nil {
 			return err
 		}
 		dec = gob.NewDecoder(f)
-		log.Infof(ctx, "Embedded metadata not found in the tsdump file. "+
+		log.Dev.Infof(ctx, "Embedded metadata not found in the tsdump file. "+
 			"Reading from the store-to-node mapping file.")
 
 		// Fallback to explicit YAML mapping file.
diff --git a/pkg/server/settingswatcher/settings_watcher.go b/pkg/server/settingswatcher/settings_watcher.go
@@ -185,7 +185,7 @@ func (s *SettingsWatcher) Start(ctx context.Context) error {
 		defer s.mu.Unlock()
 		s.mu.updater.ResetRemaining(ctx)
 		if !initialScan.done {
-			log.VInfof(ctx, 1, "initial settings scan complete")
+			log.Dev.VInfof(ctx, 1, "initial settings scan complete")
 			initialScan.done = true
 			close(initialScan.ch)
 		}
diff --git a/pkg/sql/catalog/lease/lease.go b/pkg/sql/catalog/lease/lease.go
@@ -617,9 +617,9 @@ func (m *Manager) WaitForNewVersion(
 
 				if regionStaleSessionCount != 0 { // quit early
 					if region == "" {
-						log.Infof(ctx, "%d sessions holding stale descriptor", regionStaleSessionCount)
+						log.Dev.Infof(ctx, "%d sessions holding stale descriptor", regionStaleSessionCount)
 					} else {
-						log.Infof(ctx, "Region '%s' has %d sessions holding stale descriptor", region, regionStaleSessionCount)
+						log.Dev.Infof(ctx, "Region '%s' has %d sessions holding stale descriptor", region, regionStaleSessionCount)
 					}
 					break
 				}
@@ -1211,13 +1211,13 @@ func (m *Manager) purgeOldVersions(
 		// Otherwise, we ran into some type of transient issue, where the sqllivness
 		// session was expired. This could happen if the sqlliveness range is slow
 		// for some reason.
-		log.Infof(ctx, "unable to acquire lease on latest descriptor "+
+		log.Dev.Infof(ctx, "unable to acquire lease on latest descriptor "+
 			"version of ID: %d, retrying...", id)
 	}
 	// As a last resort, we will release all versions of the descriptor. This is
 	// suboptimal, but the safest option.
 	if errors.Is(err, errRenewLease) {
-		log.Warningf(ctx, "unable to acquire lease on latest descriptor "+
+		log.Dev.Warningf(ctx, "unable to acquire lease on latest descriptor "+
 			"version of ID: %d, cleaning up all versions from storage.", id)
 		err = nil
 	}
diff --git a/pkg/sql/index_split_scatter.go b/pkg/sql/index_split_scatter.go
@@ -189,7 +189,7 @@ func (is *indexSplitAndScatter) getSplitPointsWithStats(
 	// we generated any split points above
 	if len(splitPoints) > 0 {
 		splitPoints = append(splitPoints, is.codec.IndexPrefix(uint32(table.GetID()), uint32(indexToBackfill.GetID())))
-		log.Infof(ctx, "generated %d split points from statistics for tableId=%d index=%d", len(splitPoints), table.GetID(), indexToBackfill.GetID())
+		log.Dev.Infof(ctx, "generated %d split points from statistics for tableId=%d index=%d", len(splitPoints), table.GetID(), indexToBackfill.GetID())
 	}
 	return splitPoints, nil
 }
@@ -272,7 +272,7 @@ func (is *indexSplitAndScatter) MaybeSplitIndexSpans(
 	if len(splitPoints) == 0 {
 		splitPoints, err = is.getSplitPointsWithStats(ctx, table, indexToBackfill, nSplits)
 		if err != nil {
-			log.Warningf(ctx, "unable to get split points for stats for tableID=%d index=%d due to %v", tableID, indexToBackfill.GetID(), err)
+			log.Dev.Warningf(ctx, "unable to get split points for stats for tableID=%d index=%d due to %v", tableID, indexToBackfill.GetID(), err)
 		}
 	}
 
diff --git a/pkg/util/log/gen/main.go b/pkg/util/log/gen/main.go
@@ -353,11 +353,7 @@ func (logger{{.Name}}) {{with $sev}}{{.Name}}{{end}}fDepth(ctx context.Context,
 //
 {{with $sev}}{{.Comment}}{{end -}}
 //
-// TODO: to avoid linting failures, we don't include details about
-// alternative usage. Once all usages have been replaced, update the
-// deprecation comment to describe the replacement functions
-//
-// Deprecated
+// Deprecated: use log.Dev.{{with $sev}}{{.Name}}{{end}}f instead
 func {{with $sev}}{{.Name}}{{end}}f(ctx context.Context, format string, args ...interface{}) {
   logfDepth(ctx, 1, severity.{{with $sev}}{{.NAME}}{{end}}, channel.{{.NAME}}, format, args...)
 }
@@ -370,11 +366,7 @@ func {{with $sev}}{{.Name}}{{end}}f(ctx context.Context, format string, args ...
 //
 {{with $sev}}{{.Comment}}{{end -}}
 //
-// TODO: to avoid linting failures, we don't include details about
-// alternative usage. Once all usages have been replaced, update the
-// deprecation comment to describe the replacement functions
-//
-// Deprecated
+// Deprecated: use log.Dev.V{{with $sev}}{{.Name}}{{end}}f instead
 func V{{with $sev}}{{.Name}}{{end}}f(ctx context.Context, level Level, format string, args ...interface{}) {
   if VDepth(level, 1) {
     logfDepth(ctx, 1, severity.{{with $sev}}{{.NAME}}{{end}}, channel.{{.NAME}}, format, args...)
@@ -389,11 +381,7 @@ func V{{with $sev}}{{.Name}}{{end}}f(ctx context.Context, level Level, format st
 //
 {{with $sev}}{{.Comment}}{{end -}}
 //
-// TODO: to avoid linting failures, we don't include details about
-// alternative usage. Once all usages have been replaced, update the
-// deprecation comment to describe the replacement functions
-//
-// Deprecated
+// Deprecated: use log.Dev.{{with $sev}}{{.Name}}{{end}} instead
 func {{with $sev}}{{.Name}}{{end}}(ctx context.Context, msg string) {
   logfDepth(ctx, 1, severity.{{with $sev}}{{.NAME}}{{end}}, channel.{{.NAME}}, msg)
 }
@@ -407,11 +395,7 @@ func {{with $sev}}{{.Name}}{{end}}(ctx context.Context, msg string) {
 //
 {{with $sev}}{{.Comment}}{{end -}}
 //
-// TODO: to avoid linting failures, we don't include details about
-// alternative usage. Once all usages have been replaced, update the
-// deprecation comment to describe the replacement functions
-//
-// Deprecated
+// Deprecated: use log.Dev.{{with $sev}}{{.Name}}{{end}}fDepth instead
 func {{with $sev}}{{.Name}}{{end}}fDepth(ctx context.Context, depth int, format string, args ...interface{}) {
   logfDepth(ctx, depth+1, severity.{{with $sev}}{{.NAME}}{{end}}, channel.{{.NAME}}, format, args...)
 }
@@ -466,11 +450,7 @@ func (logger{{.Name}}) VEventfDepth(ctx context.Context, depth int, level Level,
 //
 {{.Comment -}}
 //
-// TODO: to avoid linting failures, we don't include details about
-// alternative usage. Once all usages have been replaced, update the
-// deprecation comment to describe the replacement functions
-//
-// Deprecated
+// Deprecated: use log.Dev.Shout instead
 func Shout(ctx context.Context, sev Severity, msg string) {
   shoutfDepth(ctx, 1, sev, channel.{{.NAME}}, msg)
 }
@@ -481,11 +461,7 @@ func Shout(ctx context.Context, sev Severity, msg string) {
 //
 {{.Comment -}}
 //
-// TODO: to avoid linting failures, we don't include details about
-// alternative usage. Once all usages have been replaced, update the
-// deprecation comment to describe the replacement functions
-//
-// Deprecated
+// Deprecated: use log.Dev.Shoutf instead
 func Shoutf(ctx context.Context, sev Severity, format string, args ...interface{}) {
   shoutfDepth(ctx, 1, sev, channel.{{.NAME}}, format, args...)
 }
diff --git a/pkg/util/log/log_channels_generated.go b/pkg/util/log/log_channels_generated.go
diff --git a/pkg/util/log/logcrash/crash_reporting.go b/pkg/util/log/logcrash/crash_reporting.go
diff --git a/pkg/util/log/testshout/shout_test.go b/pkg/util/log/testshout/shout_test.go

Original file line number	Diff line number	Diff line change
`@@ -317,10 +317,10 @@ func (c *Container) WaitUntilNotRunning(ctx context.Context) error {`
`317`	`317`	`// NB: TEST_UNDECLARED_OUTPUTS_DIR is set for remote Bazel tests.`
`318`	`318`	`undeclaredOutsDir := os.Getenv("TEST_UNDECLARED_OUTPUTS_DIR")`
`319`	`319`	`if undeclaredOutsDir != "" {`
`320`		`- log.Shoutf(ctx, severity.INFO, "command left-over files in %s",`
	`320`	`+ log.Dev.Shoutf(ctx, severity.INFO, "command left-over files in %s",`
`321`	`321`	`strings.Replace(volumesDir, undeclaredOutsDir, "outputs.zip", 1))`
`322`	`322`	`} else {`
`323`		`- log.Shoutf(ctx, severity.INFO, "command left-over files in %s", volumesDir)`
	`323`	`+ log.Dev.Shoutf(ctx, severity.INFO, "command left-over files in %s", volumesDir)`
`324`	`324`	`}`
`325`	`325`	`}`
`326`	`326`
Original file line number	Diff line number	Diff line change
`@@ -259,7 +259,7 @@ func restoreWithRetry(`
`259`	`259`	`ctx, txn, "error", fmt.Sprintf("restore encountered error: %v", err),`
`260`	`260`	`)`
`261`	`261`	`}); err != nil {`
`262`		`- log.Warningf(ctx, "failed to record job error message: %v", err)`
	`262`	`+ log.Dev.Warningf(ctx, "failed to record job error message: %v", err)`
`263`	`263`	`}`
`264`	`264`	`}`
`265`	`265`
`@@ -330,7 +330,7 @@ func maybeResetRetry(`
`330`	`330`	`// If the previous persisted spans are different than the current, it`
`331`	`331`	`// implies that further progress has been persisted.`
`332`	`332`	`rt.Reset()`
`333`		`- log.Infof(ctx, "restored frontier has advanced since last retry, resetting retry counter")`
	`333`	`+ log.Dev.Infof(ctx, "restored frontier has advanced since last retry, resetting retry counter")`
`334`	`334`	`}`
`335`	`335`	`return currProgress`
`336`	`336`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1472,7 +1472,7 @@ func setupAndInitializeLoggingAndProfiling(`
`1472`	`1472`	`"to databases, the --locality flag must contain a \"region\" tier.\n" +`
`1473`	`1473`	`"For more information, see:\n\n" +`
`1474`	`1474`	`"- %s"`
`1475`		`- log.Shoutf(ctx, severity.WARNING, warningString,`
	`1475`	`+ log.Dev.Shoutf(ctx, severity.WARNING, warningString,`
`1476`	`1476`	`redact.Safe(docs.URL("cockroach-start.html#locality")))`
`1477`	`1477`	`}`
`1478`	`1478`	`}`
Original file line number	Diff line number	Diff line change
`@@ -348,7 +348,7 @@ func (r *logicalReplicationResumer) ingest(`
`348`	`348`	`case <-t.C:`
`349`	`349`	`newDest, err := reloadDest(ctx, ingestionJob.ID(), jobExecCtx.ExecCfg())`
`350`	`350`	`if err != nil {`
`351`		`- log.Warningf(ctx, "failed to check for updated configuration: %v", err)`
	`351`	`+ log.Dev.Warningf(ctx, "failed to check for updated configuration: %v", err)`
`352`	`352`	`} else if newDest != resolvedDest {`
`353`	`353`	`return errors.Mark(errors.Newf("replan due to detail change: old=%s, new=%s", resolvedDest, newDest), sql.ErrPlanChanged)`
`354`	`354`	`}`
Original file line number	Diff line number	Diff line change
`@@ -966,9 +966,9 @@ func (a *Allocator) ComputeAction(`
`966`	`966`	`// priority inversion. If the priority is not -1, the range might be re-queued`
`967`	`967`	`// to be processed with the correct priority.`
`968`	`968`	`if priority == -1 && buildutil.CrdbTestBuild {`
`969`		`- log.Fatalf(ctx, "allocator returned -1 priority for range %s: %v", desc, action)`
	`969`	`+ log.Dev.Fatalf(ctx, "allocator returned -1 priority for range %s: %v", desc, action)`
`970`	`970`	`} else {`
`971`		`- log.Warningf(ctx, "allocator returned -1 priority for range %s: %v", desc, action)`
	`971`	`+ log.Dev.Warningf(ctx, "allocator returned -1 priority for range %s: %v", desc, action)`
`972`	`972`	`}`
`973`	`973`	`return action, priority`
`974`	`974`	`}`
Original file line number	Diff line number	Diff line change
`@@ -128,15 +128,15 @@ func maybeImportTS(ctx context.Context, s *topLevelServer) (returnErr error) {`
`128`	`128`	`}`
`129`	`129`	`storeToNode[roachpb.StoreID(si)] = roachpb.NodeID(ni)`
`130`	`130`	`}`
`131`		`- log.Infof(ctx, "Using embedded store-to-node mapping from the tsdump file itself. "+`
	`131`	`+ log.Dev.Infof(ctx, "Using embedded store-to-node mapping from the tsdump file itself. "+`
`132`	`132`	`"Skipped check for explicit store-to-node mapping file.")`
`133`	`133`	`} else {`
`134`	`134`	`// Reset file to beginning for subsequent decoding.`
`135`	`135`	`if _, err := f.Seek(0, io.SeekStart); err != nil {`
`136`	`136`	`return err`
`137`	`137`	`}`
`138`	`138`	`dec = gob.NewDecoder(f)`
`139`		`- log.Infof(ctx, "Embedded metadata not found in the tsdump file. "+`
	`139`	`+ log.Dev.Infof(ctx, "Embedded metadata not found in the tsdump file. "+`
`140`	`140`	`"Reading from the store-to-node mapping file.")`
`141`	`141`
`142`	`142`	`// Fallback to explicit YAML mapping file.`