profiles: use single Profile.sample_type and clarify use of timestamps

opentelemetry/proto/profiles/v1development/profiles.proto

@@ -182,6 +182,10 @@ message ScopeProfiles {
   // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
   // This schema_url applies to all profiles in the "profiles" field.
   string schema_url = 3;
+
+  // The preferred type and unit of Samples in at least one Profile.
+  // See Profile.sample_type for possible values.
+  ValueType default_sample_type = 4;
 }
 
 // Profile is a common stacktrace profile format.
@@ -214,15 +218,12 @@ message ScopeProfiles {
 // for ease of understanding data migration, it is not intended that pprof:Profile and
 // OpenTelemetry:Profile encoding be wire compatible.
 message Profile {
-  // A description of the samples associated with each Sample.value.
-  // For a cpu profile this might be:
-  //   [["cpu","nanoseconds"]] or [["wall","seconds"]] or [["syscall","count"]]
+  // The type and unit of all Sample.values in this profile.
+  // For a cpu or off-cpu profile this might be:
+  //   ["cpu","nanoseconds"] or ["off_cpu","nanoseconds"]
   // For a heap profile, this might be:
-  //   [["allocations","count"], ["space","bytes"]],
-  // If one of the values represents the number of events represented
-  // by the sample, by convention it should be at index 0 and use
-  // sample_type.unit == "count".
-  repeated ValueType sample_type = 1;
+  //   ["allocated_objects","count"] or ["allocated_space","bytes"],
+  ValueType sample_type = 1;
   // The set of samples recorded in this profile.
   repeated Sample sample = 2;
 
@@ -247,32 +248,30 @@ message Profile {
   // for human-friendly content. The profile must stay functional if this field
   // is cleaned.
   repeated int32 comment_strindices = 8; // Indices into ProfilesDictionary.string_table.
-  // Index into the sample_type array to the default sample type.
-  int32 default_sample_type_index = 9;
 
   // A globally unique identifier for a profile. The ID is a 16-byte array. An ID with
   // all zeroes is considered invalid. It may be used for deduplication and signal
   // correlation purposes. It is acceptable to treat two profiles with different values
   // in this field as not equal, even if they represented the same object at an earlier
   // time.
   // This field is optional; an ID may be assigned to an ID-less profile in a later step.
-  bytes profile_id = 10;
+  bytes profile_id = 9;
 
   // dropped_attributes_count is the number of attributes that were discarded. Attributes
   // can be discarded because their keys are too long or because there are too many
   // attributes. If this value is 0, then no attributes were dropped.
-  uint32 dropped_attributes_count = 11;
+  uint32 dropped_attributes_count = 10;
 
   // Specifies format of the original payload. Common values are defined in semantic conventions. [required if original_payload is present]
-  string original_payload_format = 12;
+  string original_payload_format = 11;
 
   // Original payload can be stored in this field. This can be useful for users who want to get the original payload.
   // Formats such as JFR are highly extensible and can contain more information than what is defined in this spec.
   // Inclusion of original payload should be configurable by the user. Default behavior should be to not include the original payload.
   // If the original payload is in pprof format, it SHOULD not be included in this field.
   // The field is optional, however if it is present then equivalent converted data should be populated in other fields
   // of this message as far as is practicable.
-  bytes original_payload = 13;
+  bytes original_payload = 12;
 
   // References to attributes in attribute_table. [optional]
   // It is a collection of key/value pairs. Note, global attributes
@@ -287,7 +286,7 @@ message Profile {
   // https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#attribute
   // Attribute keys MUST be unique (it is not allowed to have more than one
   // attribute with the same key).
-  repeated int32 attribute_indices = 14;
+  repeated int32 attribute_indices = 13;
 }
 
 // Represents a mapping between Attribute Keys and Units.
@@ -385,32 +384,45 @@ message ValueType {
   AggregationTemporality aggregation_temporality = 3;
 }
 
-// Each Sample records values encountered in some program
-// context. The program context is typically a stack trace, perhaps
-// augmented with auxiliary information like the thread-id, some
-// indicator of a higher level request being handled etc.
+// Each Sample records values encountered in some program context. The program
+// context is typically a stack trace, perhaps augmented with auxiliary
+// information like the thread-id, some indicator of a higher level request
+// being handled etc.
+//
+// A Sample MUST have have at least one values or timestamps_unix_nano entry. If
+// 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.
+//
+// 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):
+//    values: []
+//    timestamps_unix_nano: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+//
+// Report of a stacktrace with an aggregated value without timestamps:
+//   values: [10]
+//    timestamps_unix_nano: []
+//
+// Report of a stacktrace at 4 timestamps where each point records a specific value:
+//    values: [2, 2, 3, 3]
+//    timestamps_unix_nano: [1, 2, 3, 4]
 message Sample {
   // locations_start_index along with locations_length refers to to a slice of locations in Profile.location_indices.
   int32 locations_start_index = 1;
   // locations_length along with locations_start_index refers to a slice of locations in Profile.location_indices.
   // Supersedes location_index.
   int32 locations_length = 2;
-  // The type and unit of each value is defined by the corresponding
-  // entry in Profile.sample_type. All samples must have the same
-  // number of values, the same as the length of Profile.sample_type.
-  // When aggregating multiple samples into a single sample, the
-  // result has a list of values that is the element-wise sum of the
-  // lists of the originals.
-  repeated int64 value = 3;
+  // The type and unit of each value is defined by Profile.sample_type.
+  repeated int64 values = 3;
   // References to attributes in ProfilesDictionary.attribute_table. [optional]
   repeated int32 attribute_indices = 4;
 
   // 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 = 5;
 
-  // Timestamps associated with Sample represented in nanoseconds. These timestamps are expected
-  // to fall within the Profile's time range. [optional]
+  // Timestamps associated with Sample represented in nanoseconds. These
+  // timestamps should fall within the Profile's time range.
   repeated uint64 timestamps_unix_nano = 6;
 }