feat: improve docs of AttributeValues and Timeseries endpoint

proto/sentry_protos/snuba/v1/endpoint_time_series.proto

@@ -7,37 +7,79 @@ import "sentry_protos/snuba/v1/request_common.proto";
 import "sentry_protos/snuba/v1/trace_item_attribute.proto";
 import "sentry_protos/snuba/v1/trace_item_filter.proto";
 
+// This is a request to the TimeSeries endpoint,
+// it is used to do a timeseries aggregation of a given attribute
+// across traces.
+//
+// ex: avg(span.duration) group by db.system
+// this (conceptually) will return a 2d graph where y-axis is avg(span.duration),
+// x-axis is time, and there is a separate line/function on the graph for each db.system value
 message TimeSeriesRequest {
+  // metadata about the request
+  // used to filter time range, organization, project, etc.
   RequestMeta meta = 1;
+
+  // filters out spans (TraceItems) that dont meet the criteria
+  // ex: avg(span.duration) where span.environment = 'production'
   TraceItemFilter filter = 2;
+
+  // the actual aggregation to compute ex: avg(span.duration)
   repeated AttributeAggregation aggregations = 3;
+
+  // the level of detail in the timeseries graph,
+  // low granularity is very detailed, high is less detail.
+  // ex: if granularity is 1s you will have a data point every 1s,
+  //     if its 1m you have a data point every 1m
+  // tip: for performance, if the query is is over a large time period you should
+  //  have high granularity
   uint64 granularity_secs = 4;
+
+  // attribute key to group by
+  // ex: span.environment might give 3 timeseries lines,
+  //     one for prod, one for dev etc
   repeated AttributeKey group_by = 5;
 }
 
 message DataPoint {
   float data = 1;
-  // optional, if not set, assume true. Accounts for sparse time series
+
+  // false if this datapoint is empty, true otherwise.
+  // optional, if not set assume true.
+  // used for sparse time series
   bool data_present = 2;
+
+  // only set for extrapolated data points, 0 otherwise
+  // the extrapolated avg sampling rate for this data point
   float avg_sampling_rate = 3;
+
+  // deprecated
   bool is_reliable = 4 [deprecated = true];
-  // determines the reliability of the aggregation using math based on confidence intervals and sample size
+
+  // the reliability of the data value based on math based on confidence intervals and sample size
   Reliability reliability = 5;
 }
 
 message TimeSeries {
   string label = 1;
+
   // the names and values of the attribute keys which
   // were in the group by
   map<string, string> group_by_attributes = 2;
+
   // time bucket for each data point in the timeseries
   repeated google.protobuf.Timestamp buckets = 3;
+
   repeated DataPoint data_points = 4;
+
   // number of events used to calculate this timeseries
   uint64 num_events = 5;
+
+  // deprecated
   float avg_sampling_rate = 6 [deprecated = true];
 }
 
+// This is the response from the TimeSeries endpoint,
+// it is the counterpart of TimeSeriesRequest
 message TimeSeriesResponse {
   repeated TimeSeries result_timeseries = 1;
   ResponseMeta meta = 5;

proto/sentry_protos/snuba/v1/endpoint_trace_item_attributes.proto

@@ -13,6 +13,7 @@ import "sentry_protos/snuba/v1/trace_item_attribute.proto";
 // TraceItemAttributes could be things like: sentry.duration,user_id cart_total, etc.
 message TraceItemAttributeNamesRequest {
   // metadata about the request
+  // this is where you specify organization, project, time range etc.
   RequestMeta meta = 1;
 
   // maximum number of attributes to return
@@ -32,34 +33,61 @@ message TraceItemAttributeNamesRequest {
   PageToken page_token = 7;
 }
 
+// TraceItemAttributeNamesResponse is the response returned by the TraceItemAttributeNames endpoint.
+// It is the counterpart to TraceItemAttributeNamesRequest.
 message TraceItemAttributeNamesResponse {
   message Attribute {
     string name = 1;
     AttributeKey.Type type = 2;
   }
+  // all attributes that matched the filters in the request
   repeated Attribute attributes = 1;
 
   // page token for the next page of results
   PageToken page_token = 2;
 
+  // metadata about the response
   ResponseMeta meta = 3;
 }
 
+// TraceItemAttributeValuesRequest is a request to the TraceItemAttributeValues endpoint,
+// it returns the set of all possible values for the given attribute key, across the given
+// organization, project_id, timerange etc (specified in meta).
+//
 // This endpoint only supports string values, it does not make sense
 // to get all the possible values of a numerical attribute
 message TraceItemAttributeValuesRequest {
+  // metadata about the request
+  // this is where you specify organization, project, time range etc.
   RequestMeta meta = 1;
+
+  // attribute you want the values of
   AttributeKey key = 2;
-  string name = 3 [deprecated = true]; //  use the `key` field instead, for API consistency
-  // a substring of the value being searched,
+
+  // depricated, please use the `key` field instead
+  string name = 3 [deprecated = true];
+
+  // a substring of the value being searched for,
+  // only values matching this substring will be returned.
   // only strict substring supported, no regex
   string value_substring_match = 4;
+
+  // max number of values to return
   uint32 limit = 5;
+
+  // optional, used for pagination, the next page token will be returned in the response
   PageToken page_token = 6;
 }
 
+// TraceItemAttributeValuesResponse is a response from the TraceItemAttributeValues endpoint
+// it is the counterpart to TraceItemAttributesRequest
 message TraceItemAttributeValuesResponse {
+  // all the values that matched the criteria specified in the request
   repeated string values = 1;
+
+  // page token for the next page of results
   PageToken page_token = 6;
+
+  // metadata about the response
   ResponseMeta meta = 7;
 }

proto/sentry_protos/snuba/v1/request_common.proto

@@ -36,7 +36,9 @@ message RequestMeta {
 }
 
 message ResponseMeta {
+  // id of the request that this response relates to
   string request_id = 1;
+
   // Optional field that is included only if debug is true
   repeated QueryInfo query_info = 2;
 }

proto/sentry_protos/snuba/v1/trace_item_filter.proto

@@ -39,8 +39,14 @@ message ExistsFilter {
   AttributeKey key = 1;
 }
 
-// Represents a condition on searching for a particular "trace item"
-// (e.g., spans, replays, errors)
+// a condition used to filter for matching "trace items"
+//
+// ex: "exists span.duration" would mean
+// "only give me trace items that have the attribute 'span.duration'"
+//
+// ( traces contain trace items,
+//   eg. trace items are: span, replay, error, etc,
+//   trace items contain attributes like 'span.duration' )
 message TraceItemFilter {
   oneof value {
     AndFilter and_filter = 1;