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 new file mode 100644 index 00000000000..9df249ad570 --- /dev/null +++ b/specification/entities/sdk.md @@ -0,0 +1,123 @@ + + +# Entities SDK + +**Status**: [Development](../document-status.md) + + + +- [Overview](#overview) +- [ResourceProvider](#resourceprovider) + * [ResourceProvider Creation](#resourceprovider-creation) + * [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) + + + +## Overview + +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. + +All language implementations of OpenTelemetry MUST provide an SDK. + +The Entities SDK consists of these main components: + +- [ResourceProvider](#resourceprovider) +- [Resource](#resource) + +## ResourceProvider + +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. + +### ResourceProvider Creation + +The SDK SHOULD allow the creation of multiple independent `ResourceProvider`s. + +### Active Resource + +This SDK MUST implement the +[Get the active Resource API](api.md#get-the-active-resource). + +The SDK MUST provide exactly one `Resource` per `ResourceProvider` via this API. + +### Configuration + +TBD + +### Shutdown + +TBD + +### ForceFlush + +TBD + +## Resource + +The SDK `Resource` is responsible for managing the current set of associated +`Entity`s on the `Resource. + +The SDK MUST track associated `Entity`s on this `Resource`. + +### Attach an Entity + +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`. + +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. + +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. + +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. + +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. + +### Flattened Resource + +The SDK MUST return a flattened `Resource` for usage in exporters. This +flattened resource MUST provide the fields expected in the `Resource` +data model: + +- `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 + +If all detected entities and initial `Resource` have the same URL, then +this is chosen for the resulting `Resource`. + +Otherwise, the Schema URL of the resulting `Resource` SHOULD be empty.