diff --git a/CHANGELOG.md b/CHANGELOG.md index ba4d9e6a111..7215ad24c71 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,11 @@ release. ### Resource +### Profiles + +- Define required attributes for Mappings. + ([#4197](https://github.com/open-telemetry/opentelemetry-specification/pull/4197)) + ### OpenTelemetry Protocol ### Compatibility diff --git a/specification/README.md b/specification/README.md index d1136d70243..ba11a14e703 100644 --- a/specification/README.md +++ b/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) diff --git a/specification/profiles/README.md b/specification/profiles/README.md new file mode 100644 index 00000000000..1d08917ed31 --- /dev/null +++ b/specification/profiles/README.md @@ -0,0 +1,7 @@ + + +# Profiles diff --git a/specification/profiles/mappings.md b/specification/profiles/mappings.md new file mode 100644 index 00000000000..465ec9fbb4d --- /dev/null +++ b/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. + + + +- [Attributes](#attributes) + * [Algorithm for `process.executable.build_id.htlhash`](#algorithm-for-processexecutablebuild_idhtlhash) + + + +## 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.