From a97152c66d8f1562fcdcbbb85600d5f12c8aab9e Mon Sep 17 00:00:00 2001
From: Yuri Shkuro <yurishkuro@users.noreply.github.com>
Date: Sun, 14 Jan 2024 14:11:06 -0500
Subject: [PATCH] Replace api_v3.SpansResponseChunk with
 opentelemetry.proto.trace.v1.TracesData (#103)

See https://github.com/jaegertracing/jaeger/pull/5098
---
 proto/api_v3/query_service.proto | 36 +++++++++++++-------------------
 1 file changed, 14 insertions(+), 22 deletions(-)

diff --git a/proto/api_v3/query_service.proto b/proto/api_v3/query_service.proto
index 8a3b0b4..61feed0 100644
--- a/proto/api_v3/query_service.proto
+++ b/proto/api_v3/query_service.proto
@@ -38,17 +38,6 @@ message GetTraceRequest {
   ];
 }
 
-// Response object with spans.
-message SpansResponseChunk {
-  // A list of OpenTelemetry ResourceSpans.
-  // In case of JSON format the ids (trace_id, span_id, parent_id) are encoded in base64 even though OpenTelemetry specification
-  // mandates to use hex encoding [2].
-  // Base64 is chosen to keep compatibility with JSONPb codec.
-  // [1]: https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto
-  // [2]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md#otlphttp
-  repeated opentelemetry.proto.trace.v1.ResourceSpans resource_spans = 1;
-}
-
 // 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.
@@ -118,11 +107,11 @@ service QueryService {
   // It means that the JSON response cannot be directly unmarshalled using JSONPb.
   // This can be fixed by first parsing into user-defined envelope with standard JSON library
   // or string manipulation to remove the envelope. Alternatively generate objects using OpenAPI.
-  rpc GetTrace(GetTraceRequest) returns (stream SpansResponseChunk) {}
+  rpc GetTrace(GetTraceRequest) returns (stream opentelemetry.proto.trace.v1.TracesData) {}
 
   // FindTraces searches for traces.
   // See GetTrace for JSON unmarshalling.
-  rpc FindTraces(FindTracesRequest) returns (stream SpansResponseChunk) {}
+  rpc FindTraces(FindTracesRequest) returns (stream opentelemetry.proto.trace.v1.TracesData) {}
 
   // GetServices returns service names.
   rpc GetServices(GetServicesRequest) returns (GetServicesResponse) {}
@@ -131,10 +120,9 @@ service QueryService {
   rpc GetOperations(GetOperationsRequest) returns (GetOperationsResponse) {}
 }
 
-// Below are some helper types when using APIv3 via HTTP endpoints implemented via grpc-gateway.
+// Below are some helper types when using APIv3 via HTTP endpoints.
 
 // GRPCGatewayError is the type returned when GRPC server returns an error.
-// Note that for streaming responses it would be wrapped in GRPCGatewayWrapper below.
 // Example: {"error":{"grpcCode":2,"httpCode":500,"message":"...","httpStatus":"text..."}}.
 message GRPCGatewayError {
   message GRPCGatewayErrorDetails {
@@ -147,13 +135,17 @@ message GRPCGatewayError {
   GRPCGatewayErrorDetails error = 1;
 }
 
-// GRPCGatewayWrapper is a type returned when GRPC service returns a stream.
-// For some unknown reason grpc-gateway/v1 wraps chunk responses in {"result": {actual output}}.
+// GRPCGatewayWrapper wraps streaming responses from GetTrace/FindTraces for HTTP.
+// Today there is always only one response because internally the HTTP server gets
+// data from QueryService that does not support multiple responses. But in the
+// future the server may return multiple responeses using Transfer-Encoding: chunked.
+// In case of errors, GRPCGatewayError above is used.
+//
+// Example:
+//     {"result": {"resourceSpans": ...}}
+//
 // See https://github.com/grpc-ecosystem/grpc-gateway/issues/2189
-// TODO: it's not clear what happens when the server returns more than one chunk.
-//       The gateway will presumably combine then into a single HTTP response.
-//       Currently this is not possible because even though APIv3 GRPC Service is using output stream,
-//       its implementation reads all spans from QueryService at once and forms only a single chunk.
+//
 message GRPCGatewayWrapper {
-  SpansResponseChunk result = 1;
+  opentelemetry.proto.trace.v1.TracesData result = 1;
 }