Move resource to SDK.

README.md

@@ -14,10 +14,11 @@ The OpenTelemetry specification describes the cross-language requirements and ex
 - API Specification
  - [DistributedContext](specification/api-distributedcontext.md)
  - [Propagators](specification/api-propagators.md)
- - [Resources](specification/api-resources.md)
  - [Tracing](specification/api-tracing.md)
  - [Sampling](specification/api-sampling.md)
  - [Metrics](specification/api-metrics.md)
+- SDK Specification
+ - [Resource](specification/sdk-resource.md)
 - Data Specification
  - [Semantic Conventions](specification/data-semantic-conventions.md)
  - [Protocol](specification/protocol.md)

specification/api-tracing.md

@@ -131,11 +131,6 @@ convenience methods to manage a `Span`'s lifetime and the scope in which a
 time) but stil active. A `Span` may be active on one thread after it has been
 made inactive on another.
 
-The `Tracer` MUST support recording `Span`s that were created _out of band_,
-i.e. not by the tracer itself. For this reason, implementations MUST NOT
-require that a `Span`'s start and end timestamps match the wall time when it is
-created, made active, or finished.
-
 The implementation MUST provide no-op binary and text `Propagator`s, which the
 `Tracer` SHOULD use by default if other propagators are not configured. SDKs
 SHOULD use the W3C HTTP Trace Context as the default text format. For more

specification/library-layout.md

@@ -1,33 +1,45 @@
 # OpenTelemetry Project Package Layout
-This documentation serves to document the "look and feel" of a basic layout for OpenTelemetry projects. This package layout is intentionally generic and it doesn't try to impose a language specific package structure.
+This documentation serves to document the "look and feel" of a basic layout for OpenTelemetry
+projects. This package layout is intentionally generic and it doesn't try to impose a language
+specific package structure.
 
 ## API Package
 Here is a proposed generic package structure for OpenTelemetry API package.
 
+A typical top-level directory layout:
+```
+api
+ ├── context
+ │ └── propagation
+ ├── metrics
+ ├── trace
+ │ └── propagation
+ ├── distributedcontext
+ │ └── propagation
+ ├── internal
+ └── logs
+```
+> Use of lowercase, CamelCase or Snake Case (stylized as snake_case) names depends on the language.
+
 ### `/context`
 
 This directory describes the API that provides in-process context propagation.
 
-### `/metrics`
+### [/metrics](api-metrics.md)
 
 This directory describes the Metrics API that can be used to record application metrics.
 
