trace: Logger helper (#36139)

I don't see many uses of log.WithTrace, but I think this is because it
is clunky to use since Span or Context may be nil on a context. This
introduces a helper so we can start logging against a span more easily.
Here is an example of using it I want:

  logger := trace.Logger(ctx, s.Log).Scoped("...", "...").With(...

This seems like the best place to add the logger, since we need to use
internal functions in the trace pkg (ie won't work in lib/log).

I updated the documentation to include an example of it. Right now the
documentation has one other place it calls WithTrace, but it needs to be
reworked to be more realistic. I think calling log.Scoped on something
that is traced seems surprising to me.

Test Plan: unused, so just that CI is happy.

Co-authored-by: Robert Lin <robert@bobheadxi.dev>

doc/dev/how-to/add_logging.md

@@ -107,8 +107,8 @@ func (w *Worker) DoSomething(params ...int) {
 If you are kicking off a long-running process, you can spawn a child logger and use it directly to maintain relevant context:
 
 ```go
-func (w *Worker) DoBigThing(params ...int) {
-  doLog := w.logger.WithTrace(/* ... */).With("params", params)
+func (w *Worker) DoBigThing(ctx context.Context, params ...int) {
+  doLog := trace.Logger(ctx, w.logger).With("params", params)
 
   // subsequent entries will have trace and params attached
   doLog.Info("starting the big thing")

internal/trace/traceutil.go

@@ -19,6 +19,7 @@ import (
 	"github.com/sourcegraph/sourcegraph/internal/trace/ot"
 	"github.com/sourcegraph/sourcegraph/internal/tracer"
 	"github.com/sourcegraph/sourcegraph/lib/errors"
+	sglog "github.com/sourcegraph/sourcegraph/lib/log"
 	"github.com/sourcegraph/sourcegraph/lib/log/otfields"
 )
 
@@ -73,6 +74,15 @@ func ContextFromSpan(span opentracing.Span) *otfields.TraceContext {
 	return nil
 }
 
+// Logger will set the TraceContext on l if ctx has one. This is a
+// convenience function around l.WithTrace for the common case.
+func Logger(ctx context.Context, l sglog.Logger) sglog.Logger {
+	if tc := Context(ctx); tc != nil {
+		return l.WithTrace(*tc)
+	}
+	return l
+}
+
 // URL returns a trace URL for the given trace ID at the given external URL.
 func URL(traceID, externalURL, traceProvider string) string {
 	if traceID == "" {