Skip to content

Commit

Permalink
Introduce specification for OTel Profiles (#4197)
Browse files Browse the repository at this point in the history
## 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
  • Loading branch information
florianl authored Oct 24, 2024
1 parent 4926dfb commit 8548dfc
Show file tree
Hide file tree
Showing 4 changed files with 49 additions and 0 deletions.
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions specification/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
7 changes: 7 additions & 0 deletions specification/profiles/README.md
Original file line number Diff line number Diff line change
@@ -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
36 changes: 36 additions & 0 deletions specification/profiles/mappings.md
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit 8548dfc

Please sign in to comment.