profiles: improve Sample message clarity and usage documentation. (#724)

* profiles: improve Sample message clarity and usage documentation.

* profiles: improve Sample message clarity and usage documentation.

Co-authored-by: Christos Kalkanis <[email protected]>

* profiles: improve Sample message clarity and usage documentation.

Co-authored-by: Christos Kalkanis <[email protected]>

* profiles: improve Sample message clarity and usage documentation.

* profiles: improve Sample message clarity and usage documentation.

---------

Co-authored-by: Christos Kalkanis <[email protected]>
Co-authored-by: Alexey Alexandrov <[email protected]>
Co-authored-by: Josh Suereth <[email protected]>

Author: 4 people

opentelemetry/proto/profiles/v1development/profiles.proto

@@ -364,6 +364,10 @@ message ValueType {
 // both fields are populated, they MUST contain the same number of elements, and
 // the elements at the same index MUST refer to the same event.
 //
+// For the purposes of efficiently representing aggregated data observations, a Sample is regarded
+// as having a shared identity and an associated collection of per-observation data points.
+// Samples having the same identity SHOULD be combined by inserting timestamps and values to the data arrays.
+//
 // Examples of different ways of representing a sample with the total value of 10:
 //
 // Report of a stacktrace at 10 timestamps (consumers must assume the value is 1 for each point):
@@ -378,17 +382,21 @@ message ValueType {
 //    values: [2, 2, 3, 3]
 //    timestamps_unix_nano: [1, 2, 3, 4]
 message Sample {
+
+  // A Sample's identity (i.e. 'primary key') is the tuple of {stack_index, set_of(attribute_indices), link_index}
+
   // Reference to stack in ProfilesDictionary.stack_table.
   int32 stack_index = 1;
-  // The type and unit of each value is defined by Profile.sample_type.
-  repeated int64 values = 2;
   // References to attributes in ProfilesDictionary.attribute_table. [optional]
-  repeated int32 attribute_indices = 3;
-
+  repeated int32 attribute_indices = 2;
   // Reference to link in ProfilesDictionary.link_table. [optional]
   // It can be unset / set to 0 if no link exists, as link_table[0] is always a 'null' default value.
-  int32 link_index = 4;
+  int32 link_index = 3;
+
+  // The following fields may contain per-observation data and do not form part of the Sample's identity.
 
+  // 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.
   repeated fixed64 timestamps_unix_nano = 5;