Skip to content

docs: clarify resource describes observed entity, not telemetry emitter#4905

Merged
jsuereth merged 2 commits intoopen-telemetry:mainfrom
svencowart:clarify-resource-definition
Mar 16, 2026
Merged

docs: clarify resource describes observed entity, not telemetry emitter#4905
jsuereth merged 2 commits intoopen-telemetry:mainfrom
svencowart:clarify-resource-definition

Conversation

@svencowart
Copy link
Copy Markdown
Contributor

@svencowart svencowart commented Feb 26, 2026 •
edited
Loading

Fixes #4903

Changes

Disambiguates the Resource definition to account for auto-instrumentation scenarios (e.g., eBPF agents) where the technical producer of telemetry differs from the entity being observed.

  • specification/resource/README.md: reframe definition as "entity for which telemetry is being produced"; add NOTE callout explaining that Resource MUST describe the observed workload in agent-based instrumentation, with guidance on telemetry.sdk.name / telemetry.distro.name
  • specification/resource/data-model.md: align definition language; explicitly note the observed entity vs. emitter distinction
  • specification/resource/sdk.md: same alignment for the SDK spec
  • specification/logs/data-model.md: update table description from "source of the log" to "observed entity that generated the log"

@svencowart svencowart requested review from a team as code owners February 26, 2026 21:37
@svencowart svencowart force-pushed the clarify-resource-definition branch from 38a63d1 to aedda40 Compare February 26, 2026 23:39
@pellared
Copy link
Copy Markdown
Member

pellared commented Mar 2, 2026

@svencowart, could you please add a changelog entry?

@pellared pellared added clarification clarify ambiguity in specification spec:resource Related to the specification/resource directory labels Mar 2, 2026
@svencowart
docs: clarify resource describes observed entity, not telemetry emitter
8a637d6 
Disambiguates the Resource definition to account for auto-instrumentation
scenarios (e.g., eBPF agents) where the technical producer of telemetry
differs from the entity being observed.

- specification/resource/README.md: reframe definition as "entity for
  which telemetry is being produced"; add NOTE callout explaining that
  Resource MUST describe the observed workload in agent-based
  instrumentation, with guidance on telemetry.sdk.name / telemetry.distro.name
- specification/resource/data-model.md: align definition language;
  explicitly note the observed entity vs. emitter distinction
- specification/resource/sdk.md: same alignment for the SDK spec
- specification/logs/data-model.md: update table description from
  "source of the log" to "observed entity that generated the log"
@svencowart svencowart force-pushed the clarify-resource-definition branch from aedda40 to 8a637d6 Compare March 2, 2026 17:06
@svencowart
Copy link
Copy Markdown
Contributor Author

svencowart commented Mar 2, 2026

@pellared done.

@florianl florianl mentioned this pull request Mar 3, 2026
Open
@dyladan
Copy link
Copy Markdown
Member

dyladan commented Mar 11, 2026

Its both though isn't it? At least in the case of the telemetry SDK attributes they reference the SDK which is monitoring the process. Admittedly it is a bit of an odd case because the SDK is a part of the process being monitored as well.

