Entity Data Model

Status: Development

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).

FieldTypeDescription
TypestringDefines 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.
Idmap<string, standard attribute value>Attributes that identify the entity.

MUST not change during the lifetime of the entity. The Id must contain at least one attribute.

Follows OpenTelemetry Standard attribute definition. SHOULD follow OpenTelemetry semantic conventions for attributes.

Descriptionmap<string, any>Descriptive (non-identifying) attributes of the entity.

MAY change over the lifetime of the entity. MAY be empty. These attributes are not part of entity’s identity.

Follows any value definition in the OpenTelemetry spec. Arbitrary deep nesting of values for arrays and maps is allowed.

SHOULD follow OpenTelemetry semantic conventions for attributes.

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.

EntityEntity TypeIdentifying AttributesDescriptive Attributes
Container
container
container.idcontainer.image.id
container.image.name
container.image.tag.{key}
container.label.{key}
container.name
container.runtime
oci.manifest.digest
container.command
Host
host
host.idhost.arch
host.name
host.type
host.image.id
host.image.name
host.image.version
host.type
Kubernetes Node
k8s.node
k8s.node.uidk8s.node.name
Kubernetes Pod
k8s.pod
k8s.pod.uidk8s.pod.name
k8s.pod.label.{key}
k8s.pod.annotation.{key}
Service Instance
service.instance
service.instance.id
service.name
service.namesapce		service.version