delint opentracing/...

opentracing/defaulttracer.go

@@ -4,52 +4,59 @@ var (
 	defaultOpenTracer OpenTracer = noopOpenTracer{noopTraceContextSource{}}
 )
 
-// Should be called as early as possible in main(), prior to calling the
-// `StartSpan*` (etc) global funcs below. Prior to calling `InitDefaultTracer`,
-// any Spans started via the `StartSpan*` globals are noops.
+// InitDefaultTracer sets the [singleton] OpenTracer returned by
+// DefaultTracer(). Those who use DefaultTracer (rather than directly manage an
+// OpenTracer instance) should call InitDefaultTracer as early as possible in
+// main(), prior to calling the `StartTrace` (etc) global funcs below. Prior to
+// calling `InitDefaultTracer`, any Spans started via the `StartTrace` (etc)
+// globals are noops.
 func InitDefaultTracer(tracer OpenTracer) {
 	defaultOpenTracer = tracer
 }
 
-// Return the global singleton `OpenTracer` implementation. Before
-// `InitDefaultTracer()` is called, the `DefaultTracer()` is a noop
+// DefaultTracer returns the global singleton `OpenTracer` implementation.
+// Before `InitDefaultTracer()` is called, the `DefaultTracer()` is a noop
 // implementation that drops all data handed to it.
 func DefaultTracer() OpenTracer {
 	return defaultOpenTracer
 }
 
-// Defers to `OpenTracer.StartTrace`. See `DefaultTracer()`.
+// StartTrace defers to `OpenTracer.StartTrace`. See `DefaultTracer()`.
 func StartTrace(operationName string, keyValueTags ...interface{}) Span {
 	return defaultOpenTracer.StartTrace(operationName, keyValueTags...)
 }
 
-// Defers to `OpenTracer.JoinTrace`. See `DefaultTracer()`.
+// JoinTrace defers to `OpenTracer.JoinTrace`. See `DefaultTracer()`.
 func JoinTrace(operationName string, parent interface{}, keyValueTags ...interface{}) Span {
 	return defaultOpenTracer.JoinTrace(operationName, parent, keyValueTags...)
 }
 
-// Defers to `TraceContextMarshaler.MarshalTraceContextBinary`.
+// MarshalTraceContextBinary defers to
+// `TraceContextMarshaler.MarshalTraceContextBinary`.
 //
 // See `DefaultTracer()`.
 func MarshalTraceContextBinary(ctx TraceContext) []byte {
 	return defaultOpenTracer.MarshalTraceContextBinary(ctx)
 }
 
-// Defers to `TraceContextMarshaler.MarshalStringMapTraceContext`.
+// MarshalTraceContextStringMap defers to
+// `TraceContextMarshaler.MarshalTraceContextStringMap`.
 //
 // See `DefaultTracer()`.
 func MarshalTraceContextStringMap(ctx TraceContext) map[string]string {
 	return defaultOpenTracer.MarshalTraceContextStringMap(ctx)
 }
 
-// Defers to `TraceContextUnmarshaler.UnmarshalTraceContextBinary`.
+// UnmarshalTraceContextBinary defers to
+// `TraceContextUnmarshaler.UnmarshalTraceContextBinary`.
 //
 // See `DefaultTracer()`.
 func UnmarshalTraceContextBinary(encoded []byte) (TraceContext, error) {
 	return defaultOpenTracer.UnmarshalTraceContextBinary(encoded)
 }
 
