Make span start/end configuration more greppable (#369)

* Make span start/end configuration more greppable

Rename SpanOption to StartOption
Rename StartOptions to StartConfig
Rename EndOptions to EndConfig

fixes #197

api/trace/api.go

@@ -31,7 +31,7 @@ type Provider interface {
 
 type Tracer interface {
 	// Start a span.
-	Start(ctx context.Context, spanName string, startOpts ...SpanOption) (context.Context, Span)
+	Start(ctx context.Context, spanName string, opts ...StartOption) (context.Context, Span)
 
 	// WithSpan wraps the execution of the fn function with a span.
 	// It starts a new span, sets it as an active span in the context,
@@ -43,15 +43,19 @@ type Tracer interface {
 	) error
 }
 
-type EndOptions struct {
+// EndConfig provides options to set properties of span at the time of ending
+// the span.
+type EndConfig struct {
 	EndTime time.Time
 }
 
-type EndOption func(*EndOptions)
+// EndOption applies changes to EndConfig that sets options when the span is ended.
+type EndOption func(*EndConfig)
 
-func WithEndTime(endTime time.Time) EndOption {
-	return func(opts *EndOptions) {
-		opts.EndTime = endTime
+// WithEndTime sets the end time of the span to provided time t, when it is ended.
+func WithEndTime(t time.Time) EndOption {
+	return func(c *EndConfig) {
+		c.EndTime = t
 	}
 }
 
@@ -87,12 +91,12 @@ type Span interface {
 	SetAttributes(...core.KeyValue)
 }
 
-// SpanOption apply changes to SpanOptions.
-type SpanOption func(*SpanOptions)
+// StartOption applies changes to StartConfig that sets options at span start time.
+type StartOption func(*StartConfig)
 
-// SpanOptions provides options to set properties of span at the time of starting
+// StartConfig provides options to set properties of span at the time of starting
 // a new span.
-type SpanOptions struct {
+type StartConfig struct {
 	Attributes []core.KeyValue
 	StartTime  time.Time
 	Links      []Link
@@ -188,34 +192,34 @@ func (sk SpanKind) String() string {
 // WithStartTime sets the start time of the span to provided time t, when it is started.
 // In absence of this option, wall clock time is used as start time.
 // This option is typically used when starting of the span is delayed.
-func WithStartTime(t time.Time) SpanOption {
-	return func(o *SpanOptions) {
-		o.StartTime = t
+func WithStartTime(t time.Time) StartOption {
+	return func(c *StartConfig) {
+		c.StartTime = t
 	}
 }
 
 // WithAttributes sets attributes to span. These attributes provides additional
 // data about the span.
 // Multiple `WithAttributes` options appends the attributes preserving the order.
-func WithAttributes(attrs ...core.KeyValue) SpanOption {
-	return func(o *SpanOptions) {
-		o.Attributes = append(o.Attributes, attrs...)
+func WithAttributes(attrs ...core.KeyValue) StartOption {
+	return func(c *StartConfig) {
+		c.Attributes = append(c.Attributes, attrs...)
 	}
 }
 
 // WithRecord specifies that the span should be recorded.
 // Note that the implementation may still override this preference,
 // e.g., if the span is a child in an unsampled trace.
-func WithRecord() SpanOption {
-	return func(o *SpanOptions) {
-		o.Record = true
+func WithRecord() StartOption {
+	return func(c *StartConfig) {
+		c.Record = true
 	}
 }
 
 // ChildOf. TODO: do we need this?.
-func ChildOf(sc core.SpanContext) SpanOption {
-	return func(o *SpanOptions) {
-		o.Relation = Relation{
+func ChildOf(sc core.SpanContext) StartOption {
+	return func(c *StartConfig) {
+		c.Relation = Relation{
 			SpanContext:      sc,
 			RelationshipType: ChildOfRelationship,
 		}
@@ -223,9 +227,9 @@ func ChildOf(sc core.SpanContext) SpanOption {
 }
 
 // FollowsFrom. TODO: do we need this?.
-func FollowsFrom(sc core.SpanContext) SpanOption {
-	return func(o *SpanOptions) {
-		o.Relation = Relation{
+func FollowsFrom(sc core.SpanContext) StartOption {
+	return func(c *StartConfig) {
+		c.Relation = Relation{
 			SpanContext:      sc,
 			RelationshipType: FollowsFromRelationship,
 		}
@@ -233,15 +237,15 @@ func FollowsFrom(sc core.SpanContext) SpanOption {
 }
 
 // LinkedTo allows instantiating a Span with initial Links.
-func LinkedTo(sc core.SpanContext, attrs ...core.KeyValue) SpanOption {
-	return func(o *SpanOptions) {
-		o.Links = append(o.Links, Link{sc, attrs})
+func LinkedTo(sc core.SpanContext, attrs ...core.KeyValue) StartOption {
+	return func(c *StartConfig) {
+		c.Links = append(c.Links, Link{sc, attrs})
 	}
 }
 
 // WithSpanKind specifies the role a Span on a Trace.
-func WithSpanKind(sk SpanKind) SpanOption {
-	return func(o *SpanOptions) {
-		o.SpanKind = sk
+func WithSpanKind(sk SpanKind) StartOption {
+	return func(c *StartConfig) {
+		c.SpanKind = sk
 	}
 }

api/trace/noop_trace.go

@@ -28,7 +28,7 @@ func (t NoopTracer) WithSpan(ctx context.Context, name string, body func(context
 }
 
 // Start starts a noop span.
-func (NoopTracer) Start(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span) {
+func (NoopTracer) Start(ctx context.Context, name string, opts ...StartOption) (context.Context, Span) {
 	span := NoopSpan{}
 	return SetCurrentSpan(ctx, span), span
 }

bridge/opentracing/bridge.go

@@ -313,7 +313,7 @@ func (t *BridgeTracer) StartSpan(operationName string, opts ...ot.StartSpanOptio
 	bRelation, _ := otSpanReferencesToBridgeRelationAndLinks(sso.References)
 	attributes, kind, hadTrueErrorTag := otTagsToOtelAttributesKindAndError(sso.Tags)
 	checkCtx := migration.WithDeferredSetup(context.Background())
-	checkCtx2, otelSpan := t.setTracer.tracer().Start(checkCtx, operationName, func(opts *oteltrace.SpanOptions) {
+	checkCtx2, otelSpan := t.setTracer.tracer().Start(checkCtx, operationName, func(opts *oteltrace.StartConfig) {
 		opts.Attributes = attributes
 		opts.StartTime = sso.StartTime
 		opts.Relation = bRelation.ToOtelRelation()

bridge/opentracing/internal/mock.go

@@ -75,8 +75,8 @@ func (t *MockTracer) WithSpan(ctx context.Context, name string, body func(contex
 	return body(ctx)
 }
 
-func (t *MockTracer) Start(ctx context.Context, name string, opts ...oteltrace.SpanOption) (context.Context, oteltrace.Span) {
-	spanOpts := oteltrace.SpanOptions{}
+func (t *MockTracer) Start(ctx context.Context, name string, opts ...oteltrace.StartOption) (context.Context, oteltrace.Span) {
+	spanOpts := oteltrace.StartConfig{}
 	for _, opt := range opts {
 		opt(&spanOpts)
 	}
@@ -123,7 +123,7 @@ func (t *MockTracer) addSpareContextValue(ctx context.Context) context.Context {
 	return ctx
 }
 
-func (t *MockTracer) getTraceID(ctx context.Context, spanOpts *oteltrace.SpanOptions) otelcore.TraceID {
+func (t *MockTracer) getTraceID(ctx context.Context, spanOpts *oteltrace.StartConfig) otelcore.TraceID {
 	if parent := t.getParentSpanContext(ctx, spanOpts); parent.IsValid() {
 		return parent.TraceID
 	}
@@ -138,14 +138,14 @@ func (t *MockTracer) getTraceID(ctx context.Context, spanOpts *oteltrace.SpanOpt
 	return t.getRandTraceID()
 }
 
-func (t *MockTracer) getParentSpanID(ctx context.Context, spanOpts *oteltrace.SpanOptions) otelcore.SpanID {
+func (t *MockTracer) getParentSpanID(ctx context.Context, spanOpts *oteltrace.StartConfig) otelcore.SpanID {
 	if parent := t.getParentSpanContext(ctx, spanOpts); parent.IsValid() {
 		return parent.SpanID
 	}
 	return otelcore.SpanID{}
 }
 
-func (t *MockTracer) getParentSpanContext(ctx context.Context, spanOpts *oteltrace.SpanOptions) otelcore.SpanContext {
+func (t *MockTracer) getParentSpanContext(ctx context.Context, spanOpts *oteltrace.StartConfig) otelcore.SpanContext {
 	if spanOpts.Relation.RelationshipType == oteltrace.ChildOfRelationship &&
 		spanOpts.Relation.SpanContext.IsValid() {
 		return spanOpts.Relation.SpanContext
@@ -250,7 +250,7 @@ func (s *MockSpan) End(options ...oteltrace.EndOption) {
 	if !s.EndTime.IsZero() {
 		return // already finished
 	}
-	endOpts := oteltrace.EndOptions{}
+	endOpts := oteltrace.EndConfig{}
 
 	for _, opt := range options {
 		opt(&endOpts)

bridge/opentracing/wrapper.go

@@ -88,7 +88,7 @@ func (t *WrapperTracer) WithSpan(ctx context.Context, name string, body func(con
 // Start forwards the call to the wrapped tracer. It also tries to
 // override the tracer of the returned span if the span implements the
 // OverrideTracerSpanExtension interface.
-func (t *WrapperTracer) Start(ctx context.Context, name string, opts ...oteltrace.SpanOption) (context.Context, oteltrace.Span) {
+func (t *WrapperTracer) Start(ctx context.Context, name string, opts ...oteltrace.StartOption) (context.Context, oteltrace.Span) {
 	ctx, span := t.otelTracer().Start(ctx, name, opts...)
 	if spanWithExtension, ok := span.(migration.OverrideTracerSpanExtension); ok {
 		spanWithExtension.OverrideTracer(t)

internal/trace/mock_tracer.go

@@ -47,8 +47,8 @@ func (mt *MockTracer) WithSpan(ctx context.Context, name string, body func(conte
 // TracdID is used from Relation Span Context and SpanID is assigned.
 // If Relation SpanContext option is not specified then random TraceID is used.
 // No other options are supported.
-func (mt *MockTracer) Start(ctx context.Context, name string, o ...apitrace.SpanOption) (context.Context, apitrace.Span) {
-	var opts apitrace.SpanOptions
+func (mt *MockTracer) Start(ctx context.Context, name string, o ...apitrace.StartOption) (context.Context, apitrace.Span) {
+	var opts apitrace.StartConfig
 	for _, op := range o {
 		op(&opts)
 	}

plugin/othttp/handler.go

@@ -49,12 +49,12 @@ type Handler struct {
 	operation string
 	handler   http.Handler
 
-	tracer      trace.Tracer
-	prop        propagators.TextFormat
-	spanOptions []trace.SpanOption
-	public      bool
-	readEvent   bool
-	writeEvent  bool
+	tracer           trace.Tracer
+	prop             propagators.TextFormat
+	spanStartOptions []trace.StartOption
+	public           bool
+	readEvent        bool
+	writeEvent       bool
 }
 
 // Option function used for setting *optional* Handler properties
@@ -87,10 +87,10 @@ func WithPropagator(p propagators.TextFormat) Option {
 }
 
 // WithSpanOptions configures the Handler with an additional set of
-// trace.SpanOptions, which are applied to each new span.
-func WithSpanOptions(opts ...trace.SpanOption) Option {
+// trace.StartOptions, which are applied to each new span.
+func WithSpanOptions(opts ...trace.StartOption) Option {
 	return func(h *Handler) {
-		h.spanOptions = opts
+		h.spanStartOptions = opts
 	}
 }
 
@@ -142,12 +142,12 @@ func NewHandler(handler http.Handler, operation string, opts ...Option) http.Han
 
 // ServeHTTP serves HTTP requests (http.Handler)
 func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	opts := append([]trace.SpanOption{}, h.spanOptions...) // start with the configured options
+	opts := append([]trace.StartOption{}, h.spanStartOptions...) // start with the configured options
 
 	// TODO: do something with the correlation context
 	sc, _ := h.prop.Extract(r.Context(), r.Header)
 	if sc.IsValid() { // not a valid span context, so no link / parent relationship to establish
-		var opt trace.SpanOption
+		var opt trace.StartOption
 		if h.public {
 			// If the endpoint is a public endpoint, it should start a new trace
 			// and incoming remote sctx should be added as a link.

sdk/trace/span.go

@@ -102,7 +102,7 @@ func (s *span) End(options ...apitrace.EndOption) {
 	if !s.IsRecording() {
 		return
 	}
-	opts := apitrace.EndOptions{}
+	opts := apitrace.EndConfig{}
 	for _, opt := range options {
 		opt(&opts)
 	}
@@ -245,7 +245,7 @@ func (s *span) addChild() {
 	s.mu.Unlock()
 }
 
-func startSpanInternal(tr *tracer, name string, parent core.SpanContext, remoteParent bool, o apitrace.SpanOptions) *span {
+func startSpanInternal(tr *tracer, name string, parent core.SpanContext, remoteParent bool, o apitrace.StartConfig) *span {
 	var noParent bool
 	span := &span{}
 	span.spanContext = parent

sdk/trace/trace_test.go

@@ -175,7 +175,7 @@ func TestSampling(t *testing.T) {
 			tr := p.Tracer("test")
 			var sampled int
 			for i := 0; i < total; i++ {
-				var opts []apitrace.SpanOption
+				var opts []apitrace.StartOption
 				if tc.parent {
 					psc := core.SpanContext{
 						TraceID: idg.NewTraceID(),
@@ -657,7 +657,7 @@ func checkChild(p core.SpanContext, apiSpan apitrace.Span) error {
 
 // startSpan starts a span with a name "span0". See startNamedSpan for
 // details.
-func startSpan(tp *Provider, trName string, args ...apitrace.SpanOption) apitrace.Span {
+func startSpan(tp *Provider, trName string, args ...apitrace.StartOption) apitrace.Span {
 	return startNamedSpan(tp, trName, "span0", args...)
 }
 
@@ -665,7 +665,7 @@ func startSpan(tp *Provider, trName string, args ...apitrace.SpanOption) apitrac
 // passed name and with ChildOf option.  remote span context contains
 // TraceFlags with sampled bit set. This allows the span to be
 // automatically sampled.
-func startNamedSpan(tp *Provider, trName, name string, args ...apitrace.SpanOption) apitrace.Span {
+func startNamedSpan(tp *Provider, trName, name string, args ...apitrace.StartOption) apitrace.Span {
 	args = append(args, apitrace.ChildOf(remoteSpanContext()), apitrace.WithRecord())
 	_, span := tp.Tracer(trName).Start(
 		context.Background(),

sdk/trace/tracer.go

@@ -28,8 +28,8 @@ type tracer struct {
 
 var _ apitrace.Tracer = &tracer{}
 
-func (tr *tracer) Start(ctx context.Context, name string, o ...apitrace.SpanOption) (context.Context, apitrace.Span) {
-	var opts apitrace.SpanOptions
+func (tr *tracer) Start(ctx context.Context, name string, o ...apitrace.StartOption) (context.Context, apitrace.Span) {
+	var opts apitrace.StartConfig
 	var parent core.SpanContext
 	var remoteParent bool