Merge branch 'main' of github.com:open-telemetry/opentelemetry-specif…

…ication into jmacd/sampling_new

CHANGELOG.md

@@ -27,12 +27,23 @@ release.
 
 ### Resource
 
+### Profiles
+
+- Define required attributes for Mappings.
+  ([#4197](https://github.com/open-telemetry/opentelemetry-specification/pull/4197))
+
 ### OpenTelemetry Protocol
 
 ### Compatibility
 
+- Add requirement to allow extending Stable APIs
+  ([#4270](https://github.com/open-telemetry/opentelemetry-specification/pull/4270))
+
 ### SDK Configuration
 
+- Clarify declarative configuration parse requirements for null vs empty.
+  ([#4269](https://github.com/open-telemetry/opentelemetry-specification/pull/4269))
+
 ### Common
 
 ### Supplementary Guidelines

specification/README.md

@@ -42,6 +42,7 @@ path_base_for_github_subdir:
   - [Protocol](protocol/README.md)
     - [Metrics](metrics/data-model.md)
     - [Logs](logs/data-model.md)
+    - [Profiles](profiles/mappings.md)
   - Compatibility
     - [OpenCensus](compatibility/opencensus.md)
     - [OpenTracing](compatibility/opentracing.md)

specification/configuration/data-model.md

@@ -86,7 +86,7 @@ results are allowed) and an error describing the parse failure to the user.
 
 Node types MUST be interpreted after environment variable substitution takes
 place. This ensures the environment string representation of boolean, integer,
-or floating point fields can be properly converted to expected types.
+or floating point properties can be properly converted to expected types.
 
 It MUST NOT be possible to inject YAML structures by environment variables. For
 example, see references to `INVALID_MAP_VALUE` environment variable below.

specification/configuration/sdk.md

@@ -179,7 +179,24 @@ Parse and validate a [configuration file](./data-model.md#file-based-configurati
 
 Parse MUST perform [environment variable substitution](./data-model.md#environment-variable-substitution).
 
-Parse MUST interpret null as equivalent to unset.
+Parse MUST differentiate between properties that are missing and properties that
+are present but null. For example, consider the following snippet,
+noting `.meter_provider.views[0].stream.drop` is present but null:
+
+```yaml
+meter_provider:
+  views:
+    - selector:
+        name: some.metric.name
+      stream:
+        aggregation:
+          drop:
+```
+
+As a result, the view stream should be configured with the `drop` aggregation.
+Note that some aggregations have additional arguments, but `drop` does not. The
+user MUST not be required to specify an empty object (i.e. `drop: {}`) in these
+cases.
 
 When encountering a reference to
 a [SDK extension component](#sdk-extension-components) which is not built in to
@@ -212,14 +229,15 @@ Interpret configuration model and return SDK components.
 The multiple responses MAY be returned using a tuple, or some other data
 structure encapsulating the components.
 
-If a field is null or unset and a default value is defined, Create MUST ensure
-the SDK component is configured with the default value. If a field is null or
-unset and no default value is defined, Create SHOULD return an error. For
-example, if configuring
+If a property has a default value defined (i.e. is _not_ required) and is
+missing or present but null, Create MUST ensure the SDK component is configured
+with the default value. If a property is required and is missing or present but
+null, Create SHOULD return an error. For example, if configuring
 the [span batching processor](../trace/sdk.md#batching-processor) and
-the `scheduleDelayMillis` field is null or unset, the component is configured
-with the default value of `5000`. However, if the `exporter` field is null or
-unset, Create fails fast since there is no default value for `exporter`.
+the `scheduleDelayMillis` property is missing or present but null, the component
+is configured with the default value of `5000`. However, if the `exporter`
+property is missing or present but null, Create fails fast since there is no
+default value for `exporter`.
 
 When encountering a reference to
 a [SDK extension component](#sdk-extension-components) which is not built in to

specification/profiles/README.md

@@ -0,0 +1,7 @@
+<!--- Hugo front matter used to generate the website version of this page:
+path_base_for_github_subdir:
+  from: tmp/otel/specification/profiles/_index.md
+  to: profiles/README.md
+--->
+
+# Profiles

specification/profiles/mappings.md

@@ -0,0 +1,36 @@
+# Mappings
+
+**Status**: [Development](../document-status.md)
+
+This document defines the required attributes of [`Mapping`](https://github.com/open-telemetry/oteps/blob/main/text/profiles/0239-profiles-data-model.md#message-mapping) messages.
+
+<!-- toc -->
+
+- [Attributes](#attributes)
+  * [Algorithm for `process.executable.build_id.htlhash`](#algorithm-for-processexecutablebuild_idhtlhash)
+
+<!-- tocstop -->
+
+## Attributes
+
+A message representing a `Mapping` MUST have at least one of the following
+[process attributes](https://opentelemetry.io/docs/specs/semconv/attributes-registry/process/#process-attributes):
+
+- `process.executable.build_id.gnu`
+- `process.executable.build_id.go`
+- `process.executable.build_id.htlhash`
+
+If possible all the above listed attributes SHOULD be present in a `Mapping`. To promote interoperability, it is RECOMMENDED for `process.executable.build_id.htlhash` to be present in every `Mapping`. For the use and purpose of `process.executable.build_id.go` see [golang/go#68652](https://github.com/golang/go/issues/68652#issuecomment-2274452424).
+
+### Algorithm for `process.executable.build_id.htlhash`
+
+In some environments GNU and/or Go build_id values are stripped or not usable - for example Alpine
+Linux which is often used as a base for Docker environments. For that reason and to promote interoperability, a deterministic build_id generation algorithm that hashes the first and last page of a file together with its length is defined as:
+
+```
+Input   ← Concat(File[:4096], File[-4096:], BigEndianUInt64(Len(File)))
+Digest  ← SHA256(Input)
+BuildID ← Digest[:16]
+```
+
+where `Input` is the concatenation of the first and last 4096 bytes of the file (may overlap, not padded) and the 8 byte big-endian serialization of the file length. The resulting `BuildID` is the truncation of the hash digest to 16 bytes (128 bits), in hex string form.

specification/versioning-and-stability.md

@@ -142,10 +142,23 @@ the plugin interfaces MUST continue to be possible to use with newer versions of
 For languages that commonly share code via binary artifacts, e.g. Java, backwards-compatible means that end user's code that implements plugin interfaces MUST continue to be possible to use with newer minor or patch versions without recompiling the end user's code.
 
 If this backwards compatible addition of methods to interfaces is not possible for a language,
-the language maintainers MAY still implement the addition using backwards-compatible workarounds without incrementing the major version.
+the language maintainers SHOULD still implement the addition using backwards-compatible
+workarounds without incrementing the major version.
 For example, a possible workaround might be to add a new interface instead of extending the existing one and accept the
 new interface in addition to the old one in every place.
 
+Additionally, a Stable signal's API/SDK MAY be extended by adding new methods to existing
+Stable APIs. Language implementations SHOULD have a mechanism to do so, such that:
+
+- Adding a new method in Development maturity level is possible and is not a breaking
+  change for users that do not use the new method.
+- New in Development methods SHOULD require opt-in, so that the user is made aware of
+  the risk associated with using the development API. It should be documented that
+  the newly added methods are in Development and are subject to breaking changes.
+- Removing (or deprecating) a method that was in Development maturity level but did
+  not graduate to Stable level is not a breaking change for users that never used the
+  method.
+
 There may be other ways to extend existing API/SDKs in non-breaking manner. Language
 maintainers SHOULD choose the idiomatic way for their language.