Spec Conformance Review: Resource

[Aneurysm9]

• Review the Resource API specification and identify all normative requirements it contains.
• Validate our implementation of the specification to conform or not. If it conforms, document the conformity here. If it does not open an Issue or PR track the work.
• Review the Resource section of the Spec Compliance Matrix.
• If there are any items listed in matrix that are not required by the specification, need clarification, or are in conflict with the specification open a PR in the specification to correct it.
• Update the matrix with the current state of Go (existing entries for Go should be ignored). If Go does not provide support for an item listed be sure to link to the Issue/PR tracking the work to support it.

[MrAlias]

Resource API:

The SDK MUST allow for creation of Resources and for associating them with telemetry.

The resource package implments this

When used with distributed tracing, a resource can be associated with the TracerProvider when the TracerProvider is created.
That association cannot be changed later.
When associated with a TracerProvider, all Spans produced by any Tracer from the provider MUST be associated with this Resource.

That is how we implement our Span creation

The SDK MUST provide access to a Resource with at least the attributes listed at Semantic Attributes with SDK-provided Default Value.

resource.Default

This resource MUST be associated with a TracerProvider or MeterProvider if another resource was not explicitly specified.

TracerProvider association
MeterProvider association

The interface MUST provide a way to create a new resource, from Attributes.
Required parameters:

• Attributes

resource.NewWithAttributes

The interface MUST provide a way for an old resource and an updating resource to be merged into a new resource.
The resulting resource MUST have all attributes that are on any of the two input resources.
If a key exists on both the old and updating resource, the value of the updating resource MUST be picked (even if the updated value is empty).
Required parameters:

• the old resource
• the updating resource whose attributes take precedence

resource.Merge

It is recommended, but not required, to provide a way to quickly create an empty resource.

resource.Empty

Custom resource detectors related to generic platforms (e.g. Docker, Kubernetes) or vendor specific environments (e.g. EKS, AKS, GKE) MUST be implemented as packages separate from the SDK.

We contain our in contrib/detectors/*

Resource detector packages MUST provide a method that returns a resource.

resource.Detect

Resource detector packages MAY detect resource information from multiple possible sources and merge the result using the Merge operation described above.

resource.Detect will take multiple Detectors and "merges each result with the previous one".

Resource detection logic is expected to complete quickly since this code will be run during application initialization. Errors should be handled as specified in the Error Handling principles.
Note the failure to detect any resource information MUST NOT be considered an error, whereas an error that occurs during an attempt to detect resource information SHOULD be considered an error.

This is a requirement for implementors of the Detector interface, not the API/SDK.

The SDK MUST extract information from the OTEL_RESOURCE_ATTRIBUTES environment variable and merge this, as the secondary resource, with any resource information provided by the user, i.e. the user provided resource information has higher priority.

The OTEL_RESOURCE_ATTRIBUTES environment variable will contain of a list of key value pairs, and these are expected to be represented in a format matching to the W3C Baggage, except that additional semi-colon delimited metadata is not supported, i.e.: key1=value1,key2=value2. All attribute values MUST be considered strings.

Not implemented, tracking with this

Resources are immutable. Thus, in addition to resource creation, only the following operations should be provided:
The SDK should provide a way to retrieve a read only collection of attributes associated with a resource.

Not a normative requirement, but we provide this.

The most common operation when retrieving attributes is to enumerate over them. As such, it is recommended to optimize the resulting collection for fast enumeration over other considerations such as a way to quickly retrieve a value for a attribute with a specific key.

Again, not a normative requirement, but we provide this. Though it should be renamed.

[MrAlias]

spec-compliance-matrix

Feature	Go
Create from Attributes	+
Create empty	+
Merge (v2)	+
Retrieve attributes	+
Default value for service.name	+