From 975f6a7a202df6cc32f65dcbd404ffd1e7ac3e64 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Sun, 2 Jun 2019 16:10:00 -0700 Subject: [PATCH 1/2] resource terminology and API --- specification/README.md | 3 +- specification/resources-api.md | 65 +++++++++++++++++++ terminology.md | 17 ++++- .../specification/resource/README.md | 14 ---- 4 files changed, 83 insertions(+), 16 deletions(-) create mode 100644 specification/resources-api.md delete mode 100644 work_in_progress/specification/resource/README.md diff --git a/specification/README.md b/specification/README.md index de566bc09c7..7d0e299c975 100644 --- a/specification/README.md +++ b/specification/README.md @@ -5,4 +5,5 @@ describes the key types and the overall behavior. Main APIs: -- [Tracing API](tracing-api.md). \ No newline at end of file +- [Tracing API](tracing-api.md). +- [Resources API](resources-api.md). \ No newline at end of file diff --git a/specification/resources-api.md b/specification/resources-api.md new file mode 100644 index 00000000000..8e7339b8f6c --- /dev/null +++ b/specification/resources-api.md @@ -0,0 +1,65 @@ +# 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. + +## Resource creation + +API defines two ways to instantiate an instance of `Resource`. First, by providing a +collection of labels - method [Create](#create). This typically 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. + +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. + +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. diff --git a/terminology.md b/terminology.md index ba732e6b36c..0cd2fb6a0e5 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 6b6edf34f42..00000000000 --- 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) From eca974c1249250587cb7a9cf25ba1d41e3fb713a Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Mon, 3 Jun 2019 10:40:56 -0700 Subject: [PATCH 2/2] addressed code review comments --- specification/resources-api.md | 20 ++++++++++++++----- .../specification/resource/Resource.md | 6 ------ 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/specification/resources-api.md b/specification/resources-api.md index 8e7339b8f6c..a6953c8b8e9 100644 --- a/specification/resources-api.md +++ b/specification/resources-api.md @@ -16,12 +16,16 @@ When associated with the `SpanData` explicitly for out-of-band spans - **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). This typically use of this -method is by creating resource from the list of labels taken from Environment -variables, metadata API call response, or other sources. +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 @@ -36,7 +40,8 @@ labels"](../semantic-conventions.md) that have prescribed semantic meanings. ### Create -Creates a new `Resource` out of the collection of labels. +Creates a new `Resource` out of the collection of labels. This is a static +method. Required parameter: @@ -48,6 +53,11 @@ 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. diff --git a/work_in_progress/specification/resource/Resource.md b/work_in_progress/specification/resource/Resource.md index 612d57f6f50..f87bc763a5b 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