Merge branch 'main' into carrier-keys

CHANGELOG.md

@@ -8,6 +8,11 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Changed
+
+- Replaced interface `oteltest.SpanRecorder` with its existing implementation
+  `StandardSpanRecorder` (#1542).
+
 ### Added
 
 - Added `resource.Default()` for use with meter and tracer providers. (#1507)

bridge/opencensus/bridge_test.go

@@ -28,7 +28,7 @@ import (
 )
 
 func TestMixedAPIs(t *testing.T) {
-	sr := new(oteltest.StandardSpanRecorder)
+	sr := new(oteltest.SpanRecorder)
 	tp := oteltest.NewTracerProvider(oteltest.WithSpanRecorder(sr))
 	tracer := tp.Tracer("mixedapitracer")
 	octrace.DefaultTracer = NewTracer(tracer)
@@ -74,7 +74,7 @@ func TestMixedAPIs(t *testing.T) {
 }
 
 func TestStartOptions(t *testing.T) {
-	sr := new(oteltest.StandardSpanRecorder)
+	sr := new(oteltest.SpanRecorder)
 	tp := oteltest.NewTracerProvider(oteltest.WithSpanRecorder(sr))
 	octrace.DefaultTracer = NewTracer(tp.Tracer("startoptionstracer"))
 
@@ -94,7 +94,7 @@ func TestStartOptions(t *testing.T) {
 }
 
 func TestStartSpanWithRemoteParent(t *testing.T) {
-	sr := new(oteltest.StandardSpanRecorder)
+	sr := new(oteltest.SpanRecorder)
 	tp := oteltest.NewTracerProvider(oteltest.WithSpanRecorder(sr))
 	tracer := tp.Tracer("remoteparent")
 	octrace.DefaultTracer = NewTracer(tracer)
@@ -117,7 +117,7 @@ func TestStartSpanWithRemoteParent(t *testing.T) {
 }
 
 func TestToFromContext(t *testing.T) {
-	sr := new(oteltest.StandardSpanRecorder)
+	sr := new(oteltest.SpanRecorder)
 	tp := oteltest.NewTracerProvider(oteltest.WithSpanRecorder(sr))
 	tracer := tp.Tracer("tofromcontext")
 	octrace.DefaultTracer = NewTracer(tracer)
@@ -158,7 +158,7 @@ func TestToFromContext(t *testing.T) {
 }
 
 func TestIsRecordingEvents(t *testing.T) {
-	sr := new(oteltest.StandardSpanRecorder)
+	sr := new(oteltest.SpanRecorder)
 	tp := oteltest.NewTracerProvider(oteltest.WithSpanRecorder(sr))
 	octrace.DefaultTracer = NewTracer(tp.Tracer("isrecordingevents"))
 
@@ -170,7 +170,7 @@ func TestIsRecordingEvents(t *testing.T) {
 }
 
 func TestSetThings(t *testing.T) {
-	sr := new(oteltest.StandardSpanRecorder)
+	sr := new(oteltest.SpanRecorder)
 	tp := oteltest.NewTracerProvider(oteltest.WithSpanRecorder(sr))
 	octrace.DefaultTracer = NewTracer(tp.Tracer("setthings"))
 

internal/global/trace_test.go

@@ -35,7 +35,7 @@ func TestTraceWithSDK(t *testing.T) {
 	// This is started before an SDK was registered and should be dropped.
 	_, span1 := tracer1.Start(ctx, "span1")
 
-	sr := new(oteltest.StandardSpanRecorder)
+	sr := new(oteltest.SpanRecorder)
 	tp := oteltest.NewTracerProvider(oteltest.WithSpanRecorder(sr))
 	otel.SetTracerProvider(tp)
 

oteltest/config.go

@@ -46,7 +46,7 @@ type config struct {
 	SpanContextFunc func(context.Context) trace.SpanContext
 
 	// SpanRecorder keeps track of spans.
-	SpanRecorder SpanRecorder
+	SpanRecorder *SpanRecorder
 }
 
 func newConfig(opts ...Option) config {
@@ -80,7 +80,7 @@ func WithSpanContextFunc(f func(context.Context) trace.SpanContext) Option {
 }
 
 type spanRecorderOption struct {
-	SpanRecorder SpanRecorder
+	SpanRecorder *SpanRecorder
 }
 
 func (o spanRecorderOption) Apply(c *config) {
@@ -89,22 +89,13 @@ func (o spanRecorderOption) Apply(c *config) {
 
 // WithSpanRecorder sets the SpanRecorder to use with the TracerProvider for
 // testing.
-func WithSpanRecorder(sr SpanRecorder) Option {
+func WithSpanRecorder(sr *SpanRecorder) Option {
 	return spanRecorderOption{sr}
 }
 
 // SpanRecorder performs operations to record a span as it starts and ends.
-type SpanRecorder interface {
-	// OnStart is called by the Tracer when it starts a Span.
-	OnStart(span *Span)
-	// OnEnd is called by the Span when it ends.
-	OnEnd(span *Span)
-}
-
-// StandardSpanRecorder is a SpanRecorder that records all started and ended
-// spans in an ordered recording. StandardSpanRecorder is designed to be
-// concurrent safe and can by used by multiple goroutines.
-type StandardSpanRecorder struct {
+// It is designed to be concurrent safe and can by used by multiple goroutines.
+type SpanRecorder struct {
 	startedMu sync.RWMutex
 	started   []*Span
 
@@ -113,21 +104,21 @@ type StandardSpanRecorder struct {
 }
 
 // OnStart records span as started.
-func (ssr *StandardSpanRecorder) OnStart(span *Span) {
+func (ssr *SpanRecorder) OnStart(span *Span) {
 	ssr.startedMu.Lock()
 	defer ssr.startedMu.Unlock()
 	ssr.started = append(ssr.started, span)
 }
 
 // OnEnd records span as completed.
-func (ssr *StandardSpanRecorder) OnEnd(span *Span) {
+func (ssr *SpanRecorder) OnEnd(span *Span) {
 	ssr.doneMu.Lock()
 	defer ssr.doneMu.Unlock()
 	ssr.done = append(ssr.done, span)
 }
 
 // Started returns a copy of all started Spans in the order they were started.
-func (ssr *StandardSpanRecorder) Started() []*Span {
+func (ssr *SpanRecorder) Started() []*Span {
 	ssr.startedMu.RLock()
 	defer ssr.startedMu.RUnlock()
 	started := make([]*Span, len(ssr.started))
@@ -138,7 +129,7 @@ func (ssr *StandardSpanRecorder) Started() []*Span {
 }
 
 // Completed returns a copy of all ended Spans in the order they were ended.
-func (ssr *StandardSpanRecorder) Completed() []*Span {
+func (ssr *SpanRecorder) Completed() []*Span {
 	ssr.doneMu.RLock()
 	defer ssr.doneMu.RUnlock()
 	done := make([]*Span, len(ssr.done))

oteltest/doc.go

@@ -45,7 +45,7 @@ introspection of their state and history. Additionally, a SpanRecorder can be
 provided to the TracerProvider to record all Spans started and ended by the
 testing structures.
 
-	sr := new(oteltest.StandardSpanRecorder)
+	sr := new(oteltest.SpanRecorder)
 	tp := oteltest.NewTracerProvider(oteltest.WithSpanRecorder(sr))
 */
 package oteltest // import "go.opentelemetry.io/otel/oteltest"

oteltest/tracer_test.go

@@ -295,7 +295,7 @@ func testTracedSpan(t *testing.T, fn func(tracer trace.Tracer, name string) (tra
 
 		e := matchers.NewExpecter(t)
 
-		sr := new(oteltest.StandardSpanRecorder)
+		sr := new(oteltest.SpanRecorder)
 		subject := oteltest.NewTracerProvider(oteltest.WithSpanRecorder(sr)).Tracer(t.Name())
 		subject.Start(context.Background(), "span1")
 
@@ -315,7 +315,7 @@ func testTracedSpan(t *testing.T, fn func(tracer trace.Tracer, name string) (tra
 
 		e := matchers.NewExpecter(t)
 
-		sr := new(oteltest.StandardSpanRecorder)
+		sr := new(oteltest.SpanRecorder)
 		subject := oteltest.NewTracerProvider(oteltest.WithSpanRecorder(sr)).Tracer(t.Name())
 
 		numSpans := 2

sdk/trace/span.go

@@ -137,13 +137,16 @@ type span struct {
 
 var _ trace.Span = &span{}
 
+// SpanContext returns the SpanContext of this span.
 func (s *span) SpanContext() trace.SpanContext {
 	if s == nil {
 		return trace.SpanContext{}
 	}
 	return s.spanContext
 }
 
+// IsRecording returns if this span is being recorded. If this span has ended
+// this will return false.
 func (s *span) IsRecording() bool {
 	if s == nil {
 		return false
@@ -153,10 +156,10 @@ func (s *span) IsRecording() bool {
 	return s.endTime.IsZero()
 }
 
+// SetStatus sets the status of this span in the form of a code and a
+// message. This overrides the existing value of this span's status if one
+// exists. If this span is not being recorded than this method does nothing.
 func (s *span) SetStatus(code codes.Code, msg string) {
-	if s == nil {
-		return
-	}
 	if !s.IsRecording() {
 		return
 	}
@@ -166,21 +169,30 @@ func (s *span) SetStatus(code codes.Code, msg string) {
 	s.mu.Unlock()
 }
 
+// SetAttributes sets attributes of this span.
+//
+// If a key from attributes already exists the value associated with that key
+// will be overwritten with the value contained in attributes.
+//
+// If this span is not being recorded than this method does nothing.
 func (s *span) SetAttributes(attributes ...label.KeyValue) {
 	if !s.IsRecording() {
 		return
 	}
 	s.copyToCappedAttributes(attributes...)
 }
 
-// End ends the span.
+// End ends the span. This method does nothing if the span is already ended or
+// is not being recorded.
 //
 // The only SpanOption currently supported is WithTimestamp which will set the
 // end time for a Span's life-cycle.
 //
 // If this method is called while panicking an error event is added to the
 // Span before ending it and the panic is continued.
 func (s *span) End(options ...trace.SpanOption) {
+	// Do not start by checking if the span is being recorded which requires
+	// acquiring a lock. Make a minimal check that the span is not nil.
 	if s == nil {
 		return
 	}
@@ -189,6 +201,12 @@ func (s *span) End(options ...trace.SpanOption) {
 	// the span's duration in case some operation below takes a while.
 	et := internal.MonotonicEndTime(s.startTime)
 
+	// Do relative expensive check now that we have an end time and see if we
+	// need to do any more processing.
+	if !s.IsRecording() {
+		return
+	}
+
 	if recovered := recover(); recovered != nil {
 		// Record but don't stop the panic.
 		defer panic(recovered)
@@ -205,13 +223,10 @@ func (s *span) End(options ...trace.SpanOption) {
 		s.executionTracerTaskEnd()
 	}
 
-	if !s.IsRecording() {
-		return
-	}
-
 	config := trace.NewSpanConfig(options...)
 
 	s.mu.Lock()
+	// Setting endTime to non-zero marks the span as ended and not recording.
 	if config.Timestamp.IsZero() {
 		s.endTime = et
 	} else {
@@ -228,6 +243,8 @@ func (s *span) End(options ...trace.SpanOption) {
 	}
 }
 
+// RecordError will record err as a span event for this span. If this span is
+// not being recorded or err is nil than this method does nothing.
 func (s *span) RecordError(err error, opts ...trace.EventOption) {
 	if s == nil || err == nil || !s.IsRecording() {
 		return
@@ -250,10 +267,13 @@ func typeStr(i interface{}) string {
 	return fmt.Sprintf("%s.%s", t.PkgPath(), t.Name())
 }
 
+// Tracer returns the Tracer that created this span.
 func (s *span) Tracer() trace.Tracer {
 	return s.tracer
 }
 
+// AddEvent adds an event with the provided name and options. If this span is
+// not being recorded than this method does nothing.
 func (s *span) AddEvent(name string, o ...trace.EventOption) {
 	if !s.IsRecording() {
 		return
@@ -273,7 +293,13 @@ func (s *span) addEvent(name string, o ...trace.EventOption) {
 	})
 }
 
+// SetName sets the name of this span. If this span is not being recorded than
+// this method does nothing.
 func (s *span) SetName(name string) {
+	if !s.IsRecording() {
+		return
+	}
+
 	s.mu.Lock()
 	defer s.mu.Unlock()
 
@@ -307,36 +333,43 @@ func (s *span) SetName(name string) {
 	}
 }
 
+// Name returns the name of this span.
 func (s *span) Name() string {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	return s.name
 }
 
+// Name returns the SpanContext of this span's parent span.
 func (s *span) Parent() trace.SpanContext {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	return s.parent
 }
 
+// SpanKind returns the SpanKind of this span.
 func (s *span) SpanKind() trace.SpanKind {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	return s.spanKind
 }
 
+// StartTime returns the time this span started.
 func (s *span) StartTime() time.Time {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	return s.startTime
 }
 
+// EndTime returns the time this span ended. For spans that have not yet
+// ended, the returned value will be the zero value of time.Time.
 func (s *span) EndTime() time.Time {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	return s.endTime
 }
 
+// Attributes returns the attributes of this span.
 func (s *span) Attributes() []label.KeyValue {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -346,6 +379,7 @@ func (s *span) Attributes() []label.KeyValue {
 	return s.attributes.toKeyValue()
 }
 
+// Events returns the links of this span.
 func (s *span) Links() []trace.Link {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -355,6 +389,7 @@ func (s *span) Links() []trace.Link {
 	return s.interfaceArrayToLinksArray()
 }
 
+// Events returns the events of this span.
 func (s *span) Events() []trace.Event {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -364,24 +399,30 @@ func (s *span) Events() []trace.Event {
 	return s.interfaceArrayToMessageEventArray()
 }
 
+// StatusCode returns the status code of this span.
 func (s *span) StatusCode() codes.Code {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	return s.statusCode
 }
 
+// StatusMessage returns the status message of this span.
 func (s *span) StatusMessage() string {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	return s.statusMessage
 }
 
+// InstrumentationLibrary returns the instrumentation.Library associated with
+// the Tracer that created this span.
 func (s *span) InstrumentationLibrary() instrumentation.Library {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	return s.instrumentationLibrary
 }
 
+// Resource returns the Resource associated with the Tracer that created this
+// span.
 func (s *span) Resource() *resource.Resource {
 	s.mu.Lock()
 	defer s.mu.Unlock()