feat: improve documentation of TraceItemAttributeNames endpoint (#74)

* init

* Update endpoint_trace_item_attributes.proto

proto/sentry_protos/snuba/v1/endpoint_trace_item_attributes.proto

@@ -5,25 +5,30 @@ package sentry_protos.snuba.v1;
 import "sentry_protos/snuba/v1/request_common.proto";
 import "sentry_protos/snuba/v1/trace_item_attribute.proto";
 
-// TraceItemAttributeNamesRequest represents a request for "which queryable attributes are available for these projects between these dates"
-// - used for things like autocompletion
-// EAP does not make a distinction between data stored as columns on a table vs attributes stored
-// dynamically (e.g. tags, contexts, etc). To the user of the interface, they are the same
+// TraceItemAttributeNamesRequest is a request to the TraceItemAttributeNames endpoint,
+// it returns the names of all queryable "TraceItemAttributes" that exist in the given projects,
+// date range, and other filters.
+//
+// TraceItem are things like: span, error, log, replay
+// TraceItemAttributes could be things like: sentry.duration,user_id cart_total, etc.
 message TraceItemAttributeNamesRequest {
+  // metadata about the request
   RequestMeta meta = 1;
+
+  // maximum number of attributes to return
   uint32 limit = 2;
 
-  // use `page_token` instead
+  // offset is deprecated, please use `page_token` instead
   uint32 offset = 3 [deprecated = true];
 
-  // different typed attributes are queried separately
-  // anything other than TYPE_STRING and TYPE_FLOAT will return empty
+  // The type of the attributes to return, must be specified,
+  // only TYPE_STRING and TYPE_FLOAT are supported, anything else will return empty response
   AttributeKey.Type type = 5;
 
-  // filter to only return attribute names that match the given substring
+  // optionalfilter to only return attribute names that match the given substring
   string value_substring_match = 6;
 
-  // optional, used for pagination, the next page token will be returned in the last response
+  // optional, used for pagination, the next page token will be returned in the response
   PageToken page_token = 7;
 }
 

proto/sentry_protos/snuba/v1/request_common.proto

@@ -6,15 +6,32 @@ import "google/protobuf/timestamp.proto";
 import "sentry_protos/snuba/v1/trace_item_filter.proto";
 
 message RequestMeta {
+  // id of the organization we are querying data for
   uint64 organization_id = 1;
+
+  // used for logging and metrics, ex: "snuba_admin", "eap", "replays", etc
   string cogs_category = 2;
+
+  // identifier for where the request is coming from
+  // ex: "api.profiling.landing-chart", "api.replay.details-page"
   string referrer = 3;
-  // can be empty
+
+  // ids of the projects we are querying data for
   repeated uint64 project_ids = 4;
+
+  // start timestamp we want to query data for
   google.protobuf.Timestamp start_timestamp = 5;
+
+  // end timestamp we want to query data for
   google.protobuf.Timestamp end_timestamp = 6;
+
+  // the type of trace item we want to query data for
   TraceItemName trace_item_name = 7;
+
+  // whether to include debug information in the response
   bool debug = 10;
+
+  // a unique identifier for the request, user doesnt need to set this
   string request_id = 11;
 }
 
@@ -32,7 +49,9 @@ enum TraceItemName {
 
 message PageToken {
   oneof value {
+    // standard limit/offset pagination
     uint64 offset = 1;
+
     // Instead of using offset (which requires all the scanning and ordering),
     // the server sends back a filter clause to be added on to the filter conditions
     // which skips the previous results altogether, avoiding extra scanning and sorting