Add resource detector name (#4461)

All SDK extension plugin interfaces are referred to by name in
declarative config.

For SDK extension plugin interfaces like exporters, processors, metric
readers, we have well-defined sets of built-in implementations. E.g.:

- span exporter: otlp, otlp_file, console, zipkin
- metric exporter: otlp, otlp_file, console
- log exporter: otlp, otlp_file, console
- span processor: simple, batch
- metric reader: periodic, prometheus
- log processor: simple, batch

These well-defined names provide obvious choices to name things in the
declarative config JSON schema.

Resource detectors are currently much more open ended, with no defined
list of built-in detectors. This is a problem for declarative config
because we want to have a config story where you can plug the same YAML
into different SDK language implementation and get the same behavior.
Without defining this list, users will have to carefully lookup
language-specific resource detector names and modify their YAML
accordingly. Yikes.

This PR solves this by:

- Establishing that resource detectors have a name, used for reference
in configuration (where declarative config is the primary use case but
other config solutions could similarly use the name)
- Provide normative language for naming resource detectors according the
root namespace of attributes they (e.g. `os` resource detector populates
`os.*` attributes)
- Carve out a list of reserved resource detector names, which should
become standard in SDK-implementations

See also
[https://github.com/open-telemetry/opentelemetry-configuration/pull/188](https://github.com/open-telemetry/opentelemetry-configuration/pull/188)
for a reference at how these resource detector names are used in
declarative configuration.

cc @open-telemetry/configuration-approvers

Author: jack-berg

CHANGELOG.md

@@ -19,6 +19,9 @@ release.
 
 ### Resource
 
+- Add experimental resource detector name.
+  ([#4461](https://github.com/open-telemetry/opentelemetry-specification/pull/4461))
+
 ### Profiles
 
 ### OpenTelemetry Protocol

specification/resource/sdk.md

@@ -1,6 +1,6 @@
 # Resource SDK
 
-**Status**: [Stable](../document-status.md)
+**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).
@@ -128,6 +128,46 @@ the detectors use different non-empty Schema URL it MUST be an error since it is
 impossible to merge such resources. The resulting resource is undefined, and its
 contents are implementation specific.
 
+#### Resource detector name
+
+**Status**: [Development](../document-status.md)
+
+Resource detectors SHOULD have a unique name for reference in configuration. For
+example, users list and configure individual resource detectors by name
+in [declarative configuration](../configuration/README.md#declarative-configuration).
+Names SHOULD be [snake case](https://en.wikipedia.org/wiki/Snake_case) and
+consist of lowercase alphanumeric and `_` characters, which ensures they conform
+to declarative
+configuration [property name requirements](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/CONTRIBUTING.md#property-name-case).
+
+Resource detector names SHOULD reflect
+the [root namespace](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/naming.md#general-naming-considerations)
+of attributes they populate. For example, a resource detector named `os`
+populates `os.*` attributes. Resource detectors which populate attributes from
+multiple root namespaces SHOULD choose a name which appropriately conveys their
+purpose.
+
+An SDK which identifies multiple resource detectors with the same name SHOULD
+report an error. In order to limit collisions, resource detectors SHOULD
+document their name in a manner which is easily discoverable. Authors of
+resource detectors should check existing resource detectors to ensure their
+target name isn't already in use. Additionally, the following detector names are
+reserved for built-in resource detectors published with language SDKs:
+
+* `container`:
+  Populates [container.*](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/container.md)
+  attributes.
+* `host`:
+  Populates [host.*](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/host.md) and [os.*](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/os.md)
+  attributes.
+* `process`:
+  Populates [process.*](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/process.md)
+  attributes.
+* `service`: Populates `service.name` based
+  on [OTEL_SERVICE_NAME](../configuration/sdk-environment-variables.md#general-sdk-configuration)
+  environment variable; populates `service.instance.id`
+  as [defined here](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/attributes-registry/service.md#service-attributes).
+
 ### Specifying resource information via an environment variable
 
 The SDK MUST extract information from the `OTEL_RESOURCE_ATTRIBUTES` environment