resource terminology and API (open-telemetry#56)

* resource terminology and API

* addressed code review comments

specification/README.md

@@ -5,4 +5,5 @@ describes the key types and the overall behavior.
 
 Main APIs:
 
-- [Tracing API](tracing-api.md).
+- [Tracing API](tracing-api.md).
+- [Resources API](resources-api.md).

specification/resources-api.md

@@ -0,0 +1,75 @@
+# Resources API
+
+[Resource](../terminology.md#resources) represents the entity producing
+telemetry. The primary purpose of resources as a first-class concept in the API
+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 creation of
+`Resources` and associating them with telemetry.
+
+When used with distributed tracing resource can be associated with the
+[Tracer](tracing-api.md#tracer) or individual
+[SpanData](tracing-api.md#spandata). 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 -
+`Resource` that is set on `Tracer` MUST be ignored.
+
+**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 
+
+## Resource creation
+
+API defines two ways to instantiate an instance of `Resource`. First, by
+providing a collection of labels - method [Create](#create). The typical use of
+this method is by creating resource from the list of labels taken from
+environment variables, metadata API call response, or other sources.
+
+Second, by merging two `Resource`s into a new one. The method [Merge](#merge) is
+used when a `Resource` is constructed from multiple sources - metadata API call
+for the host and environment variables for the container. So a single `Resource`
+will contain labels for both.
+
+Lastly, it is a good practice for API to allow easy creation of a default or
+empty `Resource`.
+
+Note that the OpenTelemetry project documents certain ["standard
+labels"](../semantic-conventions.md) that have prescribed semantic meanings.
+
+### Create
+
+Creates a new `Resource` out of the collection of labels. This is a static
+method.
+
+Required parameter:
+
+Collection of name/value labels where both name and value are strings.
+
+### Merge
+
+Creates a new `Resource` that is a combination of labels of two `Resource`s. For
+example, from two `Resource`s - one representing the host and one representing a
+container, resulting `Resource` will describe both.
+
+Already set labels MUST NOT be overwritten unless they are empty string. Label
+key namespacing SHOULD be used to prevent collisions across different resource
+detection steps.
+
+
+Required parameter:
+
+`Resource` to merge into the one, on which the method was called.
+
+## Resource operations
+
+API defines a resource class with a single getter for the list of labels
+associated with this resource. `Resource` object should be assumed immutable.
+
+### GetLabels
+
+Returns the read only collection of labels associated with this resource. Each
+label is a string to string name value pair. The order of labels in collection
+is not significant. The typical use of labels collection is enumeration so the
+fast access to the label value by it's key is not a requirement.

terminology.md

@@ -112,7 +112,22 @@ TODO: Describe tags terminology https://github.com/open-telemetry/opentelemetry-
 
 ## Resources
 
-TODO: Describe resources terminology https://github.com/open-telemetry/opentelemetry-specification/issues/47
+`Resource` captures information about the entity for which telemetry is
+recorded. For example, metrics exposed by a Kubernetes container can be linked
+to a resource that specifies the cluster, namespace, pod, and container name.
+
+`Resource` may capture an entire hierarchy of entity identification. It may
+describe the host in the cloud and specific container or an application running
+in the process.
+
+Note, that some of the process identification information can be associated with
+telemetry automatically by OpenTelemetry SDK or specific exporter. See
+OpenTelemetry
+[proto](https://github.com/open-telemetry/opentelemetry-proto/blob/a46c815aa5e85a52deb6cb35b8bc182fb3ca86a0/src/opentelemetry/proto/agent/common/v1/common.proto#L28-L96)
+for an example.
+
+**TODO**: Better describe the difference between the resource and a Node
+https://github.com/open-telemetry/opentelemetry-proto/issues/17
 
 ## Agent/Collector
 

work_in_progress/specification/resource/Resource.md

@@ -58,12 +58,6 @@ Auto-detection of resource information in specific environments, e.g. specific c
 vendors, MUST be implemented outside of the core libraries in third party or
 [census-ecosystem][census-ecosystem] repositories.
 
-### Merging
-As different mechanisms are run to gain information about a resource, their information
-has to be merged into a single resulting resource.
-Already set labels or type fields MUST NOT be overwritten unless they are empty string. Label key
-namespacing SHOULD be used to prevent collisions across different resource detection steps.
-
 ### Detectors
 To make auto-detection implementations easy to use, the core resource package SHOULD define
 an interface to retrieve resource information. Additionally, helper functionality MAY be