Add a list of standard supported resources. (#235)

* Add a list of standard supported resources.

* Refactor the standard resources to be more generic.

* Fix typo.

* Fix comments, add links to merge.

* Add a todo about optional vs required.

* Remove host.ip.

* Add examples, remove data-center.

* Fix zone vs availability zone.

* Update resource keys schema, respond to comments.

Author: Bogdan Drutu

resource/Resource.md

@@ -1,6 +1,6 @@
 # Resource API Overview
 The resource library primarily defines a type that captures information about the entity
-for which stats or traces are reported. It further provides a framework for detection of
+for which metrics or traces are reported. It further provides a framework for detection of
 resource information from the environment and progressive population as signals propagate
 from the core instrumentation library to a backend's exporter.
 
@@ -12,8 +12,8 @@ about the entity.
 
 Type, label keys, and label values MUST contain only printable ASCII (codes between 32
 and 126, inclusive) and not exceed 256 characters.
-Type and label keys MUST have a length greater than zero. They SHOULD start with a domain
-name and separate hierarchies with `/` characters, e.g. `k8s.io/namespace/name`.
+Type and label keys MUST have a length greater than zero. Label keys SHOULD start with the type
+and separate hierarchies with `.` characters, e.g. `k8s.namespace.name`.
 
 Implementations MAY define a `Resource` data type, constructed from the parameters above.
 `Resource` MUST have getters for retrieving all the information used in `Resource` definition.
@@ -26,7 +26,7 @@ type Resource {
 }
 ```
 
-TODO(fabxc): link protobuf definition.
+For the proto definition see [here][resource-proto-link]
 
 ## Populating resources
 Resource information MAY be populated at any point between startup of the instrumented
@@ -47,8 +47,8 @@ Two environment variables are used:
 (`[ <key>="value" [ ,<key>="<value>" ... ] ]`). `"` characters in values MUST be escaped with `\`.
 
 For example:
-* `OC_RESOURCE_TYPE=k8s.io/container`
-* `OC_RESOURCE_LABELS=k8s.io/pod/name="pod-xyz-123",k8s.io/container/name="c1",k8s.io/namespace/name="default"`
+* `OC_RESOURCE_TYPE=container`
+* `OC_RESOURCE_LABELS=container.name="c1",k8s.pod.name="pod-xyz-123",k8s.namespace.name="default"`
 
 Population from environment variables MUST be the first applied detection process unless
 the user explicitly overwrites this behavior.
@@ -98,17 +98,17 @@ For example, from a resource object
 
 ```javascript
 {
-	"type": "k8s.io/container",
+	"type": "container",
 	"labels": {
 		// Populated from VM environment through auto-detection library.
-		"cloud.google.com/gce/instance_id": "instance1",
-		"cloud.google.com/zone": "eu-west2-a",
-		"cloud.google.com/project_id": "project1",
-		"cloud.google.com/gce/attributes/cluster_name": "cluster1",
+		"host.id": "instance1",
+		"cloud.zone": "eu-west2-a",
+		"cloud.account.id": "project1",
 		// Populated through OpenCensus resource environment variables.
-		"k8s.io/namespace/name": "ns1",
-		"k8s.io/pod/name": "pod1",
-		"k8s.io/container/name": "container1",
+		"k8s.cluster_name": "cluster1",
+		"k8s.namespace.name": "ns1",
+		"k8s.pod.name": "pod1",
+		"container.name": "container1",
 	},
 }
 ```
@@ -130,7 +130,7 @@ resource type with well-known identifiers specific to its API:
 }
 ```
 
-For another, hyopthetical, backend a simple unique identifier might be constructed instead
+For another, hypothetical, backend a simple unique identifier might be constructed instead
 by its exporter:
 
 ```
@@ -139,10 +139,11 @@ cluster1/ns1/pod1/container1
 
 Exporter libraries MAY provide a default translation for well-known input resource types and labels.
 Those would generally be based on community-supported detection integrations maintained in the
-[census-ecosystem][census-ecosystem] organisation.
+[census-ecosystem][census-ecosystem-link] organisation.
 
 Additionally, exporters SHOULD provide configuration hooks for users to provide their own
 translation unless the exporter's backend does not support resources at all. For such backends,
 exporters SHOULD allow attaching converting resource labels to metric tags.
 
