Remove SpanData (open-telemetry#215)

bg451 · yurishkuro · commit 10135f89ed38 · 2019-09-13T16:10:24.000-04:00
* Removes references of spandata Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * initial stab at tracing spec Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * adds link and event timestamp Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * re-add whitespace to reduce diff size Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * typo fix Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * Adds OutOfBand flag to span options Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * specification/api-distributedcontext: fix typo (open-telemetry#236) contest -> context Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * Adds comment+link to Remove Out Of Band Support RFC Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * remove comment in doc Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * Remove work_in_progress dir (open-telemetry#225) Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * Move start timestamp above the possibly removed fields Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * Fix typo in FailedNotRetryable (open-telemetry#243) Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * Rename TraceOptions to TraceFlags to be w3c compatible (open-telemetry#234) * Rename TraceOptions to TraceFlags to be w3c compatible Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com> * Fix more TraceOptions and rename recorded with sampled Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com> Signed-off-by: Brandon Gonzalez <bg@lightstep.com> * Respond to comment
diff --git a/specification/api-resources.md b/specification/api-resources.md
@@ -8,10 +8,9 @@ with closed source environments. API MUST allow for creation of `Resources` and
 for associating them with telemetry.
 
 When used with distributed tracing, a resource can be associated with the
-[Tracer](api-tracing.md#tracer) or individual
-[SpanData](api-tracing.md#spandata). When associated with `Tracer`, all `Span`s
+[Tracer](api-tracing.md#tracer). When associated with `Tracer`, all `Span`s
 produced by this `Tracer` will automatically be associated with this `Resource`.
-When associated with the `SpanData` explicitly for out-of-band spans -
+When associated with a `Span` explicitly for out-of-band spans -
 `Resource` that is set on `Tracer` MUST be ignored. Note, that association of
 `Tracer` with the `Resource` will be done in SDK, not as API call.
 
diff --git a/specification/api-tracing.md b/specification/api-tracing.md
@@ -15,7 +15,6 @@ Table of Contents
     * [GetCurrentSpan](#getcurrentspan)
     * [WithSpan](#withspan)
     * [SpanBuilder](#spanbuilder)
-    * [RecordSpanData](#recordspandata)
     * [GetBinaryFormat](#getbinaryformat)
     * [GetHttpTextFormat](#gethttptextformat)
 * [SpanContext](#spancontext)
@@ -37,20 +36,6 @@ Table of Contents
   * [GetCanonicalCode](#getcanonicalcode)
   * [GetDescription](#getdescription)
   * [GetIsOk](#getisok)
-* [SpanData](#spandata)
-  * [Constructing SpanData](#constructing-spandata)
-  * [Getters](#getters)
-    * [GetName](#getname)
-    * [GetKind](#getkind)
-    * [GetStartTimestamp](#getstarttimestamp)
-    * [GetEndTimestamp](#getendtimestamp)
-    * [GetContext](#getcontext)
-    * [GetParentSpanId](#getparentspanid)
-    * [GetResource](#getresource)
-    * [GetAttributes](#getattributes)
-    * [GetTimedEvents](#gettimedevents)
-    * [GetLinks](#getlinks)
-    * [GetStatus](#getstatus)
 
 </details>
 
@@ -59,8 +44,6 @@ Tracing API consist of a few main classes:
 - `Tracer` is used for all operations. See [Tracer](#tracer) section.
 - `Span` is a mutable object storing information about the current operation
    execution. See [Span](#span) section.
-- `SpanData` is an immutable object that is used to report out-of-band completed
-  spans. See [SpanData](#spandata) section.
 
 ## Data types
 While languages and platforms have different ways of representing data,
@@ -240,6 +223,14 @@ empty by default:
 - `Attribute`s
 - `Link`s
 - `Event`s
+- `Start timestamp`
+
+N.B.: There is an active RFC to remove [out of band span reporting](https://github.com/open-telemetry/oteps/pull/26)
+so the following items below may be removed soon.
+
+- `Resource`
+- `SpanID`
+- `OutOfBand` to specify the span originated from out of band
 
 Each span has zero or one parent span and zero or more child spans, which
 represent causally related operations. A tree of related spans comprises a
@@ -304,6 +295,7 @@ with the moment when they are added to the `Span`.
 An `Event` is defined by the following properties:
 - (Required) Name of the event.
 - (Optional) One or more `Attribute`.
+- (Optional) Timestamp for the event.
 
 The `Event` SHOULD be an immutable type.
 
@@ -375,7 +367,8 @@ with the `Span`).
 Call to `End` of a `Span` MUST not have any effects on child spans. Those may
 still be running and can be ended later.
 
-There MUST be no parameter.
+Parameters:
+- (Optional) Timestamp to explicitly set the end timestamp
 
 This API MUST be non-blocking.
 
@@ -388,8 +381,7 @@ timestamps to the Span object:
 - The end time needs to be recorded when the operation is ended.
 
 Start and end time as well as Event's timestamps MUST be recorded at a time of a
-calling of corresponding API and MUST not be passed as an argument. In order to
-record already completed span - [`SpanData`](#spandata) API HAVE TO be used.
+calling of corresponding API.
 
 ## Status
 
@@ -473,93 +465,3 @@ Returns the description of this `Status`.
 ### GetIsOk
 
 Returns false if this `Status` represents an error, else returns true.
-
-## SpanData
-
-`SpanData` is an immutable and final class. All getters of `SpanData` are thread
-safe and can be called any number of times.
-
-`API` MUST provide a way of [constructing `SpanData`](#constructing-spandata)
-that can be recorded using `Tracer` method `RecordSpanData`.
-
-### Constructing SpanData
-
-`SpanData` is an immutable object that can be constructed using the following
-arguments:
-
-- `SpanContext` identifying this `SpanData`.
-- Parent's `SpanId`. All-zeroes `SpanId` or `null` MUST be assumed and
-  interchangeable if `SpanData` has no parent.
-- `Resource` this SpanData is recorded for. If not specified - `Tracer`'s
-  `Resource` will be used instead when the `RecordSpanData` called on the
-  `Tracer`.
-- Name of this `SpanData`.
-- `Kind` of this `SpanData`. `SpanKind.Internal` MUST be assumed as a default.
-- Start and End timestamps.
-- Set of attributes with the string key and the value, which must be either a
-  string, a boolean value, or a numeric type.
-- Set of `Events`.
-- Set of `Links`.
-- `Status` of `SpanData` execution.
-
-All collections passes as an argument MUST be either immutable if language
-allows it or copied so the change of the collection will not mutate the
-`SpanData`.
-
-### Getters
-
-Getters will be called by exporters in SDK. Implementation MUST not assume that
-getters will be called only once or at all. There also MUST be no expectations
-on how soon getters will be called after object creation.
-
-#### GetName
-
-Returns the name of this `SpanData`.
-
-#### GetKind
-
-Returns the `SpanKind` of this `SpanData`.
-
-#### GetStartTimestamp
-
-Returns the start timestamp of this `SpanData`.
-
-#### GetEndTimestamp
-
-Returns the end timestamp of this `SpanData`.
-
-#### GetContext
-
-Returns the `SpanContext` associated with this `SpanData`.
-
-#### GetParentSpanId
-
-Returns the `SpanId` of the parent of this `SpanData`.
-
-#### GetResource
-
-Returns the `Resource` associated with this `SpanData`. When `null` is returned
-the assumption is that `Resource` will be taken from the `Tracer` that is used
-to record this `SpanData`.
-
-#### GetAttributes
-
-Returns the `Attributes` collection associated with this `SpanData`. The order
-of attributes in collection is not significant. The typical use of attributes
-collection is enumeration so the fast access to the label value by it's key is
-not a requirement. This collection MUST be immutable.
-
-#### GetTimedEvents
-
-Return the collection of `Events` with the timestamps associated with this
-`SpanData`. The order of events in collection is not guaranteed. This collection
-MUST be immutable.
-
-#### GetLinks
-
-Returns the `Links` collection associated with this `SpanData`. The order of
-links in collection is not significant. This collection MUST be immutable.
-
-#### GetStatus
-
-Returns the `Status` of this `SpanData`.
diff --git a/specification/concurrency.md b/specification/concurrency.md
@@ -3,21 +3,19 @@
 For languages which support concurrent execution the OpenTelemetry APIs provide
 specific guarantees and safeties. Not all of API functions are safe to
 be called concurrently. Function and method documentation must explicitly
-specify whether it is safe or no to make concurrent calls and in what 
+specify whether it is safe or no to make concurrent calls and in what
 situations.
 
 The following are general recommendations of concurrent call safety of
 specific subsets of the API.
 
 **Tracer** - all methods are safe to be called concurrently.
 
-**SpanBuilder** - It is not safe to concurrently call any methods of the 
-same SpanBuilder instance. Different instances of SpanBuilder can be safely 
+**SpanBuilder** - It is not safe to concurrently call any methods of the
+same SpanBuilder instance. Different instances of SpanBuilder can be safely
 used concurrently by different threads/coroutines, provided that no single
 SpanBuilder is used by more than one thread/coroutine.
 
-**Span** - All methods of Span are safe to be called concurrently. 
-
-**SpanData** - SpanData is immutable and is safe to be used concurrently.
+**Span** - All methods of Span are safe to be called concurrently.
 
 **Link** - same as SpanData.
diff --git a/specification/library-layout.md b/specification/library-layout.md
@@ -34,8 +34,6 @@ This API consist of a few main classes:
 - `Tracer` is used for all operations. See [Tracer](api-tracing.md#tracer) section.
 - `Span` is a mutable object storing information about the current operation
    execution. See [Span](api-tracing.md#span) section.
-- `SpanData` is an immutable object that is used to report out-of-band completed
-  spans. See [SpanData](api-tracing.md#spandata) section.
 
 ### `/internal` (_Optional_)
 Private application and library code.
