Add a note about cardinality implications for attribute values. (#713)

Author: aalexand

CHANGELOG.md

@@ -6,6 +6,7 @@ The full list of changes can be found in the compare view for the respective rel
 
 ### Changed
 
+- profiles: add a note about cardinality implications for attribute values. [#713](https://github.com/open-telemetry/opentelemetry-proto/pull/713)
 - profiles: rename line -> lines and sample -> samples since they are repeated fields. [#712](https://github.com/open-telemetry/opentelemetry-proto/pull/712)
 
 ### Removed

opentelemetry/proto/profiles/v1development/profiles.proto

@@ -130,14 +130,24 @@ message ProfilesDictionary {
   // string_table[0] must always be "" and present.
   repeated string string_table = 5;
 
-  // A common table for attributes referenced by various messages.
-  // It is a collection of key/value pairs. Note, global attributes
-  // like server name can be set using the resource API. Examples of attributes:
+  // A common table for attributes referenced by the Profile, Sample, Mapping
+  // and Location messages below through attribute_indices field. Each entry is
+  // a key/value pair with an optional unit. Since this is a dictionary table,
+  // multiple entries with the same key may be present, unlike direct attribute
+  // tables like Resource.attributes. The referencing attribute_indices fields,
+  // though, do maintain the key uniqueness requirement.
   //
+  // It's recommended to use attributes for variables with bounded cardinality,
+  // such as categorical variables
+  // (https://en.wikipedia.org/wiki/Categorical_variable). Using an attribute of
+  // a floating point type (e.g., CPU time) in a sample can quickly make every
+  // attribute value unique, defeating the purpose of the dictionary and
+  // impractically increasing the profile size.
+  //
+  // Examples of attributes:
   //     "/http/user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36"
-  //     "/http/server_latency": 300
   //     "abc.com/myattribute": true
-  //     "abc.com/score": 10.239
+  //     "allocation_size": 128 bytes
   //
   // The attribute values SHOULD NOT contain empty values.
   // The attribute values SHOULD NOT contain bytes values.