From 6ec14955286c340551121813c81b764c5c3846fb Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Wed, 12 May 2021 18:00:22 -0400 Subject: [PATCH] Define how Schema URL works for Resources This adds to the Resource SDK the concept of Schema URL proposed in OTEP 0152: https://github.com/open-telemetry/oteps/blob/main/text/0152-telemetry-schemas.md Related earlier PR that adds the Schema URL to the API: https://github.com/open-telemetry/opentelemetry-specification/pull/1666 --- CHANGELOG.md | 4 ++++ specification/resource/sdk.md | 23 +++++++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8094a4cc996..1e5024952ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -51,6 +51,10 @@ release. - Clarify "key/value pair list" vs "map" in Log Data Model. ([#1604](https://github.com/open-telemetry/opentelemetry-specification/pull/1604)) +### Resource + +- Add schema_url support to `Resource`. ([#](https://github.com/open-telemetry/opentelemetry-specification/pull/)) + ### Semantic Conventions - Fix the inconsistent formatting of semantic convention enums. ([#1598](https://github.com/open-telemetry/opentelemetry-specification/pull/1598/)) diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index b74e4b6fe97..3b400ee2f59 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -56,6 +56,9 @@ object. A factory method is recommended to enable support for cached objects. Required parameters: - [`Attributes`](../common/common.md#attributes) +- [since 1.4.0] `schema_url` (optional): Specifies the Schema URL that should be + recorded in the emitted resource. If the `schema_url` parameter is unspecified + then the created resource will have an empty Schema URL. ### Merge @@ -70,6 +73,16 @@ The resulting resource MUST have all attributes that are on any of the two input If a key exists on both the old and updating resource, the value of the updating resource MUST be picked (even if the updated value is empty). +The resulting resource will have the Schema URL calculated as follows: +- If the old resource's Schema URL is empty then the resulting resource's Schema + URL will be set to the Schema URL of the updating resource, +- Else if the updating resource's Schema URL is empty then the resulting + resource's Schema URL will be set to the Schema URL of the old resource, +- Else if the Schema URLs of the old and updating resources are the same then + that will be the Schema URL of the resulting resource, +- Else this is a merging error (this is the case when the Schema URL of the old + and updating resources are not empty and are different). + Required parameters: - the old resource @@ -102,6 +115,16 @@ 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. +Resource detectors that populate resource attributes according to OpenTelemetry +semantic conventions MUST ensure that the resource has a Schema URL set to a +value that matches the semantic conventions. Empty Schema URL SHOULD be used if +the detector does not populate the resource with any known attributes that have +a semantic convention or if the detector does not know what attributes it will +populate (e.g. the detector that reads the attributes from environment values +will not know what Schema URL to use). If multiple detectors are combined and +the detectors use different non-empty Schema URL it MUST be an error since it is +impossible to merge such resources. + ### Specifying resource information via an environment variable The SDK MUST extract information from the `OTEL_RESOURCE_ATTRIBUTES` environment