-### `/resources`
-
-This API for resource information population.
-
-The resource directory primarily defines a type [Resource](overview.md#resources) that captures information about the entity for which stats or traces are recorded. For example, metrics exposed by a Kubernetes container can be linked to a resource that specifies the cluster, namespace, pod, and container name.
-
-### `/distributedcontext`
+### [/distributedcontext](api-distributedcontext.md)
 
-This directory describes the DistributedContext API that can be used to manage context propagation and metrics-related labeling.
+This directory describes the DistributedContext API that can be used to manage context propagation
+and metrics-related labeling.
 
 This API consists of a few main classes:
 
 - `Entry` is used to label anything that is associated with a specific operation, such as an HTTP request.
 - An `Entry` consists of `EntryMetadata`, `EntryKey`, and `EntryValue`.
 
-### `/trace`
+### [/trace](api-tracing.md)
 
 This API consist of a few main classes:
 
@@ -41,18 +53,46 @@ Private application and library code.
 ### `/logs` (_In the future_)
 > TODO: logs operations
 
+## SDK Package
+Here is a proposed generic package structure for OpenTelemetry SDK package.
 
 A typical top-level directory layout:
 ```
-api
+sdk
  ├── context
- │ └── propagation
  ├── metrics
- ├── resources
+ ├── resource
  ├── trace
  ├── distributedcontext
- │ └── propagation
  ├── internal
  └── logs
 ```
 > Use of lowercase, CamelCase or Snake Case (stylized as snake_case) names depends on the language.
+
+### `/sdk/context`
+
+This directory describes the SDK implementation for api/context.
+
+### `/sdk/metrics`
+
+This directory describes the SDK implementation for api/metrics.
+
+### [/sdk/resource](sdk-resource.md)
+
+The resource directory primarily defines a type [Resource](overview.md#resources) that captures
+information about the entity for which stats or traces are recorded. For example, metrics exposed
+by a Kubernetes container can be linked to a resource that specifies the cluster, namespace, pod,
+and container name.
+
+### `/sdk/distributedcontext`
+
+
+### [/sdk/trace](sdk-tracing.md)
+
+This directory describes the SDK implementation for api/metrics.
+
+### `/sdk/internal` (_Optional_)
+Private application and library code.
+
+### `/sdk/logs` (_In the future_)
+> TODO: logs operations

specification/api-resources.md → specification/sdk-resource.md

@@ -1,4 +1,4 @@
-# Resources API
+# 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
@@ -8,47 +8,42 @@ 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). When associated with `Tracer`, all `Span`s
-produced by this `Tracer` will automatically be associated with this `Resource`.
-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.
+[TracerSdk](sdk-tracing.md#tracer-sdk). When associated with `TracerSdk`, all
+`Span`s produced by the `Tracer`, that is implemented by this `TracerSdk`, will
+automatically be associated with this `Resource`.
 
-**TODO**: explain how resource is associated with metrics.
-
-## Resources SDK
-
-TODO: notes how Resources API is extended when using `SDK`. https://github.com/open-telemetry/opentelemetry-specification/issues/61 
+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`.
 
 ## Resource creation
 
-The API interface must support two ways to instantiate new resources. Those
-are:
+The API interface must support two ways to instantiate new resources. Those are:
 
 ### Create
 
-The interface MUST provide a way to create a new resource, from a collection 
-of labels. Examples include a factory method or a constructor for 
-a resource object. A factory method is recommended to enable support for 
-cached objects.
+The interface MUST provide a way to create a new resource, from a collection of
+labels. Examples include a factory method or a constructor for a resource
+object. A factory method is recommended to enable support for cached objects.
 
 Required parameters:
 
 - a collection of name/value labels, where name and value are both strings.
 
 ### Merge
 
-The interface MUST provide a way for a primary resource to merge with a 
-secondary resource, resulting in the creation of a brand new resource. The 
+The interface MUST provide a way for a primary resource to merge with a
+secondary resource, resulting in the creation of a brand new resource. The
 original resources should be unmodified.
 
 This is utilized for merging of resources whose labels come from different
-sources, such as environment variables, or metadata extracted from the host or 
+sources, such as environment variables, or metadata extracted from the host or
 container.
 
-Already set labels MUST NOT be overwritten unless they are the empty string. 
+Already set labels MUST NOT be overwritten unless they are the empty string.
 
-Label key namespacing SHOULD be used to prevent collisions across different 
+Label key namespacing SHOULD be used to prevent collisions across different
 resource detection steps.
 
 Required parameters:
@@ -58,7 +53,7 @@ Required parameters:
 
 ### The empty resource
 
-It is recommended, but not required, to provide a way to quickly create an empty 
+It is recommended, but not required, to provide a way to quickly create an empty
 resource.
 
 Note that the OpenTelemetry project documents certain ["standard
@@ -71,12 +66,12 @@ In addition to resource creation, the following operations should be provided:
 ### Retrieve labels
 
 The API should provide a way to retrieve a read only collection of labels
-associated with a resource. The labels should consist of the name and values, 
+associated with a resource. The labels should consist of the name and values,
 both of which should be strings.
 
 There is no need to guarantee the order of the labels.
 
-The most common operation when retrieving labels is to enumerate over them.
-As such, it is recommended to optimize the resulting collection for fast 
-enumeration over other considerations such as a way to quickly retrieve a
-value for a label with a specific key.
+The most common operation when retrieving labels is to enumerate over them. As
+such, it is recommended to optimize the resulting collection for fast
+enumeration over other considerations such as a way to quickly retrieve a value
+for a label with a specific key.