Merge branch 'main' into optinal-time-window-when-fetching-trace-by-id

Signed-off-by: Zhang Xin <[email protected]>

proto/api_v3/query_service.proto

@@ -27,8 +27,10 @@ option java_package = "io.jaegertracing.api_v3";
 message GetTraceRequest {
   // Hex encoded 64 or 128 bit trace ID.
   string trace_id = 1;
+
   // Optional. The start time to search trace ID.
   google.protobuf.Timestamp start_time = 2;
+
   // Optional. The end time to search trace ID.
   google.protobuf.Timestamp end_time = 3;
 }
@@ -48,20 +50,28 @@ message GetTraceRequest {
 message TraceQueryParameters {
   string service_name = 1;
   string operation_name = 2;
+
   // Attributes are matched against Span and Resource attributes.
   // At least one span in a trace must match all specified attributes.
   map<string, string> attributes = 3;
+
   // Span min start time in. REST API uses RFC-3339ns format. Required.
   google.protobuf.Timestamp start_time_min = 4;
+
   // Span max start time. REST API uses RFC-3339ns format. Required.
   google.protobuf.Timestamp start_time_max = 5;
+
   // Span min duration. REST 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.
   google.protobuf.Duration duration_max = 7;
 
-  // Maximum number of traces in the response.
-  int32 num_traces = 8;
+  // 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.
+  int32 search_depth = 8;
 }
 
 // Request object to search traces.

swagger/api_v3/query_service.swagger.json

@@ -126,8 +126,8 @@
             "type": "string"
           },
           {
-            "name": "query.num_traces",
-            "description": "Maximum number of traces in the response.",
+            "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.",
             "in": "query",
             "required": false,
             "type": "integer",
@@ -350,10 +350,10 @@
           "type": "string",
           "description": "Span max duration. REST API uses Golang's time format e.g. 10s."
         },
-        "num_traces": {
+        "search_depth": {
           "type": "integer",
           "format": "int32",
-          "description": "Maximum number of traces in the response."
+          "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": "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."