From 206cfc69ed724c44a04289fa828f6909d1dfd184 Mon Sep 17 00:00:00 2001 From: Alexey Alexandrov Date: Wed, 26 Nov 2025 19:58:30 -0800 Subject: [PATCH 1/2] Clarify the profile and sample timestamps relationship. --- CHANGELOG.md | 1 + .../proto/profiles/v1development/profiles.proto | 12 +++++++++--- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1fb1fa155..950956d48 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ The full list of changes can be found in the compare view for the respective rel - profiles: clarify Sample message usage guidance docs. [#742](https://github.com/open-telemetry/opentelemetry-proto/pull/742) - profiles: improve Sample message clarity and usage documentation. [#724](https://github.com/open-telemetry/opentelemetry-proto/pull/724) +- profiles: clarify the profile and sample timestamps relationship. [#744](https://github.com/open-telemetry/opentelemetry-proto/pull/744) ### Fixed diff --git a/opentelemetry/proto/profiles/v1development/profiles.proto b/opentelemetry/proto/profiles/v1development/profiles.proto index 1779bbd59..f0dc8d0e5 100644 --- a/opentelemetry/proto/profiles/v1development/profiles.proto +++ b/opentelemetry/proto/profiles/v1development/profiles.proto @@ -284,9 +284,13 @@ message Profile { // The following fields 3-12 are informational, do not affect // interpretation of results. - // Time of collection (UTC) represented as nanoseconds past the epoch. + // Time of collection represented as nanoseconds past the epoch. fixed64 time_unix_nano = 3; - // Duration of the profile, if a duration makes sense. + // Duration of the profile. For instant profiles like live heap snapshot, the + // duration can be zero but it may be preferable to set time_unix_nano to the + // process start time and duration_nano to the relative time when the profile + // was gathered. This ensures Sample.timestamps_unix_nano values such as + // allocation timestamp fall into the profile time range. uint64 duration_nano = 4; // The kind of events between sampled occurrences. // e.g [ "cpu","cycles" ] or [ "heap","bytes" ] @@ -402,7 +406,9 @@ message Sample { // The type and unit of each value is defined by Profile.sample_type. repeated int64 values = 4; // Timestamps associated with Sample represented in nanoseconds. These - // timestamps should fall within the Profile's time range. + // timestamps should fall within the + // [Profile.time_unix_nano, Profile.time_unix_nano + Profile.duration_nano) + // time range. repeated fixed64 timestamps_unix_nano = 5; } From 457299c223edb306648e06dd5b0a4cc2dc76274e Mon Sep 17 00:00:00 2001 From: Alexey Alexandrov Date: Mon, 1 Dec 2025 12:03:14 -0800 Subject: [PATCH 2/2] Update the timestamp format wording. --- opentelemetry/proto/profiles/v1development/profiles.proto | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/opentelemetry/proto/profiles/v1development/profiles.proto b/opentelemetry/proto/profiles/v1development/profiles.proto index f0dc8d0e5..fede0cf3c 100644 --- a/opentelemetry/proto/profiles/v1development/profiles.proto +++ b/opentelemetry/proto/profiles/v1development/profiles.proto @@ -284,7 +284,8 @@ message Profile { // The following fields 3-12 are informational, do not affect // interpretation of results. - // Time of collection represented as nanoseconds past the epoch. + // Time of collection. Value is UNIX Epoch time in nanoseconds since 00:00:00 + // UTC on 1 January 1970. fixed64 time_unix_nano = 3; // Duration of the profile. For instant profiles like live heap snapshot, the // duration can be zero but it may be preferable to set time_unix_nano to the @@ -405,8 +406,8 @@ message Sample { // The type and unit of each value is defined by Profile.sample_type. repeated int64 values = 4; - // Timestamps associated with Sample represented in nanoseconds. These - // timestamps should fall within the + // Timestamps associated with Sample. Value is UNIX Epoch time in nanoseconds + // since 00:00:00 UTC on 1 January 1970. The timestamps should fall within the // [Profile.time_unix_nano, Profile.time_unix_nano + Profile.duration_nano) // time range. repeated fixed64 timestamps_unix_nano = 5;