Clarify the profile and sample timestamps relationship.

Author: aalexand

CHANGELOG.md

@@ -8,6 +8,8 @@ The full list of changes can be found in the compare view for the respective rel
 
 ### Changed
 
+- profiles: clarify the profile and sample timestamps relationship. [#744](https://github.com/open-telemetry/opentelemetry-proto/pull/744)
+
 ### Fixed
 
 - logs: `SEVERITY_NUMBER_UNSPECIFIED` can be used as the `severity_number` field is optional. [#736](https://github.com/open-telemetry/opentelemetry-proto/pull/736)

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" ]
@@ -398,7 +402,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;
 }