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.

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) {
+}