Add WithClock TracerProviderOption

CHANGELOG.md

@@ -10,6 +10,10 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Added
 
+- The `"go.opentelemetry.io/otel/sdk/trace".TraceProvider` can now be configured with a newly added `Clock` interface.
+  This interface is called when determining the start and end times for a span.
+  Additionally, a `WithClock` is also added to the package enabling users to set custom implementations of the `Clock` interface.
+  The standard library `time` package is still used for this functionality by default if no option is set. (#2052)
 - Added `ErrorHandlerFunc` to use a function as an `"go.opentelemetry.io/otel".ErrorHandler`. (#2149)
 
 ### Changed

sdk/internal/internal.go

@@ -16,22 +16,10 @@ package internal // import "go.opentelemetry.io/otel/sdk/internal"
 
 import (
 	"fmt"
-	"time"
 
 	"go.opentelemetry.io/otel"
 )
 
 // UserAgent is the user agent to be added to the outgoing
 // requests from the exporters.
 var UserAgent = fmt.Sprintf("opentelemetry-go/%s", otel.Version())
-
-// MonotonicEndTime returns the end time at present
-// but offset from start, monotonically.
-//
-// The monotonic clock is used in subtractions hence
-// the duration since start added back to start gives
-// end as a monotonic time.
-// See https://golang.org/pkg/time/#hdr-Monotonic_Clocks
-func MonotonicEndTime(start time.Time) time.Time {
-	return start.Add(time.Since(start))
-}

sdk/trace/provider.go

@@ -21,10 +21,9 @@ import (
 	"sync/atomic"
 
 	"go.opentelemetry.io/otel"
-	"go.opentelemetry.io/otel/trace"
-
 	"go.opentelemetry.io/otel/sdk/instrumentation"
 	"go.opentelemetry.io/otel/sdk/resource"
+	"go.opentelemetry.io/otel/trace"
 )
 
 const (
@@ -51,6 +50,9 @@ type tracerProviderConfig struct {
 
 	// resource contains attributes representing an entity that produces telemetry.
 	resource *resource.Resource
+
+	// clock is used to provide start/end time for spans
+	clock Clock
 }
 
 type TracerProvider struct {
@@ -61,6 +63,7 @@ type TracerProvider struct {
 	idGenerator    IDGenerator
 	spanLimits     SpanLimits
 	resource       *resource.Resource
+	clock          Clock
 }
 
 var _ trace.TracerProvider = &TracerProvider{}
@@ -90,6 +93,7 @@ func NewTracerProvider(opts ...TracerProviderOption) *TracerProvider {
 		idGenerator: o.idGenerator,
 		spanLimits:  o.spanLimits,
 		resource:    o.resource,
+		clock:       o.clock,
 	}
 
 	for _, sp := range o.processors {
@@ -330,6 +334,23 @@ func WithSpanLimits(sl SpanLimits) TracerProviderOption {
 	})
 }
 
+// WithClock returns a TracerProviderOption that will configure the
+// TracerProvider's clock. The configured clock is used by Tracers
+// to generate span start/end time. Clock.Stopwatch should start and
+// return a Stopwatch instance. For Stopwatch implementation,
+// Stopwatch.Started should return the time.Time when the stopwatch
+// started. Stopwatch.Elapsed should return the time.Duration measuring
+// the elapsed time from when the stopwatch started. Its value should be
+// positive to ensure monotonic start/end time of the span.
+//
+// If this option is not used, the TracerProvider will provide the default
+// clock which just calls the time package under the hood.
+func WithClock(clk Clock) TracerProviderOption {
+	return traceProviderOptionFunc(func(cfg *tracerProviderConfig) {
+		cfg.clock = clk
+	})
+}
+
 // ensureValidTracerProviderConfig ensures that given TracerProviderConfig is valid.
 func ensureValidTracerProviderConfig(cfg *tracerProviderConfig) {
 	if cfg.sampler == nil {
@@ -342,4 +363,7 @@ func ensureValidTracerProviderConfig(cfg *tracerProviderConfig) {
 	if cfg.resource == nil {
 		cfg.resource = resource.Default()
 	}
+	if cfg.clock == nil {
+		cfg.clock = defaultClock()
+	}
 }

sdk/trace/span.go

@@ -27,7 +27,6 @@ import (
 	"go.opentelemetry.io/otel/trace"
 
 	"go.opentelemetry.io/otel/sdk/instrumentation"
-	"go.opentelemetry.io/otel/sdk/internal"
 	"go.opentelemetry.io/otel/sdk/resource"
 )
 
@@ -112,9 +111,6 @@ type span struct {
 	// name is the name of this span.
 	name string
 
-	// startTime is the time at which this span was started.
-	startTime time.Time
-
 	// endTime is the time at which this span was ended. It contains the zero
 	// value of time.Time until the span is ended.
 	endTime time.Time
@@ -154,6 +150,9 @@ type span struct {
 
 	// spanLimits holds the limits to this span.
 	spanLimits SpanLimits
+
+	// stopwatch holds the Stopwatch returned by Clock.Start method
+	stopwatch Stopwatch
 }
 
 var _ trace.Span = &span{}
@@ -175,7 +174,7 @@ func (s *span) IsRecording() bool {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 
-	return !s.startTime.IsZero() && s.endTime.IsZero()
+	return !s.startTime().IsZero() && s.endTime.IsZero()
 }
 
 // SetStatus sets the status of the Span in the form of a code and a
@@ -227,7 +226,7 @@ func (s *span) End(options ...trace.SpanEndOption) {
 
 	// Store the end time as soon as possible to avoid artificially increasing
 	// the span's duration in case some operation below takes a while.
-	et := internal.MonotonicEndTime(s.startTime)
+	et := s.stopwatch.Started().Add(s.stopwatch.Stop())
 
 	// Do relative expensive check now that we have an end time and see if we
 	// need to do any more processing.
@@ -364,7 +363,7 @@ func (s *span) SpanKind() trace.SpanKind {
 func (s *span) StartTime() time.Time {
 	s.mu.Lock()
 	defer s.mu.Unlock()
-	return s.startTime
+	return s.startTime()
 }
 
 // EndTime returns the time this span ended. For spans that have not yet
@@ -497,7 +496,7 @@ func (s *span) snapshot() ReadOnlySpan {
 	sd.resource = s.resource
 	sd.spanContext = s.spanContext
 	sd.spanKind = s.spanKind
-	sd.startTime = s.startTime
+	sd.startTime = s.startTime()
 	sd.status = s.status
 	sd.childSpanCount = s.childSpanCount
 
@@ -555,8 +554,14 @@ func (s *span) addChild() {
 
 func (*span) private() {}
 
+func (s *span) startTime() time.Time {
+	return s.stopwatch.Started()
+}
+
 func startSpanInternal(ctx context.Context, tr *tracer, name string, o *trace.SpanConfig) *span {
-	span := &span{}
+	span := &span{
+		stopwatch: nilStopwatch{},
+	}
 
 	provider := tr.provider
 
@@ -614,10 +619,10 @@ func startSpanInternal(ctx context.Context, tr *tracer, name string, o *trace.Sp
 
 	startTime := o.Timestamp()
 	if startTime.IsZero() {
-		startTime = time.Now()
+		span.stopwatch = tr.provider.clock.Stopwatch()
+	} else {
+		span.stopwatch = standardStopwatch(startTime)
 	}
-	span.startTime = startTime
-
 	span.spanKind = trace.ValidateSpanKind(o.SpanKind())
 	span.name = name
 	span.parent = psc

sdk/trace/time.go

@@ -0,0 +1,65 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package trace
+
+import (
+	"time"
+)
+
+// Clock is the entrypoint for providing time to span's start/end timestamp.
+// By default the standard "time" package will be used. User can replace
+// it with customized clock implementation (e.g. with additional clock
+// synchronization logic) by using the `WithClock` option.
+type Clock interface {
+	// Stopwatch returns a started Stopwatch measuring a time interval.
+	Stopwatch() Stopwatch
+}
+
+type Stopwatch interface {
+	// Started returns the time the Stopwatch was started.
+	Started() time.Time
+	// Stop stops the stopwatch and returns the duration from when this Stopwatch was started.
+	// This will only be called once when generating span's end time and should return a positive
+	// time.Duration in order to ensure the monotonicity of span's start/end time.
+	Stop() time.Duration
+}
+
+type standardClock struct{}
+type standardStopwatch time.Time
+type nilStopwatch struct{}
+
+func defaultClock() Clock {
+	return standardClock{}
+}
+
+func (standardClock) Stopwatch() Stopwatch {
+	return standardStopwatch(time.Now())
+}
+
+func (w standardStopwatch) Started() time.Time {
+	return time.Time(w)
+}
+
+func (w standardStopwatch) Stop() time.Duration {
+	return time.Since(time.Time(w))
+}
+
+func (w nilStopwatch) Started() time.Time {
+	return time.Time{}
+}
+
+func (w nilStopwatch) Stop() time.Duration {
+	return 0
+}

sdk/trace/trace_test.go

@@ -1594,6 +1594,49 @@ func TestAddLinksWithMoreAttributesThanLimit(t *testing.T) {
 	}
 }
 
+type frozenClock struct {
+	now time.Time
+}
+type frozenStopwatch struct {
+	started time.Time
+}
+
+func (f frozenStopwatch) Started() time.Time {
+	return f.started
+}
+func (f frozenStopwatch) Stop() time.Duration {
+	return 0
+}
+
+// newFrozenClock returns a clock which stops at time t
+func newFrozenClock(t time.Time) frozenClock {
+	return frozenClock{
+		now: t,
+	}
+}
+
+func (c frozenClock) Stopwatch() Stopwatch {
+	return frozenStopwatch{
+		started: c.now,
+	}
+}
+
+func TestCustomClock(t *testing.T) {
+	te := NewTestExporter()
+	now := time.Now()
+	tp := NewTracerProvider(WithSyncer(te), WithClock(newFrozenClock(now)))
+	tracer := tp.Tracer("custom-clock")
+
+	_, span := tracer.Start(context.Background(), "test-frozen-clock")
+	time.Sleep(time.Microsecond * 2)
+	span.End()
+	require.Equal(t, te.Len(), 1, "should only have one span")
+
+	got := te.Spans()[0]
+	assert.Equal(t, now, got.StartTime(), "StartTime should return the frozen time")
+	assert.Equal(t, now, got.EndTime(), "EndTime should return the frozen time")
+}
+
 type stateSampler struct {
 	prefix string
 	f      func(trace.TraceState) trace.TraceState