From 82884b84118cbdf5a146d99c34b1c2084b51edaa 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 | 24 ++++++++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 52b38772590..91a0389b1a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,10 @@ release. ### Logs +### Resource + +- Add schema_url support to `Resource`. ([#1692](https://github.com/open-telemetry/opentelemetry-specification/pull/1692)) + ### Semantic Conventions - Add JSON RPC specific conventions ([#1643](https://github.com/open-telemetry/opentelemetry-specification/pull/1643)). diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index b74e4b6fe97..58a656435f2 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,17 @@ 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 +116,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