-// Defers to `TraceContextUnmarshaler.UnmarshalStringMapTraceContext`.
+// UnmarshalTraceContextStringMap defers to
+// `TraceContextUnmarshaler.UnmarshaTraceContextStringMap`.
 //
 // See `DefaultTracer()`.
 func UnmarshalTraceContextStringMap(encoded map[string]string) (TraceContext, error) {

opentracing/gocontext.go

@@ -6,18 +6,26 @@ type goContextKey int
 
 const activeSpanKey goContextKey = iota
 
-// Return a new `context.Context` including a reference to the given `Span`.
+// GoContextWithSpan seturns a new `context.Context` that holds a reference to
+// the given `Span`.
+//
+// NOTE: We use the term "GoContext" to minimize confusion with TraceContext.
 func GoContextWithSpan(ctx context.Context, span Span) context.Context {
 	return context.WithValue(ctx, activeSpanKey, span)
 }
 
-// A convenience wrapper around `GoContextWithSpan(context.BackgroundContext(), ...)`.
-func BackgroundContextWithSpan(span Span) context.Context {
+// BackgroundGoContextWithSpan is a convenience wrapper around
+// `GoContextWithSpan(context.BackgroundContext(), ...)`.
+//
+// NOTE: We use the term "GoContext" to minimize confusion with TraceContext.
+func BackgroundGoContextWithSpan(span Span) context.Context {
 	return context.WithValue(context.Background(), activeSpanKey, span)
 }
 
-// Returns the `Span` previously associated with `ctx`, or `nil` if no such
-// `Span` could be found.
+// SpanFromGoContext returns the `Span` previously associated with `ctx`, or
+// `nil` if no such `Span` could be found.
+//
+// NOTE: We use the term "GoContext" to minimize confusion with TraceContext.
 func SpanFromGoContext(ctx context.Context) Span {
 	val := ctx.Value(activeSpanKey)
 	if span, ok := val.(Span); ok {

opentracing/opentracer.go

@@ -1,7 +1,9 @@
 package opentracing
 
-// A simple, thin interface for Span creation. Though other implementations are
-// possible and plausible, most users will be fine with `NewStandardTracer()`.
+// OpenTracer is a simple, thin interface for Span creation.
+//
+// A straightforward implementation is available via the
+// `opentracing/standardtracer` package's `standardtracer.New()'.
 type OpenTracer interface {
 	TraceContextSource
 

opentracing/raw.go

@@ -2,8 +2,13 @@ package opentracing
 
 import "time"
 
+// Tags is a generic map from an arbitrary string key to an opaque value type.
+//
+// TODO: decide on restrictions (if any) for the values: just strings and POD?
+// just simple maps and slices of same? arbitrary objects?
 type Tags map[string]interface{}
 
+// RawSpan encapsulates all state associated with a (finished) Span.
 type RawSpan struct {
 	TraceContext
 
@@ -24,6 +29,7 @@ type RawSpan struct {
 	Logs []*RawLog
 }
 
+// RawLog encapsolutes all state associated with a log element in a Span.
 type RawLog struct {
 	Timestamp time.Time
 
@@ -44,7 +50,8 @@ type RawLog struct {
 	Payload interface{}
 }
 
-// Incorporate the keys and values from `other` into this `Tags` instance.
+// Merge incorporates the keys and values from `other` into this `Tags`
+// instance, then returns same.
 func (t Tags) Merge(other Tags) Tags {
 	for k, v := range other {
 		t[k] = v

opentracing/recorder.go

@@ -1,5 +1,8 @@
 package opentracing
 
+// ProcessIdentifier is a thin interface that guarantees all implementors
+// represent a ProcessName and accepts arbitrary process-level tag assignment
+// (e.g., build numbers, platforms, hostnames, etc).
 type ProcessIdentifier interface {
 	// Every process in the opentracing-instrumented distributed system must
 	// have a name.

opentracing/span.go

@@ -2,6 +2,9 @@ package opentracing
 
 import "golang.org/x/net/context"
 
+// Span represents an active, un-finished span in the opentracing system.
+//
+// Spans are created by the OpenTracer interface and Span.StartChild.
 type Span interface {
 	// Creates and starts a child span.
 	//
@@ -47,5 +50,8 @@ type Span interface {
 	//    var span Span = ...
 	//    goCtx := opentracing.GoContextWithSpan(ctx, span)
 	//
+	//
+	// NOTE: We use the term "GoContext" to minimize confusion with
+	// TraceContext.
 	AddToGoContext(goCtx context.Context) (Span, context.Context)
 }

opentracing/standardtracer/standardimpl.go

@@ -11,11 +11,11 @@ import (
 	"golang.org/x/net/context"
 )
 
-// Creates and returns a standard OpenTracer which defers to `rec` and
-// `ctxIDSource` as appropriate.
-func New(rec opentracing.Recorder, ctxIDSource opentracing.TraceContextSource) opentracing.OpenTracer {
+// New creates and returns a standard OpenTracer which defers to `rec` and
+// `source` as appropriate.
+func New(rec opentracing.Recorder, source opentracing.TraceContextSource) opentracing.OpenTracer {
 	return &standardOpenTracer{
-		TraceContextSource: ctxIDSource,
+		TraceContextSource: source,
 		recorder:           rec,
 	}
 }
@@ -126,14 +126,14 @@ func (s *standardOpenTracer) startSpanWithGoContextParent(
 			childCtx,
 			tags,
 		)
-	} else {
-		tags := keyValueListToTags(keyValueTags)
-		return s.startSpanGeneric(
-			operationName,
-			s.NewRootTraceContext(),
-			tags,
-		)
 	}
+
+	tags := keyValueListToTags(keyValueTags)
+	return s.startSpanGeneric(
+		operationName,
+		s.NewRootTraceContext(),
+		tags,
+	)
 }
 
 func (s *standardOpenTracer) startSpanWithTraceContextParent(
@@ -182,17 +182,17 @@ func keyValueListToTags(keyValueTags []interface{}) opentracing.Tags {
 	}
 	rval := make(opentracing.Tags, len(keyValueTags)/2)
 	var k string
-	for i, kOrV := range keyValueTags {
+	for i, keyOrVal := range keyValueTags {
 		if i%2 == 0 {
 			var ok bool
-			k, ok = kOrV.(string)
+			k, ok = keyOrVal.(string)
 			if !ok {
 				panic(fmt.Errorf(
 					"even-indexed keyValueTags (i.e., the keys) must be strings: got %v",
-					reflect.TypeOf(kOrV)))
+					reflect.TypeOf(keyOrVal)))
 			}
 		} else {
-			rval[k] = kOrV
+			rval[k] = keyOrVal
 		}
 	}
 	return rval

opentracing/tracecontext.go

@@ -1,76 +1,76 @@
 package opentracing
 
-// A `TraceContext` is the smallest amount of state needed to describe a span's
-// identity within a larger [potentially distributed] trace. The `TraceContext`
-// is not intended to encode the span's operation name, timing, or log data,
-// but merely any unique identifiers (etc) needed to contextualize it within a
-// larger trace tree.
+// TraceContext encpasulates the smallest amount of state needed to describe a
+// Span's identity within a larger [potentially distributed] trace. The
+// TraceContext is not intended to encode the span's operation name, timing,
+// or log data, but merely any unique identifiers (etc) needed to contextualize
+// it within a larger trace tree.
 //
-// `TraceContext`s are sufficient to propagate the, well, *context* of a
+// TraceContexts are sufficient to propagate the, well, *context* of a
 // particular trace between processes.
 //
-// `TraceContext` also support a simple string map of "trace tags". These trace
+// TraceContext also support a simple string map of "trace tags". These trace
 // tags are special in that they are propagated *in-band*, presumably alongside
-// application data. See the documentation for `SetTraceTag()` for more details
+// application data. See the documentation for SetTraceTag() for more details
 // and some important caveats.
 type TraceContext interface {
-	// Create a child context for this `TraceContext`, and return both that
-	// child's own `TraceContext` as well as any Tags that should be added to
-	// the child's Span.
+	// NewChild creates a child context for this TraceContext, and returns both
+	// that child's own TraceContext as well as any Tags that should be added
+	// to the child's Span.
 	//
-	// The returned `TraceContext` type must be the same as the type of the
-	// `TraceContext` implementation itself.
+	// The returned TraceContext type must be the same as the type of the
+	// TraceContext implementation itself.
 	NewChild() (childCtx TraceContext, childSpanTags Tags)
 
-	// Set a tag on this `TraceContext` that also propagates to future
-	// `TraceContext` children per `NewChild()`.
+	// SetTraceTag sets a tag on this TraceContext that also propagates to
+	// future TraceContext children per TraceContext.NewChild.
 	//
-	// `SetTraceTag()` enables powerful functionality given a full-stack
+	// SetTraceTag() enables powerful functionality given a full-stack
 	// opentracing integration (e.g., arbitrary application data from a mobile
 	// app can make it, transparently, all the way into the depths of a storage
 	// system), and with it some powerful costs: use this feature with care.
 	//
-	// IMPORTANT NOTE #1: `SetTraceTag()` will only propagate trace tags to
-	// *future* children of the `TraceContext` (see `NewChild()`) and/or the
-	// `Span` that references it.
+	// IMPORTANT NOTE #1: SetTraceTag() will only propagate trace tags to
+	// *future* children of the TraceContext (see NewChild()) and/or the
+	// Span that references it.
 	//
 	// IMPORTANT NOTE #2: Use this thoughtfully and with care. Every key and
 	// value is copied into every local *and remote* child of this
-	// `TraceContext`, and that can add up to a lot of network and cpu
+	// TraceContext, and that can add up to a lot of network and cpu
 	// overhead.
 	//
-	// Returns a reference to this `TraceContext` for chaining, etc.
+	// Returns a reference to this TraceContext for chaining, etc.
 	SetTraceTag(key, value string) TraceContext
 
 	// Gets the value for a trace tag given its key. Returns the empty string
-	// if the value isn't found in this `TraceContext`.
+	// if the value isn't found in this TraceContext.
 	TraceTag(key string) string
 }
 
-// A simple interface to marshal a `TraceContext` to a binary byte array or a
-// string-to-string map.
+// TraceContextMarshaler is a simple interface to marshal a TraceContext to a
+// binary byte array or a string-to-string map.
 type TraceContextMarshaler interface {
-	// Converts the `TraceContext` into marshaled binary data (see
-	// `TraceContextUnmarshaler.UnmarshalTraceContextBinary()`).
+	// Converts the TraceContext into marshaled binary data (see
+	// TraceContextUnmarshaler.UnmarshalTraceContextBinary()).
 	MarshalTraceContextBinary(tcid TraceContext) []byte
-	// Converts the `TraceContext` into a marshaled string:string map (see
-	// `TraceContextUnmarshaler.UnmarshalTraceContextStringMap()`).
+	// Converts the TraceContext into a marshaled string:string map (see
+	// TraceContextUnmarshaler.UnmarshalTraceContextStringMap()).
 	MarshalTraceContextStringMap(tcid TraceContext) map[string]string
 }
 
-// A simple interface to marshal a `TraceContext` to a binary byte array or a
-// string-to-string map.
+// TraceContextUnmarshaler is a simple interface to unmarshal a binary byte
+// array or a string-to-string map into a TraceContext.
 type TraceContextUnmarshaler interface {
 	// Converts the marshaled binary data (see
-	// `TraceContextMarshaler.MarshalTraceContextBinary()`) into a TraceContext.
+	// TraceContextMarshaler.MarshalTraceContextBinary()) into a TraceContext.
 	UnmarshalTraceContextBinary(marshaled []byte) (TraceContext, error)
 	// Converts the marshaled string:string map (see
-	// `TraceContextMarshaler.MarshalTraceContextStringMap()`) into a TraceContext.
+	// TraceContextMarshaler.MarshalTraceContextStringMap()) into a TraceContext.
 	UnmarshalTraceContextStringMap(marshaled map[string]string) (TraceContext, error)
 }
 
-// A long-lived interface that knows how to create a root TraceContext and
-// serialize/deserialize any other.
+// TraceContextSource is a long-lived interface that knows how to create a root
+// TraceContext and marshal/unmarshal any other.
 type TraceContextSource interface {
 	TraceContextMarshaler
 	TraceContextUnmarshaler

opentracing/utils.go

@@ -7,7 +7,9 @@ import (
 )
 
 const (
-	OpenTracingContextHeaderPrefix = "Opentracing-Context-"
+	// OpenTracingContextHTTPHeaderPrefix precedes all opentracing-related HTTP
+	// headers.
+	OpenTracingContextHTTPHeaderPrefix = "Opentracing-Context-"
 )
 
 // AddTraceContextToHeader marshals TraceContext `ctx` to `h` as a series of
@@ -18,7 +20,7 @@ func AddTraceContextToHeader(
 	marshaler TraceContextMarshaler,
 ) {
 	for headerSuffix, val := range marshaler.MarshalTraceContextStringMap(ctx) {
-		h.Add(OpenTracingContextHeaderPrefix+headerSuffix, url.QueryEscape(val))
+		h.Add(OpenTracingContextHTTPHeaderPrefix+headerSuffix, url.QueryEscape(val))
 	}
 }
 
@@ -30,13 +32,13 @@ func TraceContextFromHeader(
 ) (TraceContext, error) {
 	marshaled := make(map[string]string)
 	for key, val := range h {
-		if strings.HasPrefix(key, OpenTracingContextHeaderPrefix) {
+		if strings.HasPrefix(key, OpenTracingContextHTTPHeaderPrefix) {
 			// We don't know what to do with anything beyond slice item v[0]:
 			unescaped, err := url.QueryUnescape(val[0])
 			if err != nil {
 				return nil, err
 			}
-			marshaled[strings.TrimPrefix(key, OpenTracingContextHeaderPrefix)] = unescaped
+			marshaled[strings.TrimPrefix(key, OpenTracingContextHTTPHeaderPrefix)] = unescaped
 		}
 	}
 	return unmarshaler.UnmarshalTraceContextStringMap(marshaled)