Create initial Entities data model specification.

CHANGELOG.md

@@ -34,6 +34,9 @@ release.
 
 ### Resource
 
+- Add Datamodel for Entities
+   ([#4442](https://github.com/open-telemetry/opentelemetry-specification/pull/4442))
+
 ### Profiles
 
 ### OpenTelemetry Protocol

specification/entities/README.md

@@ -0,0 +1,28 @@
+<!--- Hugo front matter used to generate the website version of this page:
+path_base_for_github_subdir:
+  from: tmp/otel/specification/entities/_index.md
+  to: entities/README.md
+--->
+
+# Entities
+
+ <details>
+ <summary>Table of Contents</summary>
+
+<!-- toc -->
+
+- [Overview](#overview)
+- [Specifications](#specifications)
+
+<!-- tocstop -->
+
+</details>
+
+## Overview
+
+Entity represents an object of interest associated with produced telemetry:
+traces, metrics, logs, profiles etc.
+
+## Specifications
+
+- [Data Model](./data-model.md)

specification/entities/data-model.md

@@ -0,0 +1,209 @@
+# Entity Data Model
+
+**Status**: [Development](../document-status.md)
+
+<details>
+<summary>Table of Contents</summary>
+
+<!-- toc -->
+
+- [Minimally Sufficient Identity](#minimally-sufficient-identity)
+- [Repeatable Identity](#repeatable-identity)
+- [Examples of Entities](#examples-of-entities)
+
+<!-- tocstop -->
+
+</details>
+
+Entity represents an object of interest associated with produced telemetry:
+traces, metrics, profiles, or logs.
+
+For example, telemetry produced using an OpenTelemetry SDK is normally
+associated with a `service` entity. Similarly, OpenTelemetry defines system
+metrics for a `host`. The `host` is the entity we want to associate metrics with
+in this case.
+
+Entities may be also associated with produced telemetry indirectly.
+For example a service that produces
+telemetry is also related to a process in which the service runs, so we say that
+the `service` entity is related to the `process` entity. The process normally
+also runs on a host, so we say that the `process` entity is related to the
+`host` entity.
+
+> Note: Entity relationship modelling will be refined in future specification
+> work.
+
+The data model below defines a logical model for an entity (irrespective of the
+physical format and encoding of how entity data is recorded).
+
+<table>
+   <tr>
+    <td><strong>Field</strong>
+    </td>
+    <td><strong>Type</strong>
+    </td>
+    <td><strong>Description</strong>
+    </td>
+   </tr>
+   <tr>
+    <td>Type
+    </td>
+    <td>string
+    </td>
+    <td>Defines the type of the entity. MUST not change during the
+lifetime of the entity. For example: "service" or "host". This field is
+required and MUST not be empty for valid entities.
+    </td>
+   </tr>
+   <tr>
+    <td>Id
+    </td>
+    <td>map&lt;string, standard attribute value&gt;
+    </td>
+    <td>Attributes that identify the entity.
+<p>
+MUST not change during the lifetime of the entity. The Id must contain
+at least one attribute.
+<p>
+Follows OpenTelemetry <a
+href="../../specification/common/README.md#standard-attribute">Standard
+attribute definition</a>. SHOULD follow OpenTelemetry <a
+href="https://github.com/open-telemetry/semantic-conventions">semantic
+conventions</a> for attributes.
+    </td>
+   </tr>
+   <tr>
+    <td>Description
+    </td>
+    <td>map&lt;string, any&gt;
+    </td>
+    <td>Descriptive (non-identifying) attributes of the entity.
+<p>
+MAY change over the lifetime of the entity. MAY be empty. These
+attributes are not part of entity's identity.
+<p>
+Follows <a
+href="../../specification/logs/data-model.md#type-any">any</a>
+value definition in the OpenTelemetry spec. Arbitrary deep nesting of values
+for arrays and maps is allowed.
+<p>
+SHOULD follow OpenTelemetry <a
+href="https://github.com/open-telemetry/semantic-conventions">semantic
+conventions</a> for attributes.
+    </td>
+   </tr>
+</table>
+
+## Minimally Sufficient Identity
+
+Commonly, a number of attributes of an entity are readily available for the telemetry
+producer to compose an Id from. Of the available attributes the entity Id should
+include the minimal set of attributes that is sufficient for uniquely identifying
+that entity. For example a Process on a host can be uniquely identified by
+(`process.pid`,`process.start_time`) attributes. Adding for example `process.executable.name` attribute to the Id is unnecessary and violates the
+Minimally Sufficient Identity rule.
+
+## Repeatable Identity
+
+The identifying attributes for entity SHOULD be values that can be repeatably
+obtained by observers of that entity. For example, a `process` entity SHOULD
+have the same identity (and be recognized as the same process), regardless of whether
+the identity was generated from the process itself, e.g. via SDK, or by an
+OpenTelemetry Collector running on the same host, or by some other system
+describing the process.
+
+> Aside: There are many ways to accomplish repeatable identifying attributes
+> across multiple observers. While many successful systems rely on pushing down
+> identity from a central registry or knowledge store, OpenTelemetry must
+> support all possible scenarios.
+
+## Examples of Entities
+
+_This section is non-normative and is present only for the purposes of
+demonstrating the data model._
+
+Here are examples of entities, the typical identifying attributes they
+have and some examples of descriptive attributes that may be
+associated with the entity.
+
+_Note: These examples MAY diverge from semantic conventions._
+
+<table>
+   <tr>
+    <td><strong>Entity</strong>
+    </td>
+    <td><strong>Entity Type</strong>
+    </td>
+    <td><strong>Identifying Attributes</strong>
+    </td>
+    <td><strong>Descriptive Attributes</strong>
+    </td>
+   </tr>
+   <tr>
+    <td>Container
+    </td>
+    <td><pre>container</pre>
+    </td>
+    <td>container.id
+    </td>
+    <td>container.image.id<br/>
+        container.image.name<br/>
+        container.image.tag.{key}<br/>
+        container.label.{key}<br/>
+        container.name<br/>
+        container.runtime<br/>
+        oci.manifest.digest<br/>
+        container.command<br/>
+    </td>
+   </tr>
+   <tr>
+    <td>Host
+    </td>
+    <td><pre>host</pre>
+    </td>
+    <td>host.id
+    </td>
+    <td>host.arch<br/>
+        host.name<br/>
+        host.type<br/>
+        host.image.id<br/>
+        host.image.name<br/>
+        host.image.version<br/>
+        host.type
+    </td>
+   </tr>
+   <tr>
+    <td>Kubernetes Node
+    </td>
+    <td><pre>k8s.node</pre>
+    </td>
+    <td>k8s.node.uid
+    </td>
+    <td>k8s.node.name
+    </td>
+   </tr>
+   <tr>
+    <td>Kubernetes Pod
+    </td>
+    <td><pre>k8s.pod</pre>
+    </td>
+    <td>k8s.pod.uid
+    </td>
+    <td>k8s.pod.name<br/>
+        k8s.pod.label.{key}<br/>
+        k8s.pod.annotation.{key}<br/>
+    </td>
+   </tr>
+   <tr>
+    <td>Service Instance
+    </td>
+    <td><pre>service.instance</pre>
+    </td>
+    <td>service.instance.id<br/>
+        service.name<br/>
+        service.namesapce
+    </td>
+    <td>service.version
+    </td>
+   </tr>
+</table>

specification/resource/README.md

@@ -5,3 +5,98 @@ path_base_for_github_subdir:
 --->
 
 # Resource
+
+ <details>
+ <summary>Table of Contents</summary>
+
+<!-- toc -->
+
+- [Overview](#overview)
+  * [Identity](#identity)
+  * [Navigation](#navigation)
+  * [Telescoping](#telescoping)
+- [Specifications](#specifications)
+
+<!-- tocstop -->
+
+</details>
+
+## Overview
+
+A Resource is a representation of the entity producing telemetry.
+Within OpenTelemetry, all signals are associated with a Resource, enabling
+contextual correlation of data from the same source.  For example, if I see
+a high latency in a span I need to check the metrics for the same entity that
+produced that Span during the time when the latency was observed.
+
+Resource provides two important aspects for observability:
+
+- It MUST identify an entity that is producing telemetry.
+- It SHOULD allow users to determine where that entity resides within their infrastructure.
+
+### Identity
+
+Resource provides a natural way to understand "what" produced an effect and
+evaluate other signals of that same source. This is done through attaching the
+same set of identifying attributes on all telemetry produced in an
+OpenTelemetry SDK.
+
+Resource identity provides a natural pivot point for observability signals, a
+key type of correlation in OpenTelemetry.
+
+### Navigation
+
+Implicit in the design of Resource and attributes is ensuring users are able to
+navigate their infrastructure, tools, UIs, etc. to find the *same* entity that
+telemetry is reporting against.  For example, in the definition above, we see a
+few entities listed for one Resource:
+
+- A process
+- A container
+- A kubernetes pod name
+- A namespace
+- A deployment
+
+By including identifying attributes of each of these, we can help users navigate
+through their `kubectl` or Kubernetes UIs to find the specific process
+generating telemetry.   This is as important as being able to uniquely identify
+one process from another.
+
+> Aside: Observability signals SHOULD be actionable.  Knowing a process is
+> struggling is not as useful as being able to scale up a deployment to take
+> load off the struggling process.
+
+If the only thing important to Resource was identity, we could simply use UUIDs.
+However, this would rely on some other, easily accessible, system to provide
+human-friendly understanding for these UUIDs. OpenTelemetry provides a model
+where a full UUID-only solution could be chosen, but defaults to a *blended*
+approach, where resource provides both Identity and Navigation.
+
+This leads to the next concept: Telescoping identity to the needs of a system.
+
+### Telescoping
+
+Within OpenTelemetry, we want to give users the flexibility to decide what
+information needs to be sent *with* observability signals and what information
+can be later joined.  We call this "telescoping identity" where users can decide
+how *small* or *large* the size of an OpenTelemetry resource will be on the wire
+(and correspondingly, how large data points are when stored, depending on
+storage solution).
+
+For example, in the extreme, OpenTelemery could synthesize a UUID for every
+system which produces telemetry.  All identifying attributes for Resource and
+Entity could be sent via a side channel with known relationships to this UUID.
+While this would optimise the runtime generation and sending of telemetry, it
+comes at the cost of downstream storage systems needing to join data back
+together either at ingestion time or query time. For high performance use cases,
+e.g. alerting, these joins can be expensive.
+
+In practice, users control Resource identity via the configuration of Resource
+Detection within SDKs and the collector. Users wishing for minimal identity will
+limit their resource detection just to a `service.instance.id`, for example.
+Some users highly customize resource detection with many concepts being appended.
+
+## Specifications
+
+- [Data Model](./data-model.md)
+- [Resource SDK](./sdk.md)