Sync changes to profile.proto.

PiperOrigin-RevId: 668533280
Change-Id: I5716e9163305414a478c5a0a57e420f4d3455d52

tcmalloc/internal/profile.proto

@@ -1,4 +1,4 @@
-// Copyright 2018 Google LLC
+// Copyright 2016 Google Inc. All Rights Reserved.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -11,8 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-//
-////////////////////////////////////////////////////////////////////////////////
 
 // Profile is a common stacktrace profile format.
 //
@@ -60,9 +58,9 @@ message Profile {
   // Mapping from address ranges to the image/binary/library mapped
   // into that address range.  mapping[0] will be the main binary.
   repeated Mapping mapping = 3;
-  // Useful program location
+  // Locations referenced by samples.
   repeated Location location = 4;
-  // Functions referenced by locations
+  // Functions referenced by locations.
   repeated Function function = 5;
   // A common table for strings referenced by various messages.
   // string_table[0] must always be "".
@@ -71,7 +69,7 @@ message Profile {
   // regexp will be dropped from the samples, along with their successors.
   int64 drop_frames = 7;  // Index into string table.
   // frames with Function.function_name fully matching the following
-  // regexp will be kept, even if it matches drop_functions.
+  // regexp will be kept, even if it matches drop_frames.
   int64 keep_frames = 8;  // Index into string table.
 
   // The following fields are informational, do not affect
@@ -86,7 +84,11 @@ message Profile {
   ValueType period_type = 11;
   // The number of events between sampled occurrences.
   int64 period = 12;
-  // Freeform text associated to the profile.
+  // Free-form text associated with the profile. The text is displayed as is
+  // to the user by the tools that read profiles (e.g. by pprof). This field
+  // should not be used to store any machine-readable information, it is only
+  // for human-friendly content. The profile must stay functional if this field
+  // is cleaned.
   repeated int64 comment = 13;  // Indices into string table.
   // Index into the string table of the type of the preferred sample
   // value. If unset, clients should default to the last sample value.
@@ -115,7 +117,13 @@ message Sample {
   // lists of the originals.
   repeated int64 value = 2;
   // label includes additional context for this sample. It can include
-  // things like a thread id, allocation size, etc
+  // things like a thread id, allocation size, etc.
+  //
+  // NOTE: While possible, having multiple values for the same label key is
+  // strongly discouraged and should never be used. Most tools (e.g. pprof) do
+  // not have good (or any) support for multi-value labels. And an even more
+  // discouraged case is having a string label and a numeric label of the same
+  // name on a sample.  Again, possible to express, but should not be used.
   repeated Label label = 3;
 }