From d79fb7288cc8399cc621fb2f0cac3fc980451860 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 23 Jun 2025 14:04:12 -0400 Subject: [PATCH 1/8] First cut at Entity SDK specification. --- specification/entities/sdk.md | 212 ++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 specification/entities/sdk.md diff --git a/specification/entities/sdk.md b/specification/entities/sdk.md new file mode 100644 index 00000000000..a9ed9209a5d --- /dev/null +++ b/specification/entities/sdk.md @@ -0,0 +1,212 @@ + + +# Entities SDK + +**Status**: [Development](../document-status.md) + + + +- [Overview](#overview) +- [Entity](#entity) + * [Entity Creation](#entity-creation) + * [Entity properties](#entity-properties) +- [EntityDetector](#entitydetector) + * [EntityDetector operations](#entitydetector-operations) + + [Detect a set of `Entity`](#detect-a-set-of-entity) +- [EntityProvider](#entityprovider) + * [EntityProvider creation](#entityprovider-creation) + * [EntityProvider operations](#entityprovider-operations) + + [Providing the current Resource](#providing-the-current-resource) + * [Dealing with conflicts in Entity and Resource](#dealing-with-conflicts-in-entity-and-resource) + * [Merge Algorithm](#merge-algorithm) + + [Construct a set of detected entities.](#construct-a-set-of-detected-entities) + * [Resolve conflicts with raw attributes](#resolve-conflicts-with-raw-attributes) + * [Resolve conflicts in Schema URL](#resolve-conflicts-in-schema-url) + + + +## Overview + +The Entities SDK consists of these main components: + +- [Entity](#entity) +- [EntityDetector](#entitydetector) +- [EntityProvider](#entityprovider) + +## Entity + +An `Entity` represents an object of interested associated with +produced telemetry: traces, metrics, profiles or logs. Every entity +typically describes one object for its entire lifetime. + +### Entity Creation + +The SDK MUST accept the following parameters: + +- The entity's `type`. +- The entity's `identity` attributes. +- (optional) The entity's `description` attributes. +- (optional) The Schema URL associated with emitted entity. + +The SDK MAY use a builder pattern or other language convention for +constructing entities. + +### Entity properties + +The SDK MUST allow access to Entity properties: + +- The entity's `type`. +- The entity's `identity` attributes. +- The entity's `description` attributes. +- The SchemaURL associated with the entity. + +These MAY be provided using language conventions, e.g. public +fields, "Getter" methods, etc. + +## EntityDetector + +An `EntityDetector` is responsible for detecting the identity and +description for entities. A set of `EntityDetector`s will be used +by the SDK for the purpose of determining associated `Entity`s on +produced telemetry (metrics, log, traces). + +### EntityDetector operations + +The `EntityDetector` MUST provide the following functions: + +* Detect a set of `Entity`. + +#### Detect a set of `Entity` + +This operation MAY take input parameters related to the environment +the SDK is running in, or used for SDK diagnostics and debugging. + +This operation MUST return a collection or set of `Entity` objects +that were detected by the `EntityDetector`. + +This operation MAY return an error, in the event the detection +resulted in some kind of exceptional situation and was unable to +complete. + +## EntityProvider + + The `EntityProvider` is responsible for the following: + + - Constructing a `Resource` for the SDK from detectors. + - Dealing with conflicts between detectors and raw `Resource`. + - Providing SDK-internal access to the final `Resource`. + +An `EntityProvider` MAY decide when to run entity detection +and update the current `Resource`. + +### EntityProvider creation + +The SDK MUST accept the following parameters: + +- `detectors`: A collection or set of `EntityDetector`s. + Note: SDKs MUST provide a mechanism to prioritize or order + `EntityDetector`s. +- (optional) `resource`: A `Resource` created using the + + +### EntityProvider operations + +The `EntityProvider` MUST provide the following functions: + +- Providing the current `Resource`. + +#### Providing the current Resource + +This operation MUST return the current, complete `Resource` +the SDK should use when producing signals. + +This operation SHOULD be thread-safe, for languages or environments +that allow threads or concurrency. + +The returned resource SHOULD represent the most up-to-date +`Resource`, which includes all `Entity` found from +`EntityDetector`s and any original `Resource`. +The`EntityProvider` SHOULD NOT attempt to use `EntityDetector`s +every time this method is called, but instead cache a a result. + +### Dealing with conflicts in Entity and Resource + +The `EntityProvider` MUST resolve conflicts between `Resource` +and `EntityDetector`s that are registered with it. +The `EntityProvider` SHOULD use the [merge algorithm](#merge-algorithm) defined to deal with these conflicts. + +### Merge Algorithm + +The `EntityProvider` SHOULD use the following algorithm +(or an equivalent) to construct a single `Resource` using +`EntityDetector` and `Resource` provided to it. + +First, [construct a set of detected entities](#construct-a-set-of-detected-entities). + +Next, merge loose attributes (from `Resource`) with the +set of entities. [Resolve all conflicts](#resolve-conflicts-with-raw-attributes). + +Finally, select a Schema URL for the `Resource` by +[resolving conflicts between detected entities and resource](#resolve-conflicts-in-schema-url). + +The resulting `Resource` should include the remaining `Entity` +set, raw `Attribute`s and Schema URL. + +#### Construct a set of detected entities. + +Construct a set of detected entities (`E`) + +- All entity detectors are sorted by priority (highest first). +- For each entity detector (`D`), use the "detect a set of + entities" operation. + - For each entity detected (`d'`): + - If an entity (`e'`) exists in the current set of detected + entities (`E`) with the same `type` as the detected + entity (`d'`), do one of the following: + - If the entity `identity` and `schema_url` are the same, + merge the `description` of the detected entity (`d'`) into + the previously detected entity (`e'`). + - For each attribute (`da'`) in the description + - If the attribute key does not exist in the previously + detected entity (`e'`), then add the full attribute + (`da'`). + - otherwise, ignore the attribute. + - If the entity `identity` is the same, but `schema_url` is + different, drop the new entity (`d'`). + _Note: SDKs MAY provide configuration to preserve + non-conflicting description attributes in this case._ + - If the entity identity is different, drop the new + entity (`d'`). + - Otherwise, add the detected entity (`d'`) to the set of + detected entities (`E`). + +### Resolve conflicts with raw attributes + +When a "raw" attribute from `Resource` (those not associated with +an entity) has the same key as an `Entity`'s `identity` or +`description` attributes, then there is a conflict. + +If the *value* of the attribute is the same, the SDK can ignore the +"raw" attribute. + +If the *value* of the attribute is different, then the SDK must +resolve the conflict. + +- The SDK MUST remove the `Entity` from the detected `Entity` set + if the conflict is with an `identity` attribute. +- The SDK MAY remove the `Entity` or just the conflicting attribute + from the `Entity` if the conflict is with a `description` + attribute. + +### Resolve conflicts in Schema URL + +If the detected `Entity` set and raw `Resource` all share the +same Schema URL, then this Schema URL SHOULD be returned. + +If the detected `Entity` set have non-empty Schema URLs and +these conflict, then Schema URL SHOULD NOT be set on the Resource. + +If the detected `Entity` set is empty or does not have any Schema +URLs defined, then the raw `Resource` Schema URL SHOULD be used. From d20b37850d25ed207f495f2ac739530f8b54ba87 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 23 Jun 2025 14:51:41 -0400 Subject: [PATCH 2/8] Clean up from lint. --- specification/entities/sdk.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification/entities/sdk.md b/specification/entities/sdk.md index a9ed9209a5d..002be2615fe 100644 --- a/specification/entities/sdk.md +++ b/specification/entities/sdk.md @@ -94,9 +94,9 @@ complete. The `EntityProvider` is responsible for the following: - - Constructing a `Resource` for the SDK from detectors. - - Dealing with conflicts between detectors and raw `Resource`. - - Providing SDK-internal access to the final `Resource`. +- Constructing a `Resource` for the SDK from detectors. +- Dealing with conflicts between detectors and raw `Resource`. +- Providing SDK-internal access to the final `Resource`. An `EntityProvider` MAY decide when to run entity detection and update the current `Resource`. @@ -108,8 +108,8 @@ The SDK MUST accept the following parameters: - `detectors`: A collection or set of `EntityDetector`s. Note: SDKs MUST provide a mechanism to prioritize or order `EntityDetector`s. -- (optional) `resource`: A `Resource` created using the - +- (optional) `resource`: A `Resource` created using existing + Resource SDK. ### EntityProvider operations @@ -154,7 +154,7 @@ Finally, select a Schema URL for the `Resource` by The resulting `Resource` should include the remaining `Entity` set, raw `Attribute`s and Schema URL. -#### Construct a set of detected entities. +#### Construct a set of detected entities Construct a set of detected entities (`E`) @@ -175,8 +175,8 @@ Construct a set of detected entities (`E`) - otherwise, ignore the attribute. - If the entity `identity` is the same, but `schema_url` is different, drop the new entity (`d'`). - _Note: SDKs MAY provide configuration to preserve - non-conflicting description attributes in this case._ + *Note: SDKs MAY provide configuration to preserve + non-conflicting description attributes in this case.* - If the entity identity is different, drop the new entity (`d'`). - Otherwise, add the detected entity (`d'`) to the set of From 246867bacf92dce0a21b152be209fad8b7dd5109 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 23 Jun 2025 14:56:33 -0400 Subject: [PATCH 3/8] Fix toc. --- specification/entities/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/entities/sdk.md b/specification/entities/sdk.md index 002be2615fe..7f52e12ff1c 100644 --- a/specification/entities/sdk.md +++ b/specification/entities/sdk.md @@ -21,7 +21,7 @@ linkTitle: SDK + [Providing the current Resource](#providing-the-current-resource) * [Dealing with conflicts in Entity and Resource](#dealing-with-conflicts-in-entity-and-resource) * [Merge Algorithm](#merge-algorithm) - + [Construct a set of detected entities.](#construct-a-set-of-detected-entities) + + [Construct a set of detected entities](#construct-a-set-of-detected-entities) * [Resolve conflicts with raw attributes](#resolve-conflicts-with-raw-attributes) * [Resolve conflicts in Schema URL](#resolve-conflicts-in-schema-url) From 371cb0e9ec3b49248927272b8d4bf188648e3f7e Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 23 Jun 2025 14:59:09 -0400 Subject: [PATCH 4/8] Update specification/entities/sdk.md Co-authored-by: Nathan L Smith --- specification/entities/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/entities/sdk.md b/specification/entities/sdk.md index 7f52e12ff1c..7da5ab38dc0 100644 --- a/specification/entities/sdk.md +++ b/specification/entities/sdk.md @@ -128,7 +128,7 @@ that allow threads or concurrency. The returned resource SHOULD represent the most up-to-date `Resource`, which includes all `Entity` found from `EntityDetector`s and any original `Resource`. -The`EntityProvider` SHOULD NOT attempt to use `EntityDetector`s +The `EntityProvider` SHOULD NOT attempt to use `EntityDetector`s every time this method is called, but instead cache a a result. ### Dealing with conflicts in Entity and Resource From 8c87d42f0da7b6c91048c0de5183ddc9fb6e38c3 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 23 Jun 2025 16:22:46 -0400 Subject: [PATCH 5/8] Update specification/entities/sdk.md Co-authored-by: Daniel Dyla --- specification/entities/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/entities/sdk.md b/specification/entities/sdk.md index 7da5ab38dc0..9a74e795df5 100644 --- a/specification/entities/sdk.md +++ b/specification/entities/sdk.md @@ -83,7 +83,7 @@ The `EntityDetector` MUST provide the following functions: This operation MAY take input parameters related to the environment the SDK is running in, or used for SDK diagnostics and debugging. -This operation MUST return a collection or set of `Entity` objects +This operation MUST return a collection of `Entity` objects that were detected by the `EntityDetector`. This operation MAY return an error, in the event the detection From 8b16faf97a75beb2aa72ba562ce520c5835ff1df Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 23 Jun 2025 16:47:35 -0400 Subject: [PATCH 6/8] Fixes from review. --- specification/entities/sdk.md | 31 ++++++++++++++----------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/specification/entities/sdk.md b/specification/entities/sdk.md index 9a74e795df5..9e051a38043 100644 --- a/specification/entities/sdk.md +++ b/specification/entities/sdk.md @@ -11,7 +11,7 @@ linkTitle: SDK - [Overview](#overview) - [Entity](#entity) * [Entity Creation](#entity-creation) - * [Entity properties](#entity-properties) + * [Retrieving Entity properties](#retrieving-entity-properties) - [EntityDetector](#entitydetector) * [EntityDetector operations](#entitydetector-operations) + [Detect a set of `Entity`](#detect-a-set-of-entity) @@ -53,14 +53,17 @@ The SDK MUST accept the following parameters: The SDK MAY use a builder pattern or other language convention for constructing entities. -### Entity properties +### Retrieving Entity properties -The SDK MUST allow access to Entity properties: +The API MUST allow retrieving the `type`, `identity`, `description` and +Schema URL in the following forms: -- The entity's `type`. -- The entity's `identity` attributes. -- The entity's `description` attributes. -- The SchemaURL associated with the entity. +- Get the entity's `type` as a string. +- Get the entity's `identity` as an + [Attribute Collection](../common/README.md#attribute-collections). +- Get the entity's `description` as an + [Attribute Collection](../common/README.md#attribute-collections). +- Get the SchemaURL associated with the entity as a string or empty value. These MAY be provided using language conventions, e.g. public fields, "Getter" methods, etc. @@ -97,9 +100,7 @@ complete. - Constructing a `Resource` for the SDK from detectors. - Dealing with conflicts between detectors and raw `Resource`. - Providing SDK-internal access to the final `Resource`. - -An `EntityProvider` MAY decide when to run entity detection -and update the current `Resource`. +- Deduplicating and merging discovered `Entity`s. ### EntityProvider creation @@ -202,11 +203,7 @@ resolve the conflict. ### Resolve conflicts in Schema URL -If the detected `Entity` set and raw `Resource` all share the -same Schema URL, then this Schema URL SHOULD be returned. - -If the detected `Entity` set have non-empty Schema URLs and -these conflict, then Schema URL SHOULD NOT be set on the Resource. +If all detected entities and initial `Resource` have the same URL, then +this is chosen for the resulting `Resource`. -If the detected `Entity` set is empty or does not have any Schema -URLs defined, then the raw `Resource` Schema URL SHOULD be used. +Otherwise, the Schema URL of the resulting `Resource` SHOULD be empty. From a392bb796312e6a8600a1632a98f4998e0edda2e Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 7 Jul 2025 08:50:06 -0400 Subject: [PATCH 7/8] Migrate Entities to be an API. --- specification/entities/README.md | 2 + specification/entities/api.md | 80 +++++++++++ specification/entities/sdk.md | 227 ++++++++++--------------------- 3 files changed, 152 insertions(+), 157 deletions(-) create mode 100644 specification/entities/api.md diff --git a/specification/entities/README.md b/specification/entities/README.md index be0fc3b2a7c..1b628934c40 100644 --- a/specification/entities/README.md +++ b/specification/entities/README.md @@ -26,3 +26,5 @@ traces, metrics, logs, profiles etc. ## Specifications - [Data Model](./data-model.md) +- [API](./api.md) +- [SDK](./sdk.md) diff --git a/specification/entities/api.md b/specification/entities/api.md new file mode 100644 index 00000000000..dc418f58aaa --- /dev/null +++ b/specification/entities/api.md @@ -0,0 +1,80 @@ + + +# Entities API + +**Status**: [Development](../document-status.md) + + + +- [Overview](#overview) +- [ResourceProvider](#resourceprovider) + * [ResourceProvider operations](#resourceprovider-operations) + + [Get the active Resource](#get-the-active-resource) + * [Resource](#resource) + * [Attach an Entity](#attach-an-entity) + + + +## Overview + +The Entities API is provided for instrumentation authors to build +[Entities](./data-model.md#entity-data-model) and report them +against the OpenTelemetry [Resource](../resource/README.md) for all signals. + +This detection of the environment and its entities is expected +to happen early / immediately in the lifespan of a system being +observed, however, the Entities are allowed to change over the +lifespan of the Resource. + +The Entities API consists of these main components: + +- [ResourceProvider](#resourceprovider) +- [Resource](#resource) + +## ResourceProvider + +`Resource`s can be accessed with a `ResourceProvider`. + +Normally, the `ResourceProvider` is expected to be accessed from a central place. +Thus, the API SHOULD provide a way to set/register and access a global default +`ResourceProvider`. + +### ResourceProvider operations + +The `ResourceProvider` MUST provide the following functions: + +* Get the active `Resource` + +#### Get the active Resource + +This API MUST return the current `Resource` for which Telemetry +is being reported. + +### Resource + +The `Resource` is responsible for emitting `Entity`s and tracking +the current set of entities attached to the `Resource`. + +The `Resource` MUST provide a function to: + +- [Attach an Entity](#attach-an-entity) + +### Attach an Entity + +The effect of calling this API is to attach (or update) an Entity +to the current `Resource`. + +The API MUST accept the following parameters: + +- `entity_type`: A string that uniquely identifies the type of Entity. + See [entity data model](./data-model.md#entity-data-model) for details. +- `identity`: Specifies the attributes which identify the entity. + This API MUST be structured to accept a variable number of + attributes, but must see at least one attribute. +- `description` (optional): Specifies the attributes which describe the + entity. This API MUST be structured to accept a variable number + of attributes, including none. +- `schema_url` (optional): Specifies the Schema URL that should be recorded in + the emitted telemetry. diff --git a/specification/entities/sdk.md b/specification/entities/sdk.md index 9e051a38043..20ce5a961cd 100644 --- a/specification/entities/sdk.md +++ b/specification/entities/sdk.md @@ -9,197 +9,110 @@ linkTitle: SDK - [Overview](#overview) -- [Entity](#entity) - * [Entity Creation](#entity-creation) - * [Retrieving Entity properties](#retrieving-entity-properties) -- [EntityDetector](#entitydetector) - * [EntityDetector operations](#entitydetector-operations) - + [Detect a set of `Entity`](#detect-a-set-of-entity) -- [EntityProvider](#entityprovider) - * [EntityProvider creation](#entityprovider-creation) - * [EntityProvider operations](#entityprovider-operations) - + [Providing the current Resource](#providing-the-current-resource) - * [Dealing with conflicts in Entity and Resource](#dealing-with-conflicts-in-entity-and-resource) - * [Merge Algorithm](#merge-algorithm) - + [Construct a set of detected entities](#construct-a-set-of-detected-entities) - * [Resolve conflicts with raw attributes](#resolve-conflicts-with-raw-attributes) +- [ResourceProvider](#resourceprovider) + * [ResourceProvider Creation](#resourceprovider-creation) + * [Active Resource.](#active-resource) * [Resolve conflicts in Schema URL](#resolve-conflicts-in-schema-url) + * [Configuration](#configuration) + * [Shutdown](#shutdown) + * [ForceFlush](#forceflush) +- [Resource](#resource) + * [Attach an Entity](#attach-an-entity) ## Overview -The Entities SDK consists of these main components: - -- [Entity](#entity) -- [EntityDetector](#entitydetector) -- [EntityProvider](#entityprovider) - -## Entity - -An `Entity` represents an object of interested associated with -produced telemetry: traces, metrics, profiles or logs. Every entity -typically describes one object for its entire lifetime. - -### Entity Creation - -The SDK MUST accept the following parameters: - -- The entity's `type`. -- The entity's `identity` attributes. -- (optional) The entity's `description` attributes. -- (optional) The Schema URL associated with emitted entity. - -The SDK MAY use a builder pattern or other language convention for -constructing entities. - -### Retrieving Entity properties - -The API MUST allow retrieving the `type`, `identity`, `description` and -Schema URL in the following forms: - -- Get the entity's `type` as a string. -- Get the entity's `identity` as an - [Attribute Collection](../common/README.md#attribute-collections). -- Get the entity's `description` as an - [Attribute Collection](../common/README.md#attribute-collections). -- Get the SchemaURL associated with the entity as a string or empty value. - -These MAY be provided using language conventions, e.g. public -fields, "Getter" methods, etc. +Users of OpenTelemetry need a way for instrumentation interactions with the +OpenTelemetry API to actually produce telemetry. The OpenTelemetry Entities SDK +(henceforth referred to as the SDK) is an implementation of the OpenTelemetry +API that provides users with this functionally. -## EntityDetector +All language implementations of OpenTelemetry MUST provide an SDK. -An `EntityDetector` is responsible for detecting the identity and -description for entities. A set of `EntityDetector`s will be used -by the SDK for the purpose of determining associated `Entity`s on -produced telemetry (metrics, log, traces). - -### EntityDetector operations - -The `EntityDetector` MUST provide the following functions: - -* Detect a set of `Entity`. - -#### Detect a set of `Entity` - -This operation MAY take input parameters related to the environment -the SDK is running in, or used for SDK diagnostics and debugging. - -This operation MUST return a collection of `Entity` objects -that were detected by the `EntityDetector`. - -This operation MAY return an error, in the event the detection -resulted in some kind of exceptional situation and was unable to -complete. - -## EntityProvider - - The `EntityProvider` is responsible for the following: - -- Constructing a `Resource` for the SDK from detectors. -- Dealing with conflicts between detectors and raw `Resource`. -- Providing SDK-internal access to the final `Resource`. -- Deduplicating and merging discovered `Entity`s. +The Entities SDK consists of these main components: -### EntityProvider creation +- [ResourceProvider](#resourceprovider) +- [Resource](#resource) -The SDK MUST accept the following parameters: +## ResourceProvider -- `detectors`: A collection or set of `EntityDetector`s. - Note: SDKs MUST provide a mechanism to prioritize or order - `EntityDetector`s. -- (optional) `resource`: A `Resource` created using existing - Resource SDK. +The ResourceProvider MUST provide a way to retrieve the current +[Resource](../resource/sdk.md) for use in there parts of the OpenTelemetry SDK. +This `Resource` MUST include all registered `Entity`s. -### EntityProvider operations +### ResourceProvider Creation -The `EntityProvider` MUST provide the following functions: +The SDK SHOULD allow the creation of multiple independent `ResourceProvider`s. -- Providing the current `Resource`. +### Active Resource -#### Providing the current Resource +This SDK MUST implement the +[Get the active Resource API](api.md#get-the-active-resource). -This operation MUST return the current, complete `Resource` -the SDK should use when producing signals. +The SDK MUST provide exactly one `Resource` per `ResourceProvider` via this API. -This operation SHOULD be thread-safe, for languages or environments -that allow threads or concurrency. +### Configuration -The returned resource SHOULD represent the most up-to-date -`Resource`, which includes all `Entity` found from -`EntityDetector`s and any original `Resource`. -The `EntityProvider` SHOULD NOT attempt to use `EntityDetector`s -every time this method is called, but instead cache a a result. +TBD -### Dealing with conflicts in Entity and Resource +### Shutdown -The `EntityProvider` MUST resolve conflicts between `Resource` -and `EntityDetector`s that are registered with it. -The `EntityProvider` SHOULD use the [merge algorithm](#merge-algorithm) defined to deal with these conflicts. +TBD -### Merge Algorithm +### ForceFlush -The `EntityProvider` SHOULD use the following algorithm -(or an equivalent) to construct a single `Resource` using -`EntityDetector` and `Resource` provided to it. +TBD -First, [construct a set of detected entities](#construct-a-set-of-detected-entities). +## Resource -Next, merge loose attributes (from `Resource`) with the -set of entities. [Resolve all conflicts](#resolve-conflicts-with-raw-attributes). +The SDK `Resource` is responsible for managing the current set of associated +`Entity`s on the `Resource. -Finally, select a Schema URL for the `Resource` by -[resolving conflicts between detected entities and resource](#resolve-conflicts-in-schema-url). +The SDK MUST track associated `Entity`s on this `Resource`. -The resulting `Resource` should include the remaining `Entity` -set, raw `Attribute`s and Schema URL. +### Attach an Entity -#### Construct a set of detected entities +The `Resource` MUST implement the [Attach an Entity](api.md#attach-an-entity) +operation. This operation will try to associate a new `Entity` on the +`Resource`. -Construct a set of detected entities (`E`) +If the incoming `Entity`'s `entity_type` property is not found in the current +set of `Entity`s on `Resource`, then the new `Entity` is added to the set. -- All entity detectors are sorted by priority (highest first). -- For each entity detector (`D`), use the "detect a set of - entities" operation. - - For each entity detected (`d'`): - - If an entity (`e'`) exists in the current set of detected - entities (`E`) with the same `type` as the detected - entity (`d'`), do one of the following: - - If the entity `identity` and `schema_url` are the same, - merge the `description` of the detected entity (`d'`) into - the previously detected entity (`e'`). - - For each attribute (`da'`) in the description - - If the attribute key does not exist in the previously - detected entity (`e'`), then add the full attribute - (`da'`). - - otherwise, ignore the attribute. - - If the entity `identity` is the same, but `schema_url` is - different, drop the new entity (`d'`). - *Note: SDKs MAY provide configuration to preserve - non-conflicting description attributes in this case.* - - If the entity identity is different, drop the new - entity (`d'`). - - Otherwise, add the detected entity (`d'`) to the set of - detected entities (`E`). +If the incoming `Entity`'s `entity_type` property matches an existing `Entity` +in the current set AND the `identity` attributes for these `Entity`s are +different, then the SDK MUST ignore the new entity. -### Resolve conflicts with raw attributes +If the incoming `Entity`'s `entity_type` property matches an existing `Entity` +in the current set AND the `identity` attributes for these `Entity`s are +the same but the `schema_url` is different, then the SDK MUST ignore the new +entity. -When a "raw" attribute from `Resource` (those not associated with -an entity) has the same key as an `Entity`'s `identity` or -`description` attributes, then there is a conflict. +If the incoming `Entity`'s `entity_type` property matches an existing `Entity` +in the current set AND the `identity` attributes for these `Entity`s are +the same AND the `schema_url` is the same, then the SDK MUST add any new +attributes found in the `description` to the existing entity. Any new + `description` attributes with the same keys as existing `description` + attributes SHOULD replace previous values. -If the *value* of the attribute is the same, the SDK can ignore the -"raw" attribute. +### Flattened Resource -If the *value* of the attribute is different, then the SDK must -resolve the conflict. +The SDK MUST return a flattened `Resource` for usage in exporters. This +flattened resource MUST provide the fields expected in the `Resource` +data model: -- The SDK MUST remove the `Entity` from the detected `Entity` set - if the conflict is with an `identity` attribute. -- The SDK MAY remove the `Entity` or just the conflicting attribute - from the `Entity` if the conflict is with a `description` - attribute. +- `attributes`: The complete set of all attributes +- `schema_url`: The Schema URL that should be recorded for this resource. + See [resolve conflicts in schema url](#resolve-conflicts-in-schema-url). +- `entity_refs`: References to the `Entity` data model in `Resource`. + These each include: + - `type`: The type of the entity. + - `schema_url`: The Scheam URL that was recorded for this Entity. + - `id_keys`: The attribute keys for the Entity identity. Values are found + in the `Resource.attributes` property. + - `description_keys`: The attribute keys for the Entity description. Values + are found in the `Resource.attributes` property. ### Resolve conflicts in Schema URL From 1079fad07f4ade7846c27fbba9f62211bd0fd06b Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Mon, 7 Jul 2025 08:59:35 -0400 Subject: [PATCH 8/8] Fix toc. --- specification/entities/sdk.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/entities/sdk.md b/specification/entities/sdk.md index 20ce5a961cd..9df249ad570 100644 --- a/specification/entities/sdk.md +++ b/specification/entities/sdk.md @@ -11,13 +11,14 @@ linkTitle: SDK - [Overview](#overview) - [ResourceProvider](#resourceprovider) * [ResourceProvider Creation](#resourceprovider-creation) - * [Active Resource.](#active-resource) - * [Resolve conflicts in Schema URL](#resolve-conflicts-in-schema-url) + * [Active Resource](#active-resource) * [Configuration](#configuration) * [Shutdown](#shutdown) * [ForceFlush](#forceflush) - [Resource](#resource) * [Attach an Entity](#attach-an-entity) + * [Flattened Resource](#flattened-resource) + * [Resolve conflicts in Schema URL](#resolve-conflicts-in-schema-url)