Merge branch 'remove-binary-format' of github.com:MikeGoldsmith/opent…

…elemetry-specification into remove-binary-format

* 'remove-binary-format' of github.com:MikeGoldsmith/opentelemetry-specification:
  update Resource spec based on the move to the SDK and named tracers (open-telemetry#421)
  sdk-tracer: replace Factory with Provider (open-telemetry#422)
  Add details for determining the parent Span from a Context (open-telemetry#423)

specification/api-tracing.md

@@ -19,6 +19,7 @@ Table of Contents
 * [SpanContext](#spancontext)
 * [Span](#span)
   * [Span creation](#span-creation)
+    * [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context)
     * [Add Links](#add-links)
   * [Span operations](#span-operations)
     * [Get Context](#get-context)
@@ -255,9 +256,11 @@ as a separate operation.
 The API MUST accept the following parameters:
 
 - The span name. This is a required parameter.
-- The parent Span or parent Span context, and whether the new `Span` should be a
-  root `Span`. API MAY also have an option for implicit parent context
-  extraction from the current context as a default behavior.
+- The parent `Span` or a `Context` containing a parent `Span` or `SpanContext`,
+  and whether the new `Span` should be a root `Span`. API MAY also have an
+  option for implicit parenting from the current context as a default behavior.
+  See [Determining the Parent Span from a Context](#determining-the-parent-span-from-a-context)
+  for guidance on `Span` parenting from explicit and implicit `Context`s.
 - [`SpanKind`](#spankind), default to `SpanKind.Internal` if not specified.
 - `Attribute`s - A collection of key-value pairs, with the same semantics as
   the ones settable with [Span::SetAttributes](#set-attributes). Additionally,
@@ -288,6 +291,21 @@ created in another process. Each propagators' deserialization must set
 `IsRemote` to true on a parent `SpanContext` so `Span` creation knows if the
 parent is remote.
 
+#### Determining the Parent Span from a Context
+
+When a new `Span` is created from a `Context`, the `Context` may contain:
+
+- A current `Span`
+- An extracted `SpanContext`
+- A current `Span` and an extracted `SpanContext`
+- Neither a current `Span` nor an extracted `Span` context
+
+The parent should be selected in the following order of precedence:
+
+- Use the current `Span`, if available.
+- Use the extracted `SpanContext`, if available.
+- There is no parent. Create a root `Span`.
+
 #### Add Links
 
 During the `Span` creation user MUST have the ability to record links to other `Span`s. Linked

specification/sdk-resource.md

@@ -1,25 +1,30 @@
 # Resource SDK
 
-A [Resource](overview.md#resources) represents the entity producing telemetry.
-The primary purpose of resources as a first-class concept in the API is
+A [Resource](overview.md#resources) represents the entity producing
+telemetry. For example, a process producing telemetry that is running in a
+container on Kubernetes has a Pod name, it is in a namespace and possibly is
+part of a Deployment which also has a name. All three of these attributes can be
+included in the `Resource`.
+
+The primary purpose of resources as a first-class concept in the SDK is
 decoupling of discovery of resource information from exporters. This allows for
 independent development and easy customization for users that need to integrate
-with closed source environments. API MUST allow for creation of `Resources` and
+with closed source environments. The SDK MUST allow for creation of `Resources` and
 for associating them with telemetry.
 
 When used with distributed tracing, a resource can be associated with the
-[TracerSdk](sdk-tracing.md#tracer-sdk). When associated with `TracerSdk`, all
-`Span`s produced by the `Tracer`, that is implemented by this `TracerSdk`, will
+[TracerProvider](sdk-tracing.md#tracer-sdk). When associated with a
+`TracerProvider`, all `Span`s produced by any `Tracer` from the provider will
 automatically be associated with this `Resource`.
 
 When used with metrics, a resource can be associated with the
-[MeterSdk](sdk-metrics.md#meter-sdk). When associated with `MeterSdk`, all
-`Metrics` produced by this `Meter`, that is implemented by this `MeterSdk`, will
-automatically be associated with this `Resource`.
+[MeterProvider](sdk-metrics.md#meter-sdk). When associated with a `MeterProvider`,
+all `Metrics` produced by any `Meter` from the provider will automatically be
+associated with this `Resource`.
 
 ## Resource creation
 
-The API interface must support two ways to instantiate new resources. Those are:
+The SDK must support two ways to instantiate new resources. Those are:
 
 ### Create
 
@@ -66,7 +71,7 @@ In addition to resource creation, the following operations should be provided:
 
 ### Retrieve attributes
 
-The API should provide a way to retrieve a read only collection of attributes
+The SDK should provide a way to retrieve a read only collection of attributes
 associated with a resource. The attributes should consist of the name and values,
 both of which should be strings.
 

specification/sdk-tracing.md

@@ -127,14 +127,15 @@ of the `TraceID`.
 
 ## Tracer Creation
 
-New `Tracer` instances are always created through a `TracerFactory` (see [API](api-tracing.md#obtaining-a-tracer)).
-The `name` and `version` arguments supplied to the `TracerFactory` must be used
-to create a `Resource` instance which is stored on the created `Tracer`.
+New `Tracer` instances are always created through a `TracerProvider` (see
+[API](api-tracing.md#obtaining-a-tracer)).  The `name` and `version` arguments
+supplied to the `TracerProvider` must be used to create a
+[`Resource`](sdk-resource.md) instance which is stored on the created `Tracer`.
 
 All configuration objects (SDK specific) and extension points (span processors,
-propagators) must be provided to the `TracerFactory`. `Tracer` instances must
+propagators) must be provided to the `TracerProvider`. `Tracer` instances must
 not duplicate this data (unless for read-only access) to avoid that different
-`Tracer` instances of a `TracerFactory` have different versions of these data.
+`Tracer` instances of a `TracerProvider` have different versions of these data.
 
 The readable representations of all `Span` instances created by a `Tracer` must
 provide a `getLibraryResource` method that returns this `Resource` information
@@ -149,20 +150,20 @@ invocations. The span processors are invoked only when
 Built-in span processors are responsible for batching and conversion of spans to
 exportable representation and passing batches to exporters.
 
-Span processors can be registered directly on SDK `TracerFactory` and they are
+Span processors can be registered directly on SDK `TracerProvider` and they are
 invoked in the same order as they were registered.
 
-All `Tracer` instances created by a `TracerFactory` share the same span processors.
+All `Tracer` instances created by a `TracerProvider` share the same span processors.
 Changes to this collection reflect in all `Tracer` instances.
 Implementation-wise, this could mean that `Tracer` instances have a reference to
-their `TracerFactory` and can access span processor objects only via this
+their `TracerProvider` and can access span processor objects only via this
 reference.
 
-Manipulation of the span processors collection must only happen on `TracerFactory`
+Manipulation of the span processors collection must only happen on `TracerProvider`
 instances. This means methods like `addSpanProcessor` must be implemented on
-`TracerFactory`.
+`TracerProvider`.
 
-Each processor registered on `TracerFactory` is a start of pipeline that consist
+Each processor registered on `TracerProvider` is a start of pipeline that consist
 of span processor and optional exporter. SDK MUST allow to end each pipeline with
 individual exporter.