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 dd44adff7ef..55d63d2fb76 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -70,6 +70,42 @@ 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 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 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 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 +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](#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 +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..c2f54f0affb 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