query_service.proto

// Copyright (c) 2021 The Jaeger Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package jaeger.api_v3;

import "google/api/annotations.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "opentelemetry/proto/trace/v1/trace.proto";
import "gnostic/openapiv3/annotations.proto";

option go_package = "api_v3";
option java_package = "io.jaegertracing.api_v3";

// Request object to get a trace.
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;

  // 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.
  bool raw_traces = 4;
}

// Query parameters to find traces.
//
// All fields form a conjunction (e.g., "service_name='X' AND operation_name='Y' AND ..."),
// except for `search_depth` and `raw_traces`.
//
// 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 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.
  //
  // The HTTP API expects this as a URL-encoded JSON string map.
  // Example: {"http.status_code":"200","error":"true"}
  map<string, string> attributes = 3 [
    (openapi.v3.property) = {
      type: "string",
      example: { yaml: "'{\"http.status_code\":\"200\"}'" }
    }
  ];

  // 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;

  // 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;

  // 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;

  // 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;

  // 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;

  // 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;
}

// Request object to search traces.
message FindTracesRequest {
  TraceQueryParameters query = 1;
}

// Request object to get service names.
message GetServicesRequest {}

// Response object to get service names.
message GetServicesResponse {
  repeated string services = 1 [(google.api.field_behavior) = REQUIRED];
}

// Request object to get operation names.
message GetOperationsRequest {
  // Required service name.
  string service = 1 [(google.api.field_behavior) = REQUIRED];
  // Optional span kind.
  string span_kind = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Operation encapsulates information about operation.
message Operation {
  string name = 1 [(google.api.field_behavior) = REQUIRED];
  string span_kind = 2 [(google.api.field_behavior) = REQUIRED];
}

// Response object to get operation names.
message GetOperationsResponse {
  repeated Operation operations = 1 [(google.api.field_behavior) = REQUIRED];
}

message GetDependenciesRequest {
  // Required. The start time for the time range to search dependencies.
  google.protobuf.Timestamp start_time = 1;
  // Required. The end time for the time range to search dependencies.
  google.protobuf.Timestamp end_time = 2;
}
    


message DependenciesResponse {
  repeated Dependency dependencies = 1 [(google.api.field_behavior) = REQUIRED];
}

message Dependency {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  string child = 2 [(google.api.field_behavior) = REQUIRED];
  uint64 call_count = 3 [(google.api.field_behavior) = REQUIRED];
}


service QueryService {
  // GetTrace returns a single trace.
  // Note that the JSON response over HTTP is wrapped into result envelope "{"result": ...}"
  // 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 opentelemetry.proto.trace.v1.TracesData) {
    option (google.api.http) = {
      get: "/api/v3/traces/{trace_id}"
    };
  }

  // FindTraces searches for traces.
  // See GetTrace for JSON unmarshalling.
  rpc FindTraces(FindTracesRequest) returns (stream opentelemetry.proto.trace.v1.TracesData) {
    option (google.api.http) = {
      // 1. Primary Binding: GET
      // Maps fields to Query Parameters (e.g., ?query.service_name=foo)
      get: "/api/v3/traces"

      // 2. Secondary Binding: POST
      // Maps the entire JSON body to the request message, e.g.
      // {
      //   "query": {
      //     "service_name": "foo",
      //     "attributes": { "http.status": "200" }
      //   }
      // }
      additional_bindings {
        post: "/api/v3/traces" // You can use the exact same path
        body: "*"              // "*" means "map the whole JSON body to the Request struct"
      }
    };
  }

  // GetServices returns service names.
  rpc GetServices(GetServicesRequest) returns (GetServicesResponse) {
    option (google.api.http) = {
      get: "/api/v3/services"
    };
  }

  // GetOperations returns operation names.
  rpc GetOperations(GetOperationsRequest) returns (GetOperationsResponse) {
    option (google.api.http) = {
      get: "/api/v3/operations"
    };
  }
  rpc GetDependencies(GetDependenciesRequest) returns (DependenciesResponse) {
    option (google.api.http) = {
      get: "/api/v3/dependencies"
    };
  }
}

// Below are some helper types when using APIv3 via HTTP endpoints.

// GRPCGatewayError is the type returned when GRPC server returns an error.
// Example: {"error":{"grpcCode":2,"httpCode":500,"message":"...","httpStatus":"text..."}}.
message GRPCGatewayError {
  message GRPCGatewayErrorDetails {
    int32 grpcCode = 1;
    int32 httpCode = 2;
    string message = 3;
    string httpStatus = 4;
  }

  GRPCGatewayErrorDetails error = 1;
}

// 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
//
message GRPCGatewayWrapper {
  opentelemetry.proto.trace.v1.TracesData result = 1;
}