-[census-ecosystem]: https://github.com/census-ecosystem
+[census-ecosystem-link]: https://github.com/census-ecosystem
+[resource-proto-link]: https://github.com/census-instrumentation/opencensus-proto/blob/master/src/opencensus/proto/resource/v1/resource.proto

resource/StandardResources.md

@@ -0,0 +1,86 @@
+# Standard Resources
+
+This page lists the standard resource types in OpenCensus. For more details on how resources can 
+be combined see [this](Resource.md).
+
+OpenCensus defines these fields.
+ * [Compute Unit](#compute-unit)
+   * [Container](#container)
+ * [Deployment Service](#deployment-service)
+   * [Kubernetes](#kubernetes)
+ * [Compute Instance](#compute-instance)
+   * [Host](#host)
+ * [Environment](#environment)
+   * [Cloud](#cloud)
+   * [Cluster](#cluster)
+
+## TODOs
+* Add logical compute units: Service, Task - instance running in a service.
+* Add more compute units: Process, Lambda Function, AppEngine unit, etc.
+* Add Device (mobile) and Web Browser.
+* Decide if lower case strings only.
+* Consider to add optional/required for each label and combination of labels (e.g when supplying a 
+k8s resource all k8s may be required).
+
+## Compute Unit
+Resources defining a compute unit (e.g. Container, Process, Lambda Function).
+
+### Container
+**type:** `container`
+
+**Description:** A container instance. This resource can be [merged](Resource.md#Merging) with a
+deployment service resource, a compute instance resource, and an environment resource.
+
+| Label  | Description  | Example  |
+|---|---|---|
+| container.name | Container name. | `opencenus-autoconf` |
+| container.image.name | Name of the image the container was built on. | `gcr.io/opencensus/operator` |
+| container.image.tag | Container image tag. | `0.1` |
+
+## Deployment Service
+Resources defining a deployment service (e.g. Kubernetes).
+
+### Kubernetes
+**type:** `k8s`
+
+**Description:** A Kubernetes resource. This resource can be [merged](Resource.md#Merging) with
+a compute instance resource, and/or an environment resource.
+
+| Label  | Description  | Example  |
+|---|---|---|
+| k8s.cluster.name | The name of the cluster that the pod is running in. | `opencensus-cluster` |
+| k8s.namespace.name | The name of the namespace that the pod is running in. | `default` |
+| k8s.pod.name | The name of the pod. | `opencensus-pod-autoconf` |
+
+## Compute Instance
+Resources defining a computing instance (e.g. host).
+
+### Host
+**type:** `host`
+
+**Description:** A host is defined as a general computing instance. This resource should be
+[merged](Resource.md#Merging) with an environment resource.
+
+
+| Label  | Description  | Example  |
+|---|---|---|
+| host.hostname | Hostname of the host.<br/> It contains what the `hostname` command returns on the host machine. | `opencensus-test` |
+| host.id | Unique host id.<br/> For Cloud this must be the instance_id assigned by the cloud provider | `opencensus-test` |
+| host.name | Name of the host.<br/> It may contain what `hostname` returns on Unix systems, the fully qualified, or a name specified by the user. | `opencensus-test` |
+| host.type | Type of host.<br/> For Cloud this must be the machine type.| `n1-standard-1` |
+
+## Environment
+
+Resources defining a running environment (e.g. Cloud, Data Center).
+
+### Cloud
+**type:** `cloud`
+
+**Description:** A cloud infrastructure (e.g. GCP, Azure, AWS).
+
+| Label  | Description  | Example  |
+|---|---|---|
+| cloud.provider | Name of the cloud provider.<br/> Example values are aws, azure, gcp. | `gcp` |
+| cloud.account.id | The cloud account id used to identify different entities. | `opencensus` |
+| cloud.region | A specific geographical location where different entities can run | `us-central1` |
+| cloud.zone | Zones are a sub set of the region connected through low-latency links.<br/> In aws it is called availability-zone. | `us-central1-a` |