Trace SDK: Provide definitions for readable and read/write span.

CHANGELOG.md

@@ -15,6 +15,8 @@ Updates:
 
 - Add semantic convention for NGINX custom HTTP 499 status code.
 - Adapt semantic conventions for the span name of messaging systems ([#690](https://github.com/open-telemetry/opentelemetry-specification/pull/690))
+- Provide clear definitions for readable and read/write span interfaces in the SDK ([#669](https://github.com/open-telemetry/opentelemetry-specification/pull/669))
+ * SpanProcessors must provide read/write access at least in OnStart.
 - Specify how `Probability` sampler is used with `ParentOrElse` sampler.
 - Clean up api-propagators.md, by extending documentation and removing redundant sections ([#577](https://github.com/open-telemetry/opentelemetry-specification/pull/577))
 

specification/trace/sdk.md

@@ -6,6 +6,7 @@
 
 * [Sampling](#sampling)
 * [Tracer Creation](#tracer-creation)
+* [Additional Span Interfaces](#additional-span-interfaces)
 * [Span Processor](#span-processor)
 * [Span Exporter](#span-exporter)
 
@@ -152,9 +153,36 @@ Note: Implementation-wise, this could mean that `Tracer` instances have a
 reference to their `TracerProvider` and access configuration only via this
 reference.
 
-The readable representations of all `Span` instances created by a `Tracer` must
-provide a `getInstrumentationLibrary` method that returns the
-`InstrumentationLibrary` information held by the `Tracer`.
+## Additional Span Interfaces
+
+The [API-level definition for Span's interface](api.md#span-operations)
+only defines write-only access to the span.
+This is good because instrumentations and applications are not meant to use the data
+stored in a span for application logic.
+However, the SDK needs to eventually read back the data in some locations.
+Thus, the SDK specification defines two new terms:
+
+* **Readable span**: A span interface satisfies the requirements of being a
+ readable span if it allows to retrieve all information
+ that was added to the span (e.g. all attributes, events, (parent) `SpanContext`,
+ etc.).
+
+ A readable span interface MUST provide a method called `getInstrumentationLibrary` (or similar),
+ that returns the `InstrumentationLibrary` information held by the `Tracer` that created the span.
+* **Read/write span**: A span interface satisfies this requirement of being a
+ read/write span if it provides both the full span API as defined in the
+ [API-level definition for span's interface](api.md#span-operations) and
+ additionally satisfies the requirements for being a readable span
+ as defined in the above bullet point.
+
+Note: First, these requirements use "interface" in the most abstract sense --
+it does not need to be an actual Java `interface` for example but could also be
+a `final` POJO. Second, these are abstract requirements for interfaces. Not all
+places in the spec that talk about a readable span need to be implemented by the
+same concrete interface. For example, this allows using a different interface
+for the readable span passed to an exporter than for the readable span passed
+to a SpanProcessor's OnEnd. On the other hand,
+it allows implementing a readable span as a read/write span.
 
 ## Span processor
 
@@ -203,18 +231,21 @@ exceptions.
 
 **Parameters:**
 
-* `Span` - a readable span object.
+* `Span` - a [read/write span object](#additional-span-interfaces) for the started span.
 
 **Returns:** `Void`
 
 #### OnEnd(Span)
 
-`OnEnd` is called when a span is ended. This method is called synchronously on
-the execution thread, therefore it should not block or throw an exception.
+`OnEnd` is called after a span is ended (i.e., the end timestamp is already set).
+This method MUST be called synchronously within the [`Span.End()` API](api.md#end),
+therefore it should not block or throw an exception.
 
 **Parameters:**
 
-* `Span` - a readable span object.
+* `Span` - a [readable span object](#additional-span-interfaces) for the ended span.
+ Note: Even if the passed Span may be technically writable,
+ since it's already ended at this point, modifying it is not allowed.
 
 **Returns:** `Void`
 
@@ -290,7 +321,8 @@ interfaces, one that accepts spans (SpanExporter) and one that accepts metrics
 
 #### `Export(batch)`
 
-Exports a batch of telemetry data. Protocol exporters that will implement this
+Exports a batch of [readable spans](#additional-span-interfaces).
+Protocol exporters that will implement this
 function are typically expected to serialize and transmit the data to the
 destination.
 
@@ -307,15 +339,9 @@ and backend the spans are being sent to.
 
 **Parameters:**
 
-batch - a batch of telemetry data. The exact data type of the batch is language
-specific, typically it is a list of telemetry items, e.g. for spans in Java it
-will be typically `Collection<ExportableSpan>`.
-
-Note that the data type for a span for illustration purposes here is written as
-an imaginary type ExportableSpan (similarly for metrics it would be e.g.
-ExportableMetrics). The actual data type must be specified by language library
-authors, it should be able to represent the span data that can be read by the
-exporter.
+batch - a batch of [readable spans](#additional-span-interfaces). The exact data type of the batch is language
+specific, typically it is some kind of list,
+e.g. for spans in Java it will be typically `Collection<SpanData>`.
 
 **Returns:** ExportResult: