From c1c1a163ca9f394b5cfc1f4ca0982a3adbf86622 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Mon, 3 Jun 2019 11:03:08 -0700 Subject: [PATCH] resource terminology and API (#56) * resource terminology and API * addressed code review comments --- terminology.md | 17 ++++++++++++++++- .../specification/resource/README.md | 14 -------------- .../specification/resource/Resource.md | 6 ------ 3 files changed, 16 insertions(+), 21 deletions(-) delete mode 100644 work_in_progress/specification/resource/README.md diff --git a/terminology.md b/terminology.md index ba732e6b3..0cd2fb6a0 100644 --- a/terminology.md +++ b/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 diff --git a/work_in_progress/specification/resource/README.md b/work_in_progress/specification/resource/README.md deleted file mode 100644 index 6b6edf34f..000000000 --- a/work_in_progress/specification/resource/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# OpenCensus Library Resource Package -This documentation serves to document the "look and feel" of the OpenCensus resource package. -It describes their key types and overall behavior. - -The resource library primarily defines a type "Resource" 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. -The primary purpose of resources as a first-class concept in the core library is decoupling -of discovery of resource information from exporters. This allows for independent development -of easy customization for users that need to integrate with closed source environments. - - -## Main APIs -* [Resource](Resource.md) diff --git a/work_in_progress/specification/resource/Resource.md b/work_in_progress/specification/resource/Resource.md index 612d57f6f..f87bc763a 100644 --- a/work_in_progress/specification/resource/Resource.md +++ b/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