diff --git a/CHANGELOG.md b/CHANGELOG.md index 9bdb8919686..1b10cc66b1c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,7 @@ Updates: - Resource's service.name MUST have a default value, service.instance.id is not required. ([#1269](https://github.com/open-telemetry/opentelemetry-specification/pull/1269)) + - Clarified in [#1294](https://github.com/open-telemetry/opentelemetry-specification/pull/1294) - Add requirement that the SDK allow custom generation of Trace IDs and Span IDs ([#1006](https://github.com/open-telemetry/opentelemetry-specification/pull/1006)) - Add default ratio when TraceIdRatioSampler is specified by environment variable but diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 3ec5b02ef43..a997e781a9e 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -92,7 +92,7 @@ status of the feature is not known. |Create empty | + | + | + | + | + | + | | + | | + | + | |[Merge (v2)](specification/resource/sdk.md#merge) | | | | | | | | | | | | |Retrieve attributes | + | + | + | + | + | + | | + | | + | + | -|[Default value](specification/resource/semantic_conventions/README.md#attributes-with-default-value) for service.name | | | | | | | | | | | | +|[Default value](specification/resource/semantic_conventions/README.md#semantic-attributes-with-sdk-provided-default-value) for service.name | | | | | | | | | | | | ## Context Propagation diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index bcc2871fee1..e80b5a74c5e 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -1,10 +1,12 @@ # Resource SDK A [Resource](../overview.md#resources) is an immutable representation of the entity producing -telemetry. For example, a process producing telemetry that is running in a +telemetry as [Attributes](../common/common.md#attributes). +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`. +included in the `Resource`. Note that there are certain +["standard attributes"](semantic_conventions/README.md) that have prescribed meanings. The primary purpose of resources as a first-class concept in the SDK is decoupling of discovery of resource information from exporters. This allows for @@ -24,6 +26,21 @@ When associated with a [`MeterProvider`](../metrics/api.md#meter-interface), all metrics produced by any `Meter` from the provider will be associated with this `Resource`. +## SDK-provided resource attributes + +The SDK MUST provide access to a Resource with at least the attributes listed at +[Semantic Attributes with SDK-provided Default Value](semantic_conventions/README.md#semantic-attributes-with-sdk-provided-default-value). +This resource MUST be associated with a `TracerProvider` or `MeterProvider` +if another resource was not explicitly specified. + +Note: This means that it is possible to create and associate a resource that +does not have all or any of the SDK-provided attributes present. However, that +does not happen by default. If a user wants to combine custom attributes with +the default resource, they can use [`Merge`](#merge) with their custom resource +or specify their attributes by implementing +[Custom resource detectors](#detecting-resource-information-from-the-environment) +instead of explicitly associating a resource. + ## Resource creation The SDK must support two ways to instantiate new resources. Those are: @@ -34,9 +51,6 @@ The interface MUST provide a way to create a new resource, from [`Attributes`](. Examples include a factory method or a constructor for a resource object. A factory method is recommended to enable support for cached objects. -Note that certain **required** `Resource` attributes MUST be set to a default value if they were not specified. -See [Attributes with Default Value](semantic_conventions/README.md#attributes-with-default-value). - Required parameters: - [`Attributes`](../common/common.md#attributes) @@ -64,9 +78,6 @@ Required parameters: It is recommended, but not required, to provide a way to quickly create an empty resource. -Note that the OpenTelemetry project documents certain ["standard -attributes"](semantic_conventions/README.md) that have prescribed semantic meanings. - ### Detecting resource information from the environment Custom resource detectors related to generic platforms (e.g. Docker, Kubernetes) diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index de9743a25e9..c3a3bc68f04 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -9,13 +9,14 @@ This document defines standard attributes for resources. These attributes are ty - [TODOs](#todos) - [Document Conventions](#document-conventions) -- [Attributes with Default Value](#attributes-with-default-value) +- [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value) - [Service](#service) - [Telemetry SDK](#telemetry-sdk) - [Compute Unit](#compute-unit) - [Compute Instance](#compute-instance) - [Environment](#environment) - [Version attributes](#version-attributes) +- [Cloud-Provider-Specific Attributes](#cloud-provider-specific-attributes) @@ -33,9 +34,10 @@ Attributes are grouped logically by the type of the concept that they described. Certain attribute groups in this document have a **Required** column. For these groups if any attribute from the particular group is present in the Resource then all attributes that are marked as Required MUST be also present in the Resource. However it is also valid if the entire attribute group is omitted (i.e. none of the attributes from the particular group are present even though some of them are marked as Required in this document). -## Attributes with Default Value +## Semantic Attributes with SDK-provided Default Value -The SDK MUST set a default value for the following attributes if they were not specified, even if the resource would otherwise not be present at all: +These are the the attributes which MUST be provided by the SDK +as specified in the [Resource SDK specification](../sdk.md#sdk-provided-resource-attributes): - [`service.name`](#service)