diff --git a/CHANGELOG.md b/CHANGELOG.md index bba0f1ead6c..f4fa6282ee6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,10 @@ release. ### Resource +- Clarify that a Resource describes the observed entity, not the component + that technically emits telemetry. + ([#4905](https://github.com/open-telemetry/opentelemetry-specification/pull/4905)) + ### Entities ### Common diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index bb8fb98051c..ff2da244437 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -170,7 +170,7 @@ Here is the list of fields in a log record: | SeverityText | The severity text (also known as log level). | | SeverityNumber | Numerical value of the severity. | | Body | The body of the log record. | -| Resource | Describes the source of the log. | +| Resource | Describes the observed entity that generated the log. | | InstrumentationScope | Describes the scope that emitted the log. | | Attributes | Additional information about the event. | | EventName | Name that identifies the class / type of event. | diff --git a/specification/resource/README.md b/specification/resource/README.md index ef270704dac..e8ff7239123 100644 --- a/specification/resource/README.md +++ b/specification/resource/README.md @@ -23,15 +23,26 @@ path_base_for_github_subdir: ## Overview -A Resource is a representation of the entity producing telemetry. +A Resource represents the observed entity for which telemetry is produced. 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. +a high latency in a span, I need to check the metrics for the same entity +during the time when the latency was observed. + +> [!NOTE] +> The entity that *technically emits* telemetry and the entity *described by* +> a Resource are not always the same. In auto-instrumentation scenarios, such +> as eBPF-based agents that observe a running process without code changes, +> the instrumentation agent produces the telemetry on behalf of the observed +> workload. In these cases, the Resource describes the *observed* entity +> (e.g., the service or process being instrumented), not the agent itself. +> Attributes such as `telemetry.sdk.name` and `telemetry.distro.name` that +> pertain to the instrumentation tooling should be applied according to their +> own semantic conventions rather than used to identify the observed entity. Resource provides two important aspects for observability: -- It MUST identify an entity that is producing telemetry. +- It MUST identify the observed entity for which telemetry is being produced. - It SHOULD allow users to determine where that entity resides within their infrastructure. ### Identity diff --git a/specification/resource/data-model.md b/specification/resource/data-model.md index 5fa43c193cc..5fb5bebfec4 100644 --- a/specification/resource/data-model.md +++ b/specification/resource/data-model.md @@ -18,13 +18,15 @@ weight: 2 -A Resource is a representation of the entity producing telemetry as Attributes. -For example, You could have a process producing telemetry that is -running in a container on Kubernetes, which is associated to a Pod running on a -Node that is a VM but also is in a namespace and possibly is part of a +A Resource represents the observed entity for which telemetry is produced. +It is defined by a set of Attributes that identify the source of the telemetry, +rather than the component that technically produces it (like an +auto-instrumentation agent). +For example, a process running in a container on Kubernetes is associated to a +Pod running on a Node that is a VM, in a namespace, and possibly part of a Deployment. Resource could have attributes to denote information about the Container, the Pod, the Node, the VM or the Deployment. All of these help -identify what produced the telemetry. Note that there are certain attributes +identify the observed entity. Note that there are certain attributes that have prescribed meanings. A resource is composed of 0 or more [`Entities`](../entities/README.md) and 0 diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index 5fcfcaa742f..232b90af71c 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -7,12 +7,13 @@ weight: 3 **Status**: [Stable](../document-status.md) except where otherwise specified -A [Resource](../overview.md#resources) is an immutable representation of the entity producing -telemetry as [Attributes](../common/README.md#attribute). -For example, a process producing telemetry that is running in a -container on Kubernetes has a Pod name, it is in a namespace and possibly is -part of a Deployment which also has a name. All three of these attributes can be -included in the `Resource`. Note that there are certain +A [Resource](../overview.md#resources) is an immutable representation of the +observed entity for which telemetry is being produced, expressed as +[Attributes](../common/README.md#attribute). +For example, a process running in a container on Kubernetes has a Pod name, it +is in a namespace and possibly is part of a Deployment which also has a name. +All three of these attributes can be included in the `Resource`. Note that there +are certain [attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md) that have prescribed meanings.