move span, trace and event implementation to sdk. (#27)

* move event to sdk.

* move trace and span implementation to sdk.
- also added noop implementation of span and trace.

* fix review comments.

Author: rghetia

api/event/event.go

@@ -15,17 +15,10 @@
 package event
 
 import (
-	"fmt"
-
 	"github.com/open-telemetry/opentelemetry-go/api/core"
 )
 
 type (
-	event struct {
-		message    string
-		attributes []core.KeyValue
-	}
-
 	// Event interface provides methods to retrieve Event properties.
 	Event interface {
 
@@ -36,24 +29,3 @@ type (
 		Attributes() []core.KeyValue
 	}
 )
-
-var _ Event = (*event)(nil)
-
-// WithAttr creates an Event with Attributes and a message.
-// Attributes are immutable.
-func WithAttr(msg string, attributes ...core.KeyValue) Event {
-	return event{message: msg, attributes: attributes}
-}
-
-// WithString creates an Event with formatted string.
-func WithString(f string, args ...interface{}) Event {
-	return event{message: fmt.Sprint(f, args), attributes: nil}
-}
-
-func (e event) Message() string {
-	return e.message
-}
-
-func (e event) Attributes() []core.KeyValue {
-	return append(e.attributes[:0:0], e.attributes...)
-}

api/trace/api.go

@@ -16,6 +16,7 @@ package trace
 
 import (
 	"context"
+	"sync/atomic"
 	"time"
 
 	"google.golang.org/grpc/codes"
@@ -31,14 +32,21 @@ type (
 	Tracer interface {
 		Start(context.Context, string, ...SpanOption) (context.Context, Span)
 
+		// WithSpan wraps the execution of the function body with a span.
+		// It starts a new span and sets it as an active span in the context.
+		// It then executes the body. It closes the span before returning the execution result.
+		// TODO: Should it restore the previous span?
 		WithSpan(
 			ctx context.Context,
 			operation string,
 			body func(ctx context.Context) error,
 		) error
 
+		// TODO: Do we need WithService and WithComponent?
 		WithService(name string) Tracer
 		WithComponent(name string) Tracer
+
+		// WithResources attaches resource attributes to the Tracer.
 		WithResources(res ...core.KeyValue) Tracer
 
 		// Note: see https://github.com/opentracing/opentracing-go/issues/127
@@ -53,39 +61,50 @@ type (
 
 		stats.Interface
 
-		SetError(bool)
-
+		// 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()
 
 		// AddEvent adds an event to the span.
 		AddEvent(ctx context.Context, event event.Event)
 
-		// IsRecordingEvents returns true is the span is active and recording events is enabled.
+		// IsRecordingEvents returns true if the span is active and recording events is enabled.
 		IsRecordingEvents() bool
 
 		// SpancContext returns span context of the span. Return SpanContext is usable
 		// even after the span is finished.
 		SpanContext() core.SpanContext
 
+		// SetStatus sets the status of the span. The status of the span can be updated
+		// even after span is finished.
 		SetStatus(codes.Code)
 	}
 
 	Injector interface {
+		// Inject serializes span context and tag.Map and inserts them in to
+		// carrier associated with the injector. For example in case of http request,
+		// span context could added to the request (carrier) as W3C Trace context header.
 		Inject(core.SpanContext, tag.Map)
 	}
 
 	// SpanOption apply changes to SpanOptions.
 	SpanOption func(*SpanOptions)
 
+	// SpanOptions provides options to set properties of span at the time of starting
+	// a new span.
 	SpanOptions struct {
-		attributes  []core.KeyValue
-		startTime   time.Time
-		reference   Reference
-		recordEvent bool
+		Attributes  []core.KeyValue
+		StartTime   time.Time
+		Reference   Reference
+		RecordEvent bool
 	}
 
+	// Reference is used to establish relationship between newly created span and the
+	// other span. The other span could be related as a parent or linked or any other
+	// future relationship type.
 	Reference struct {
 		core.SpanContext
 		RelationshipType
@@ -94,39 +113,49 @@ type (
 	RelationshipType int
 )
 
+var (
+	// The process global tracer could have process-wide resource
+	// tags applied directly, or we can have a SetGlobal tracer to
+	// install a default tracer w/ resources.
+	global atomic.Value
+
+	// TODO: create NOOP Tracer and register it instead of creating empty tracer here.
+	nt = &noopTracer{}
+)
+
 const (
 	ChildOfRelationship RelationshipType = iota
 	FollowsFromRelationship
 )
 
+// GlobalTracer return tracer registered with global registry.
+// If no tracer is registered then an instance of noop Tracer is returned.
 func GlobalTracer() Tracer {
 	if t := global.Load(); t != nil {
 		return t.(Tracer)
 	}
-	return empty
+	return nt
 }
 
+// SetGlobalTracer sets provided tracer as a global tracer.
 func SetGlobalTracer(t Tracer) {
 	global.Store(t)
 }
 
+// Start starts a new span using registered global tracer.
 func Start(ctx context.Context, name string, opts ...SpanOption) (context.Context, Span) {
 	return GlobalTracer().Start(ctx, name, opts...)
 }
 
+// Active returns current span from the context.
 func Active(ctx context.Context) Span {
-	span, _ := scope.Active(ctx).(*span)
+	span, _ := scope.Active(ctx).(Span)
 	return span
 }
 
-func WithSpan(ctx context.Context, name string, body func(context.Context) error) error {
-	return GlobalTracer().WithSpan(ctx, name, body)
-}
-
-func SetError(ctx context.Context, v bool) {
-	Active(ctx).SetError(v)
-}
-
+// Inject is convenient function to inject current span context using injector.
+// Injector is expected to serialize span context and inject it in to a carrier.
+// An example of a carrier is http request.
 func Inject(ctx context.Context, injector Injector) {
 	span := Active(ctx)
 	if span == nil {
@@ -136,36 +165,46 @@ func Inject(ctx context.Context, injector Injector) {
 	span.Tracer().Inject(ctx, span, injector)
 }
 
+// WithStartTime sets the start time of the span to provided time t, when it is started.
+// In absensce 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
+		o.StartTime = t
 	}
 }
 
+// WithAttributes sets attributes to span. These attributes provides additional
+// data about the span.
 func WithAttributes(attrs ...core.KeyValue) SpanOption {
 	return func(o *SpanOptions) {
-		o.attributes = attrs
+		o.Attributes = attrs
 	}
 }
 
+// WithRecordEvents enables recording of the events while the span is active.
+// In the absence of this option, RecordEvent is set to false, disabling any recording of
+// the events.
 func WithRecordEvents() SpanOption {
 	return func(o *SpanOptions) {
-		o.recordEvent = true
+		o.RecordEvent = true
 	}
 }
 
+// ChildOf. TODO: do we need this?.
 func ChildOf(sc core.SpanContext) SpanOption {
 	return func(o *SpanOptions) {
-		o.reference = Reference{
+		o.Reference = Reference{
 			SpanContext:      sc,
 			RelationshipType: ChildOfRelationship,
 		}
 	}
 }
 
+// FollowsFrom. TODO: do we need this?.
 func FollowsFrom(sc core.SpanContext) SpanOption {
 	return func(o *SpanOptions) {
-		o.reference = Reference{
+		o.Reference = Reference{
 			SpanContext:      sc,
 			RelationshipType: FollowsFromRelationship,
 		}

api/trace/noop_span.go

@@ -0,0 +1,93 @@
+// 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 trace
+
+import (
+	"context"
+
+	"google.golang.org/grpc/codes"
+
+	"github.com/open-telemetry/opentelemetry-go/api/core"
+	"github.com/open-telemetry/opentelemetry-go/api/event"
+)
+
+var _ Span = (*noopSpan)(nil)
+
+// SpancContext returns an invalid span context.
+func (sp *noopSpan) SpanContext() core.SpanContext {
+	return core.INVALID_SPAN_CONTEXT
+}
+
+// IsRecordingEvents always returns false for noopSpan.
+func (sp *noopSpan) IsRecordingEvents() bool {
+	return false
+}
+
+// SetStatus does nothing.
+func (sp *noopSpan) SetStatus(status codes.Code) {
+	return
+}
+
+// ScopeID returns and empty ScopeID.
+func (sp *noopSpan) ScopeID() core.ScopeID {
+	return core.ScopeID{}
+}
+
+// SetError does nothing.
+func (sp *noopSpan) SetError(v bool) {
+	return
+}
+
+// SetAttribute does nothing.
+func (sp *noopSpan) SetAttribute(attribute core.KeyValue) {
+	return
+}
+
+// SetAttributes does nothing.
+func (sp *noopSpan) SetAttributes(attributes ...core.KeyValue) {
+	return
+}
+
+// ModifyAttribute does nothing.
+func (sp *noopSpan) ModifyAttribute(mutator core.Mutator) {
+	return
+}
+
+// ModifyAttributes does nothing.
+func (sp *noopSpan) ModifyAttributes(mutators ...core.Mutator) {
+	return
+}
+
+// Finish does nothing.
+func (sp *noopSpan) Finish() {
+	return
+}
+
+// Tracer returns noop implementation of Tracer.
+func (sp *noopSpan) Tracer() Tracer {
+	return t
+}
+
+// AddEvent does nothing.
+func (sp *noopSpan) AddEvent(ctx context.Context, event event.Event) {
+}
+
+// Record does nothing.
+func (sp *noopSpan) Record(ctx context.Context, m ...core.Measurement) {
+}
+
+// RecordSingle does nothing.
+func (sp *noopSpan) RecordSingle(ctx context.Context, m core.Measurement) {
+}