Added resource detection spec

open-telemetry · Aug 15, 2020 · c5429e4 · c5429e4
1 parent 61a1d44
commit c5429e4
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 5 deletions.
diff --git a/specification/library-guidelines.md b/specification/library-guidelines.md
@@ -90,6 +90,10 @@ For example:
 - Python and Java: opentelemetry-exporter-jaeger
 - Javascript: @opentelemetry/exporter-jeager
 
+#### Resource Detection
+
+Cloud vendors are encouraged to provide packages to detect resource information from the environment. These MUST be implemented outside of the SDK. See [Resource SDK](./resource/sdk.md#detecting-resource-information-from-the-environment) for more details.
+
 ### Alternative Implementations
 
 The end-user application may decide to take a dependency on alternative implementation.

diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md
@@ -70,6 +70,40 @@ resource.
 Note that the OpenTelemetry project documents certain ["standard
 attributes"](semantic_conventions/README.md) that have prescribed semantic meanings.
 
+### Detecting resource information from the environment
+
+Custom resource detectors related to specific environments (e.g. specific cloud
+vendors) MUST be implemented as packages separate from the SDK.
+
+Resource detector packages MUST provide a method that returns a single resource.
+This can then be associated with `TracerProvider` or `MeterProvider` instances
+as described above.
+
+Resource detector packages MAY detect resource information from multiple
+possible sources and merge the result using the `Merge` operation described
+above.
+
+Resource detection logic MUST be synchronous and is expected to complete quickly
+since this is run during application initialization. Errors should be handled as
+specified in the [Error Handling
+principles](../error-handling.md#basic-error-handling-principles). Note the
+failure to detect any resource information MUST NOT be considered an error,
+whereas an error that occurs during an attempt to detect resource information
+SHOULD be considered an error.
+
+### Specifying resource information via an environment variable
+
+The SDK MUST extract information from the `OTEL_RESOURCE_ATTRIBUTES` environment
+variable and merge this, as the secondary resource, with any resource
+information provided by the user.
+
+The `OTEL_RESOURCE_ATTRIBUTES` environment variable will contain of a list of
+key value pairs, and these are expected to be represented in a format matching
+to the [W3C
+Correlation-Context](https://github.com/w3c/correlation-context/blob/master/correlation_context/HTTP_HEADER_FORMAT.md#header-value),
+except that additional semi-colon delimited metadata is not supported, i.e.:
+`key1=value1,key2=value2`. All attribute values MUST be considered strings.
+
 ## Resource operations
 
 Resources are immutable. Thus, in addition to resource creation,

diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md
@@ -4,11 +4,11 @@ The goal of this specification is to unify the environment variable names betwee
 
 ## General SDK Configuration
 
-| Name                 | Description                                      | Default                           | Notes                                                                                       |
-| -------------------- | ------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------- |
-| OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes    |                                   | Spec details TBD. Proposal in [OTEP-111](https://github.com/open-telemetry/oteps/pull/111). |
-| OTEL_LOG_LEVEL       | Log level used by the SDK logger                 | "info"                            |                                                                                             |
-| OTEL_PROPAGATORS     | Propagators to be used as a comma separated list | "tracecontext,correlationcontext" |                                                                                             |
+| Name                     | Description                                       | Default                           | Notes                               |
+| ------------------------ | ------------------------------------------------- | --------------------------------- |                                     |
+| OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes | -                                 | See [Resource SDK](./resource/sdk#specifying-resource-information-via-an-environment-variable) for more details. |
+| OTEL_LOG_LEVEL           | Log level used by the SDK logger                  | "info"                            |                                     |
+| OTEL_PROPAGATORS         | Propagators to be used as a comma separated list  | "tracecontext,correlationcontext" |                                     |
 
 ## Batch Span Processor