@jsuereth jsuereth added this pull request to the merge queue Mar 16, 2026
Merged via the queue into open-telemetry:main with commit 720364f Mar 16, 2026
8 checks passed
@carlosalberto carlosalberto mentioned this pull request Apr 15, 2026
Merged
pull Bot pushed a commit to MC-MAGA/opentelemetry-specification that referenced this pull request Apr 20, 2026
@carlosalberto @jack-berg
Release 1.56 (open-telemetry#5029)
50149c2 
### Context

- Align environment variable context propagation name restrictions with
POSIX.1-2024
  and define normalization behavior.

([open-telemetry#4944](open-telemetry#4944))
- Decouple the responsibilities of the environment variable propagation
carrier.

([open-telemetry#4961](open-telemetry#4961))
- Remove misleading implementation approach the environment variable
propagation.

([open-telemetry#5003](open-telemetry#5003))
- Change Environment Variables as Context Propagation Carriers document
status to Beta.

([open-telemetry#5020](open-telemetry#5020))

### Traces

- Stabilize Tracer `enabled` operation

([open-telemetry#4941](open-telemetry#4941))
- Stabilize `AlwaysRecord` sampler.

([open-telemetry#4934](open-telemetry#4934))

### Metrics

- Add development `maxExportBatchSize` parameter to Periodic exporting
MetricReader.

([open-telemetry#4895](open-telemetry#4895))

### Logs

- Add event to span event bridge.

([open-telemetry#5006](open-telemetry#5006))

### Resource

- Clarify that a Resource describes the observed entity, not the
component
  that technically emits telemetry.

([open-telemetry#4905](open-telemetry#4905))

### Compatibility

- Deprecate OpenTracing compatibility requirements in the specification.

([open-telemetry#4938](open-telemetry#4938))
- Stabilize sections of Prometheus and OpenMetrics Compatibility.
- Stabilize Prometheus Classic Histogram to OTLP Explicit Histogram
transformation.

([open-telemetry#4874](open-telemetry#4874))
  - Stabilize Prometheus Timestamp and Start timestamp transformation.

([open-telemetry#4953](open-telemetry#4953))
- Clarify Prometheus Native Histogram to OTLP Exponential Histogram
conversion,
add conversion rules for Native Histograms with Custom Buckets (NHCB) to
OTLP
    Histogram.

([open-telemetry#4898](open-telemetry#4898))
  - Stabilize Prometheus Dropped Types transformation.

([open-telemetry#4952](open-telemetry#4952))
- Stabilize OpenTelemetry Attributes to Prometheus labels
transformation.

([open-telemetry#4963](open-telemetry#4963))
- Stabilize Prometheus Exemplar to OpenTelemetry Exemplar
transformation.

([open-telemetry#4962](open-telemetry#4962))
  - Stabilize Prometheus Metadata transformation.

([open-telemetry#4954](open-telemetry#4954))
- Stabilize OpenTelemetry Metric Metadata to Prometheus metric metadata.

([open-telemetry#4966](open-telemetry#4966))
- Stabilize OpenTelemetry Exemplar to Prometheus Exemplar
transformation.

([open-telemetry#4964](open-telemetry#4964))
- Stabilize sections of Prometheus Metrics Exporter.
  - Stabilize host configuration.

([open-telemetry#5025](open-telemetry#5025))

### SDK Configuration

- Declarative configuration: add in-development guidance for exposing
the
  effective `Resource` returned by `Create`.

([open-telemetry#4949](open-telemetry#4949))
- Require spec changes to consider declarative config schema

([open-telemetry#4916](open-telemetry#4916))
- Add strict YAML parsing guidance to configuration supplementary
guidelines.

([open-telemetry#4878](open-telemetry#4878))

### OTEPs

- Process Context: Sharing Resource Attributes with External Readers.

([open-telemetry#4719](open-telemetry#4719))
- Support multiple Resources within an SDK.

([open-telemetry#4665](open-telemetry#4665))

---------

Co-authored-by: Jack Berg <34418638+jack-berg@users.noreply.github.com>
hilmarf pushed a commit to apeirora/opentelemetry-specification that referenced this pull request Apr 22, 2026
@carlosalberto @jack-berg @hilmarf
Release 1.56 (open-telemetry#5029)
68fba8a 
### Context

- Align environment variable context propagation name restrictions with
POSIX.1-2024
  and define normalization behavior.

([open-telemetry#4944](open-telemetry#4944))
- Decouple the responsibilities of the environment variable propagation
carrier.

([open-telemetry#4961](open-telemetry#4961))
- Remove misleading implementation approach the environment variable
propagation.

([open-telemetry#5003](open-telemetry#5003))
- Change Environment Variables as Context Propagation Carriers document
status to Beta.

([open-telemetry#5020](open-telemetry#5020))

### Traces

- Stabilize Tracer `enabled` operation

([open-telemetry#4941](open-telemetry#4941))
- Stabilize `AlwaysRecord` sampler.

([open-telemetry#4934](open-telemetry#4934))

### Metrics

- Add development `maxExportBatchSize` parameter to Periodic exporting
MetricReader.

([open-telemetry#4895](open-telemetry#4895))

### Logs

- Add event to span event bridge.

([open-telemetry#5006](open-telemetry#5006))

### Resource

- Clarify that a Resource describes the observed entity, not the
component
  that technically emits telemetry.

([open-telemetry#4905](open-telemetry#4905))

### Compatibility

- Deprecate OpenTracing compatibility requirements in the specification.

([open-telemetry#4938](open-telemetry#4938))
- Stabilize sections of Prometheus and OpenMetrics Compatibility.
- Stabilize Prometheus Classic Histogram to OTLP Explicit Histogram
transformation.

([open-telemetry#4874](open-telemetry#4874))
  - Stabilize Prometheus Timestamp and Start timestamp transformation.

([open-telemetry#4953](open-telemetry#4953))
- Clarify Prometheus Native Histogram to OTLP Exponential Histogram
conversion,
add conversion rules for Native Histograms with Custom Buckets (NHCB) to
OTLP
    Histogram.

([open-telemetry#4898](open-telemetry#4898))
  - Stabilize Prometheus Dropped Types transformation.

([open-telemetry#4952](open-telemetry#4952))
- Stabilize OpenTelemetry Attributes to Prometheus labels
transformation.

([open-telemetry#4963](open-telemetry#4963))
- Stabilize Prometheus Exemplar to OpenTelemetry Exemplar
transformation.

([open-telemetry#4962](open-telemetry#4962))
  - Stabilize Prometheus Metadata transformation.

([open-telemetry#4954](open-telemetry#4954))
- Stabilize OpenTelemetry Metric Metadata to Prometheus metric metadata.

([open-telemetry#4966](open-telemetry#4966))
- Stabilize OpenTelemetry Exemplar to Prometheus Exemplar
transformation.

([open-telemetry#4964](open-telemetry#4964))
- Stabilize sections of Prometheus Metrics Exporter.
  - Stabilize host configuration.

([open-telemetry#5025](open-telemetry#5025))

### SDK Configuration

- Declarative configuration: add in-development guidance for exposing
the
  effective `Resource` returned by `Create`.

([open-telemetry#4949](open-telemetry#4949))
- Require spec changes to consider declarative config schema

([open-telemetry#4916](open-telemetry#4916))
- Add strict YAML parsing guidance to configuration supplementary
guidelines.

([open-telemetry#4878](open-telemetry#4878))

### OTEPs

- Process Context: Sharing Resource Attributes with External Readers.

([open-telemetry#4719](open-telemetry#4719))
- Support multiple Resources within an SDK.

([open-telemetry#4665](open-telemetry#4665))

---------

Co-authored-by: Jack Berg <34418638+jack-berg@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jsuereth jsuereth jsuereth approved these changes

@carlosalberto carlosalberto carlosalberto approved these changes

@pellared pellared pellared approved these changes

@MrAlias MrAlias MrAlias approved these changes

@reyang reyang reyang approved these changes

+1 more reviewer

@florianl florianl florianl approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

@jsuereth jsuereth

Labels

clarification clarify ambiguity in specification spec:resource Related to the specification/resource directory

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Clarify Resource definition for auto instrumentation

8 participants

@svencowart @pellared @dyladan @jsuereth @carlosalberto @florianl @MrAlias @reyang