[chore] Update documentation in query_service.proto (#149)

## Which problem is this PR solving?
- Towards jaegertracing/jaeger#6629

## Description of the changes
- Cleans up `query_service.proto` to improve the documentation so that
it can be re-used for the remote storage API v2

## How was this change tested?
- CI

## Checklist
- [x] I have read
https://github.com/jaegertracing/jaeger/blob/master/CONTRIBUTING_GUIDELINES.md
- [x] I have signed all commits
- [x] I have added unit tests for the new functionality
- [x] I have run lint and test steps successfully
  - for `jaeger`: `make lint test`
  - for `jaeger-ui`: `npm run lint` and `npm run test`

---------

Signed-off-by: Mahad Zaryab <[email protected]>

Author: mahadzaryab1

proto/api_v3/query_service.proto

@@ -12,13 +12,13 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-syntax="proto3";
+syntax = "proto3";
 
 package jaeger.api_v3;
 
-import "opentelemetry/proto/trace/v1/trace.proto";
-import "google/protobuf/timestamp.proto";
 import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
+import "opentelemetry/proto/trace/v1/trace.proto";
 
 option go_package = "api_v3";
 option java_package = "io.jaegertracing.api_v3";
@@ -40,47 +40,64 @@ message GetTraceRequest {
   bool raw_traces = 4;
 }
 
-// Query parameters to find traces. Except for num_traces, all fields should be treated
-// as forming a conjunction, e.g., "service_name='X' AND operation_name='Y' AND ...".
-// All fields are matched against individual spans, not at the trace level.
-// The returned results contain traces where at least one span matches the conditions.
-// When num_traces results in fewer traces returned, there is no required ordering.
+// Query parameters to find traces.
 //
-// Note: num_traces should restrict the number of traces returned, but not all backends
-// interpret it this way. For instance, in Cassandra this limits the number of _spans_
-// that match the conditions, and the resulting number of traces can be less.
+// All fields form a conjunction (e.g., "service_name='X' AND operation_name='Y' AND ..."),
+// except for `search_depth` and `raw_traces`.
 //
-// Note: some storage implementations do not guarantee the correct implementation of all parameters.
+// Fields are matched against individual spans, not the trace level. The results include
+// traces with at least one matching span.
 //
+// The results have no guaranteed ordering.
 message TraceQueryParameters {
+  // service_name filters spans generated by a specific service.
   string service_name = 1;
+
+  // operation_name filters spans by a specific operation / span name.
   string operation_name = 2;
 
-  // Attributes are matched against Span and Resource attributes.
-  // At least one span in a trace must match all specified attributes.
+  // attributes contains key-value pairs where the key is the attribute name
+  // and the value is its string representation. Attributes are matched against
+  // span and resource attributes. At least one span must match all specified attributes.
   map<string, string> attributes = 3;
 
-  // Span min start time in. REST API uses RFC-3339ns format. Required.
+  // start_time_min is the start of the time interval (inclusive) for the query.
+  // Only traces with spans that started on or after this time will be returned.
+  //
+  // The HTTP API uses RFC-3339ns format.
+  //
+  // This field is required.
   google.protobuf.Timestamp start_time_min = 4;
 
-  // Span max start time. REST API uses RFC-3339ns format. Required.
+  // start_time_max is the end of the time interval (exclusive) for the query.
+  // Only traces with spans that started before this time will be returned.
+  //
+  // The HTTP API uses RFC-3339ns format.
+  //
+  // This field is required.
   google.protobuf.Timestamp start_time_max = 5;
 
-  // Span min duration. REST API uses Golang's time format e.g. 10s.
+  // duration_min is the minimum duration of a span in the trace.
+  // Only traces with spans that lasted at least this long will be returned.
+  //
+  // The HTTP API uses Golang's time format (e.g., "10s").
   google.protobuf.Duration duration_min = 6;
 
-  // Span max duration. REST API uses Golang's time format e.g. 10s.
+  // duration_max is the maximum duration of a span in the trace.
+  // Only traces with spans that lasted at most this long will be returned.
+  //
+  // The HTTP API uses Golang's time format (e.g., "10s").
   google.protobuf.Duration duration_max = 7;
 
-  // Maximum depth of search. Depending on the backend storage
-  // implementtaion this could be like a regular LIMIT clause in SQL,
-  // but not all implementations support such accuracy and for those
-  // the larger depth value simply means more traces returned.
+  // search_depth defines the maximum search depth. Depending on the backend storage implementation,
+  // this may behave like an SQL `LIMIT` clause. However, some implementations might not support
+  // precise limits, and a larger value generally results in more traces being returned.
   int32 search_depth = 8;
 
-  // Optional. If set to true, the response will not include any
-  // enrichments to the trace, such as clock skew adjustment.
-  // Instead, the trace will be returned exactly as stored.
+  // If set to true, the response will exclude any enrichments to the trace, such as clock skew adjustments.
+  // The trace will be returned exactly as stored.
+  //
+  // This field is optional.
   bool raw_traces = 9;
 }
 

swagger/api_v3/query_service.swagger.json

@@ -85,57 +85,59 @@
         "parameters": [
           {
             "name": "query.service_name",
+            "description": "service_name filters spans generated by a specific service.",
             "in": "query",
             "required": false,
             "type": "string"
           },
           {
             "name": "query.operation_name",
+            "description": "operation_name filters spans by a specific operation / span name.",
             "in": "query",
             "required": false,
             "type": "string"
           },
           {
             "name": "query.start_time_min",
-            "description": "Span min start time in. REST API uses RFC-3339ns format. Required.",
+            "description": "start_time_min is the start of the time interval (inclusive) for the query.\nOnly traces with spans that started on or after this time will be returned.\n\nThe HTTP API uses RFC-3339ns format.\n\nThis field is required.",
             "in": "query",
             "required": false,
             "type": "string",
             "format": "date-time"
           },
           {
             "name": "query.start_time_max",
-            "description": "Span max start time. REST API uses RFC-3339ns format. Required.",
+            "description": "start_time_max is the end of the time interval (exclusive) for the query.\nOnly traces with spans that started before this time will be returned.\n\nThe HTTP API uses RFC-3339ns format.\n\nThis field is required.",
             "in": "query",
             "required": false,
             "type": "string",
             "format": "date-time"
           },
           {
             "name": "query.duration_min",
-            "description": "Span min duration. REST API uses Golang's time format e.g. 10s.",
+            "description": "duration_min is the minimum duration of a span in the trace.\nOnly traces with spans that lasted at least this long will be returned.\n\nThe HTTP API uses Golang's time format (e.g., \"10s\").",
             "in": "query",
             "required": false,
             "type": "string"
           },
           {
             "name": "query.duration_max",
-            "description": "Span max duration. REST API uses Golang's time format e.g. 10s.",
+            "description": "duration_max is the maximum duration of a span in the trace.\nOnly traces with spans that lasted at most this long will be returned.\n\nThe HTTP API uses Golang's time format (e.g., \"10s\").",
             "in": "query",
             "required": false,
             "type": "string"
           },
           {
             "name": "query.search_depth",
-            "description": "Maximum depth of search. Depending on the backend storage\nimplementtaion this could be like a regular LIMIT clause in SQL,\nbut not all implementations support such accuracy and for those\nthe larger depth value simply means more traces returned.",
+            "description": "search_depth defines the maximum search depth. Depending on the backend storage implementation,\nthis may behave like an SQL `LIMIT` clause. However, some implementations might not support\nprecise limits, and a larger value generally results in more traces being returned.",
             "in": "query",
             "required": false,
             "type": "integer",
             "format": "int32"
           },
           {
             "name": "query.raw_traces",
-            "description": "Optional. If set to true, the response will not include any\nenrichments to the trace, such as clock skew adjustment.\nInstead, the trace will be returned exactly as stored.",
+            "description": "If set to true, the response will exclude any enrichments to the trace, such as clock skew adjustments.\nThe trace will be returned exactly as stored.\n\nThis field is optional.",
             "in": "query",
             "required": false,
             "type": "boolean"
@@ -334,47 +336,49 @@
       "type": "object",
       "properties": {
         "service_name": {
-          "type": "string"
+          "type": "string",
+          "description": "service_name filters spans generated by a specific service."
         },
         "operation_name": {
-          "type": "string"
+          "type": "string",
+          "description": "operation_name filters spans by a specific operation / span name."
         },
         "attributes": {
           "type": "object",
           "additionalProperties": {
             "type": "string"
           },
-          "description": "Attributes are matched against Span and Resource attributes.\nAt least one span in a trace must match all specified attributes."
+          "description": "attributes contains key-value pairs where the key is the attribute name\nand the value is its string representation. Attributes are matched against\nspan and resource attributes. At least one span must match all specified attributes."
         },
         "start_time_min": {
           "type": "string",
           "format": "date-time",
-          "description": "Span min start time in. REST API uses RFC-3339ns format. Required."
+          "description": "start_time_min is the start of the time interval (inclusive) for the query.\nOnly traces with spans that started on or after this time will be returned.\n\nThe HTTP API uses RFC-3339ns format.\n\nThis field is required."
         },
         "start_time_max": {
           "type": "string",
           "format": "date-time",
-          "description": "Span max start time. REST API uses RFC-3339ns format. Required."
+          "description": "start_time_max is the end of the time interval (exclusive) for the query.\nOnly traces with spans that started before this time will be returned.\n\nThe HTTP API uses RFC-3339ns format.\n\nThis field is required."
         },
         "duration_min": {
           "type": "string",
-          "description": "Span min duration. REST API uses Golang's time format e.g. 10s."
+          "description": "duration_min is the minimum duration of a span in the trace.\nOnly traces with spans that lasted at least this long will be returned.\n\nThe HTTP API uses Golang's time format (e.g., \"10s\")."
         },
         "duration_max": {
           "type": "string",
-          "description": "Span max duration. REST API uses Golang's time format e.g. 10s."
+          "description": "duration_max is the maximum duration of a span in the trace.\nOnly traces with spans that lasted at most this long will be returned.\n\nThe HTTP API uses Golang's time format (e.g., \"10s\")."
         },
         "search_depth": {
           "type": "integer",
           "format": "int32",
-          "description": "Maximum depth of search. Depending on the backend storage\nimplementtaion this could be like a regular LIMIT clause in SQL,\nbut not all implementations support such accuracy and for those\nthe larger depth value simply means more traces returned."
+          "description": "search_depth defines the maximum search depth. Depending on the backend storage implementation,\nthis may behave like an SQL `LIMIT` clause. However, some implementations might not support\nprecise limits, and a larger value generally results in more traces being returned."
         },
         "raw_traces": {
           "type": "boolean",
-          "description": "Optional. If set to true, the response will not include any\nenrichments to the trace, such as clock skew adjustment.\nInstead, the trace will be returned exactly as stored."
+          "description": "If set to true, the response will exclude any enrichments to the trace, such as clock skew adjustments.\nThe trace will be returned exactly as stored.\n\nThis field is optional."
         }
       },
-      "description": "Query parameters to find traces. Except for num_traces, all fields should be treated\nas forming a conjunction, e.g., \"service_name='X' AND operation_name='Y' AND ...\".\nAll fields are matched against individual spans, not at the trace level.\nThe returned results contain traces where at least one span matches the conditions.\nWhen num_traces results in fewer traces returned, there is no required ordering.\n\nNote: num_traces should restrict the number of traces returned, but not all backends\ninterpret it this way. For instance, in Cassandra this limits the number of _spans_\nthat match the conditions, and the resulting number of traces can be less.\n\nNote: some storage implementations do not guarantee the correct implementation of all parameters."
+      "description": "Query parameters to find traces.\n\nAll fields form a conjunction (e.g., \"service_name='X' AND operation_name='Y' AND ...\"),\nexcept for `search_depth` and `raw_traces`.\n\nFields are matched against individual spans, not the trace level. The results include\ntraces with at least one matching span.\n\nThe results have no guaranteed ordering."
     },
     "protobufAny": {
       "type": "object",