From 039601f155712c793d45abd5e993cd4fce4009ad Mon Sep 17 00:00:00 2001 From: James Bebbington Date: Sat, 15 Aug 2020 12:12:07 +1000 Subject: [PATCH 1/3] Added resource detection spec --- specification/library-guidelines.md | 4 +++ specification/resource/sdk.md | 34 ++++++++++++++++++++++ specification/sdk-environment-variables.md | 10 +++---- 3 files changed, 43 insertions(+), 5 deletions(-) diff --git a/specification/library-guidelines.md b/specification/library-guidelines.md index 2b6ad798940..0c818d24dd6 100644 --- 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 index c80d825878b..1e613f78854 100644 --- 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 index ea74e24e321..3085c0fb020 100644 --- 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.md#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 From a3f31e9081b6201df348e10178cf0f3f1e9a2b80 Mon Sep 17 00:00:00 2001 From: James Bebbington Date: Thu, 20 Aug 2020 11:39:21 +1000 Subject: [PATCH 2/3] Review suggestions --- specification/resource/sdk.md | 10 ++++++---- specification/sdk-environment-variables.md | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index 1e613f78854..d8dfe64518c 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -72,8 +72,9 @@ attributes"](semantic_conventions/README.md) that have prescribed semantic meani ### 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. +Custom resource detectors related to generic platforms (e.g. Docker, Kubernetes) +or vendor specific environments (e.g. EKS, AKS, GKE) 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 @@ -94,8 +95,9 @@ 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. +variable and [merge](#merge) this, as the secondary resource, with any resource +information provided by the user, i.e. the user provided resource information +has higher priority. 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 diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index 3085c0fb020..c2f54f0affb 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -6,7 +6,7 @@ The goal of this specification is to unify the environment variable names betwee | Name | Description | Default | Notes | | ------------------------ | ------------------------------------------------- | --------------------------------- | ----------------------------------- | -| OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes | - | See [Resource SDK](./resource/sdk.md#specifying-resource-information-via-an-environment-variable) for more details. | +| OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes | | See [Resource SDK](./resource/sdk.md#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" | | From fe512eb15db0c6970c378f1cf9829a058ecf6cbd Mon Sep 17 00:00:00 2001 From: James Bebbington Date: Sat, 22 Aug 2020 13:02:41 +1000 Subject: [PATCH 3/3] Minor updates based on review feedback --- specification/resource/sdk.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index 6750b56c34b..55d63d2fb76 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -76,17 +76,17 @@ Custom resource detectors related to generic platforms (e.g. Docker, Kubernetes) or vendor specific environments (e.g. EKS, AKS, GKE) 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 MUST provide a method that returns a 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 +Resource detection logic is expected to complete quickly since this code will be +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