Skip to content

Commit 8548dfc

Browse files
authored
Introduce specification for OTel Profiles (#4197)
## Changes Proposed change along with open-telemetry/semantic-conventions#1329 to clarify the use of `build_id` in the context of OTel Profiles. FYI: @open-telemetry/profiling-maintainers * [x] [`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md) file updated for non-trivial changes
1 parent 4926dfb commit 8548dfc

File tree

4 files changed

+49
-0
lines changed

4 files changed

+49
-0
lines changed

CHANGELOG.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,11 @@ release.
2424

2525
### Resource
2626

27+
### Profiles
28+
29+
- Define required attributes for Mappings.
30+
([#4197](https://github.com/open-telemetry/opentelemetry-specification/pull/4197))
31+
2732
### OpenTelemetry Protocol
2833

2934
### Compatibility

specification/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ path_base_for_github_subdir:
4242
- [Protocol](protocol/README.md)
4343
- [Metrics](metrics/data-model.md)
4444
- [Logs](logs/data-model.md)
45+
- [Profiles](profiles/mappings.md)
4546
- Compatibility
4647
- [OpenCensus](compatibility/opencensus.md)
4748
- [OpenTracing](compatibility/opentracing.md)

specification/profiles/README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<!--- Hugo front matter used to generate the website version of this page:
2+
path_base_for_github_subdir:
3+
from: tmp/otel/specification/profiles/_index.md
4+
to: profiles/README.md
5+
--->
6+
7+
# Profiles

specification/profiles/mappings.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Mappings
2+
3+
**Status**: [Development](../document-status.md)
4+
5+
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.
6+
7+
<!-- toc -->
8+
9+
- [Attributes](#attributes)
10+
* [Algorithm for `process.executable.build_id.htlhash`](#algorithm-for-processexecutablebuild_idhtlhash)
11+
12+
<!-- tocstop -->
13+
14+
## Attributes
15+
16+
A message representing a `Mapping` MUST have at least one of the following
17+
[process attributes](https://opentelemetry.io/docs/specs/semconv/attributes-registry/process/#process-attributes):
18+
19+
- `process.executable.build_id.gnu`
20+
- `process.executable.build_id.go`
21+
- `process.executable.build_id.htlhash`
22+
23+
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).
24+
25+
### Algorithm for `process.executable.build_id.htlhash`
26+
27+
In some environments GNU and/or Go build_id values are stripped or not usable - for example Alpine
28+
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:
29+
30+
```
31+
Input ← Concat(File[:4096], File[-4096:], BigEndianUInt64(Len(File)))
32+
Digest ← SHA256(Input)
33+
BuildID ← Digest[:16]
34+
```
35+
36+
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.

0 commit comments

Comments
 (0)