Consolidate AddEvent and Event methods, add FinishOptions (open-telemetry#99)

* Merge two event methods in span API

There was an agreement to get rid of the Event interface and
consolidate the two methods for adding events into one. See open-telemetry#57.

* Eliminate the use of the Event interface

There is no need for the SDK to provide the implementation of the
Event interface - it is used nowhere.

* Drop the Event interface

It's dead code now.

* Make it possible to override a finish timestamp through options

Opentracing to opentelemetry bridge will certainly use this feature.

* Obey the start time option

* Add tests for events and custom start/end times

Author: krnowak

api/event/event.go

@@ -21,7 +21,6 @@ import (
 	"google.golang.org/grpc/codes"
 
 	"go.opentelemetry.io/api/core"
-	"go.opentelemetry.io/api/event"
 	"go.opentelemetry.io/api/tag"
 )
 
@@ -50,18 +49,28 @@ type Tracer interface {
 	Inject(context.Context, Span, Injector)
 }
 
+type FinishOptions struct {
+	FinishTime time.Time
+}
+
+type FinishOption func(*FinishOptions)
+
+func WithFinishTime(finishTime time.Time) FinishOption {
+	return func(opts *FinishOptions) {
+		opts.FinishTime = finishTime
+	}
+}
+
 type Span interface {
 	// Tracer returns tracer used to create this span. Tracer cannot be nil.
 	Tracer() Tracer
 
 	// Finish completes the span. No updates are allowed to span after it
 	// finishes. The only exception is setting status of the span.
-	Finish()
+	Finish(options ...FinishOption)
 
 	// AddEvent adds an event to the span.
-	AddEvent(ctx context.Context, event event.Event)
-	// AddEvent records an event to the span.
-	Event(ctx context.Context, msg string, attrs ...core.KeyValue)
+	AddEvent(ctx context.Context, msg string, attrs ...core.KeyValue)
 
 	// IsRecordingEvents returns true if the span is active and recording events is enabled.
 	IsRecordingEvents() bool

api/trace/api.go

@@ -7,7 +7,6 @@ import (
 	"google.golang.org/grpc/codes"
 
 	"go.opentelemetry.io/api/core"
-	"go.opentelemetry.io/api/event"
 	"go.opentelemetry.io/api/tag"
 	"go.opentelemetry.io/api/trace"
 )
@@ -97,18 +96,14 @@ func (mockSpan) ModifyAttributes(mutators ...tag.Mutator) {
 }
 
 // Finish does nothing.
-func (mockSpan) Finish() {
+func (mockSpan) Finish(options ...trace.FinishOption) {
 }
 
 // Tracer returns noop implementation of Tracer.
 func (mockSpan) Tracer() trace.Tracer {
 	return trace.NoopTracer{}
 }
 
-// AddEvent does nothing.
-func (mockSpan) AddEvent(ctx context.Context, event event.Event) {
-}
-
 // Event does nothing.
-func (mockSpan) Event(ctx context.Context, msg string, attrs ...core.KeyValue) {
+func (mockSpan) AddEvent(ctx context.Context, msg string, attrs ...core.KeyValue) {
 }

api/trace/current_test.go

@@ -20,7 +20,6 @@ import (
 	"google.golang.org/grpc/codes"
 
 	"go.opentelemetry.io/api/core"
-	"go.opentelemetry.io/api/event"
 	"go.opentelemetry.io/api/tag"
 )
 
@@ -64,7 +63,7 @@ func (NoopSpan) ModifyAttributes(mutators ...tag.Mutator) {
 }
 
 // Finish does nothing.
-func (NoopSpan) Finish() {
+func (NoopSpan) Finish(options ...FinishOption) {
 }
 
 // Tracer returns noop implementation of Tracer.
@@ -73,11 +72,7 @@ func (NoopSpan) Tracer() Tracer {
 }
 
 // AddEvent does nothing.
-func (NoopSpan) AddEvent(ctx context.Context, event event.Event) {
-}
-
-// Event does nothing.
-func (NoopSpan) Event(ctx context.Context, msg string, attrs ...core.KeyValue) {
+func (NoopSpan) AddEvent(ctx context.Context, msg string, attrs ...core.KeyValue) {
 }
 
 // SetName does nothing.

api/trace/noop_span.go

@@ -63,7 +63,7 @@ func main() {
 
 	err := tracer.WithSpan(ctx, "operation", func(ctx context.Context) error {
 
-		trace.CurrentSpan(ctx).Event(ctx, "Nice operation!", key.New("bogons").Int(100))
+		trace.CurrentSpan(ctx).AddEvent(ctx, "Nice operation!", key.New("bogons").Int(100))
 
 		trace.CurrentSpan(ctx).SetAttributes(anotherKey.String("yes"))
 
@@ -75,7 +75,7 @@ func main() {
 			func(ctx context.Context) error {
 				trace.CurrentSpan(ctx).SetAttribute(lemonsKey.String("five"))
 
-				trace.CurrentSpan(ctx).Event(ctx, "Sub span event")
+				trace.CurrentSpan(ctx).AddEvent(ctx, "Sub span event")
 
 				stats.Record(ctx, measureTwo.M(1.3))
 

example/basic/main.go

@@ -49,7 +49,7 @@ func main() {
 		)
 		defer span.Finish()
 
-		span.Event(ctx, "handling this...")
+		span.AddEvent(ctx, "handling this...")
 
 		_, _ = io.WriteString(w, "Hello, world!\n")
 	}

example/http/server/server.go

@@ -36,7 +36,6 @@ type ScopeID struct {
 	core.SpanContext
 }
 
-// TODO: this Event is confusing with event.Event.
 type Event struct {
 	// Automatic fields
 	Sequence EventID   // Auto-filled

experimental/streaming/exporter/observer/observer.go

@@ -0,0 +1,60 @@
+// Copyright 2019, 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 internal // import "go.opentelemetry.io/experimental/streaming/sdk/internal"
+
+import (
+	"go.opentelemetry.io/experimental/streaming/exporter/observer"
+)
+
+type eventsMap map[observer.EventType][]observer.Event
+
+type TestObserver struct {
+	events eventsMap
+}
+
+var _ observer.Observer = &TestObserver{}
+
+func NewRegisteredObserver() *TestObserver {
+	o := &TestObserver{}
+	observer.RegisterObserver(o)
+	return o
+}
+
+func (o *TestObserver) Unregister() {
+	observer.UnregisterObserver(o)
+}
+
+func (o *TestObserver) Observe(e observer.Event) {
+	if o.events == nil {
+		o.events = make(eventsMap)
+	}
+	o.events[e.Type] = append(o.events[e.Type], e)
+}
+
+func (o *TestObserver) Clear() {
+	o.events = nil
+}
+
+func (o *TestObserver) ClearAndUnregister() {
+	o.Clear()
+	o.Unregister()
+}
+
+func (o *TestObserver) Events(eType observer.EventType) []observer.Event {
+	if o.events == nil {
+		return nil
+	}
+	return o.events[eType]
+}

experimental/streaming/sdk/internal/test_observer.go

@@ -16,11 +16,11 @@ package sdk
 
 import (
 	"context"
+	"time"
 
 	"google.golang.org/grpc/codes"
 
 	"go.opentelemetry.io/api/core"
-	"go.opentelemetry.io/api/event"
 	"go.opentelemetry.io/api/tag"
 	apitrace "go.opentelemetry.io/api/trace"
 	"go.opentelemetry.io/experimental/streaming/exporter/observer"
@@ -87,9 +87,14 @@ func (sp *span) ModifyAttributes(mutators ...tag.Mutator) {
 	})
 }
 
-func (sp *span) Finish() {
+func (sp *span) Finish(options ...apitrace.FinishOption) {
 	recovered := recover()
+	opts := apitrace.FinishOptions{}
+	for _, opt := range options {
+		opt(&opts)
+	}
 	observer.Record(observer.Event{
+		Time:      opts.FinishTime,
 		Type:      observer.FINISH_SPAN,
 		Scope:     sp.ScopeID(),
 		Recovered: recovered,
@@ -103,17 +108,13 @@ func (sp *span) Tracer() apitrace.Tracer {
 	return sp.tracer
 }
 
-func (sp *span) AddEvent(ctx context.Context, event event.Event) {
-	observer.Record(observer.Event{
-		Type:       observer.ADD_EVENT,
-		String:     event.Message(),
-		Attributes: event.Attributes(),
-		Context:    ctx,
-	})
+func (sp *span) AddEvent(ctx context.Context, msg string, attrs ...core.KeyValue) {
+	sp.addEventWithTime(ctx, time.Time{}, msg, attrs...)
 }
 
-func (sp *span) Event(ctx context.Context, msg string, attrs ...core.KeyValue) {
+func (sp *span) addEventWithTime(ctx context.Context, timestamp time.Time, msg string, attrs ...core.KeyValue) {
 	observer.Record(observer.Event{
+		Time:       timestamp,
 		Type:       observer.ADD_EVENT,
 		String:     msg,
 		Attributes: attrs,