tracing: improve comment on otSpan

Release note: None

pkg/util/log/BUILD.bazel

@@ -145,6 +145,7 @@ go_test(
         "//vendor/github.com/kr/pretty",
         "//vendor/github.com/pmezard/go-difflib/difflib",
         "//vendor/github.com/stretchr/testify/assert",
+        "//vendor/github.com/stretchr/testify/require",
         "//vendor/golang.org/x/net/trace",
     ] + select({
         "@io_bazel_rules_go//go/platform:aix": [

pkg/util/tracing/BUILD.bazel

@@ -6,6 +6,7 @@ go_library(
         "annotate.go",
         "annotate_nocgo.go",
         "grpc_interceptor.go",
+        "recording.go",
         "shadow.go",
         "span.go",
         "tags.go",

pkg/util/tracing/span.go

@@ -145,10 +145,15 @@ func (s *crdbSpan) isRecording() bool {
 	return s != nil && atomic.LoadInt32(&s.recording) != 0
 }
 
+// otSpan is an span for an external opentracing compatible tracer
+// such as lightstep, zipkin, jaeger, etc.
 type otSpan struct {
-	// TODO(tbg): see if we can lose the shadowTr here and rely on shadowSpan.Tracer().
-	// Probably not - but worth checking.
-	// TODO(tbg): consider renaming 'shadow' -> 'ot' or 'external'.
+	// shadowTr is the shadowTracer this span was created from. We need
+	// to hold on to it separately because shadowSpan.Tracer() returns
+	// the wrapper tracer directly and we lose the ability to find out
+	// what tracer it is. This is important when deriving children from
+	// this span, as we want to avoid mixing different tracers, which
+	// would otherwise be the result of cluster settings changed.
 	shadowTr   *shadowTracer
 	shadowSpan opentracing.Span
 }