|
| 1 | +syntax = "proto3"; |
| 2 | + |
| 3 | +package jaeger.storage.v2; |
| 4 | + |
| 5 | +import "google/protobuf/duration.proto"; |
| 6 | +import "google/protobuf/timestamp.proto"; |
| 7 | +import "opentelemetry/proto/trace/v1/trace.proto"; |
| 8 | + |
| 9 | +option go_package = "storage"; |
| 10 | + |
| 11 | +// GetTraceParams represents the query for a single trace from the storage backend. |
| 12 | +message GetTraceParams { |
| 13 | + // trace_id is a 16 byte array containing the unique identifier for the trace to query. |
| 14 | + bytes trace_id = 1; |
| 15 | + |
| 16 | + // start_time is the start of the time interval to search for the trace_id. |
| 17 | + // |
| 18 | + // This field is optional. |
| 19 | + google.protobuf.Timestamp start_time = 2; |
| 20 | + |
| 21 | + // end_time is the end of the time interval to search for the trace_id. |
| 22 | + // |
| 23 | + // This field is optional. |
| 24 | + google.protobuf.Timestamp end_time = 3; |
| 25 | +} |
| 26 | + |
| 27 | +// GetTracesRequest represents a request to retrieve multiple traces. |
| 28 | +message GetTracesRequest { |
| 29 | + repeated GetTraceParams query = 1; |
| 30 | +} |
| 31 | + |
| 32 | +// GetServicesRequest represents a request to get service names. |
| 33 | +message GetServicesRequest {} |
| 34 | + |
| 35 | +// GetServicesResponse represents the response for GetServicesRequest. |
| 36 | +message GetServicesResponse { |
| 37 | + repeated string services = 1; |
| 38 | +} |
| 39 | + |
| 40 | +// GetOperationsRequest represents a request to get operation names. |
| 41 | +message GetOperationsRequest { |
| 42 | + // service is the name of the service for which to get operation names. |
| 43 | + // |
| 44 | + // This field is required. |
| 45 | + string service = 1; |
| 46 | + |
| 47 | + // span_kind is the type of span which is used to distinguish between |
| 48 | + // spans generated in a particular context. |
| 49 | + // |
| 50 | + // This field is optional. |
| 51 | + string span_kind = 2; |
| 52 | +} |
| 53 | + |
| 54 | +// Operation contains information about an operation for a given service. |
| 55 | +message Operation { |
| 56 | + string name = 1; |
| 57 | + string span_kind = 2; |
| 58 | +} |
| 59 | + |
| 60 | +// GetOperationsResponse represents the response for GetOperationsRequest. |
| 61 | +message GetOperationsResponse { |
| 62 | + repeated Operation operations = 1; |
| 63 | +} |
| 64 | + |
| 65 | +// KeyValue and all its associated types are copied from opentelemetry-proto/common/v1/common.proto |
| 66 | +// (https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/common/v1/common.proto). |
| 67 | +// This type is used to store attributes in traces. |
| 68 | +message KeyValue { |
| 69 | + string key = 1; |
| 70 | + AnyValue value = 2; |
| 71 | +} |
| 72 | + |
| 73 | +message AnyValue { |
| 74 | + oneof value { |
| 75 | + string string_value = 1; |
| 76 | + bool bool_value = 2; |
| 77 | + int64 int_value = 3; |
| 78 | + double double_value = 4; |
| 79 | + ArrayValue array_value = 5; |
| 80 | + KeyValueList kvlist_value = 6; |
| 81 | + bytes bytes_value = 7; |
| 82 | + } |
| 83 | +} |
| 84 | + |
| 85 | +message KeyValueList { |
| 86 | + repeated KeyValue values = 1; |
| 87 | +} |
| 88 | + |
| 89 | +message ArrayValue { |
| 90 | + repeated AnyValue values = 1; |
| 91 | +} |
| 92 | + |
| 93 | +// TraceQueryParameters contains query parameters to find traces. For a detailed |
| 94 | +// definition of each field in this message, refer to `TraceQueryParameters` in `jaeger.api_v3` |
| 95 | +// (https://github.com/jaegertracing/jaeger-idl/blob/main/proto/api_v3/query_service.proto). |
| 96 | +message TraceQueryParameters { |
| 97 | + string service_name = 1; |
| 98 | + string operation_name = 2; |
| 99 | + repeated KeyValue attributes = 3; |
| 100 | + google.protobuf.Timestamp start_time_min = 4; |
| 101 | + google.protobuf.Timestamp start_time_max = 5; |
| 102 | + google.protobuf.Duration duration_min = 6; |
| 103 | + google.protobuf.Duration duration_max = 7; |
| 104 | + int32 search_depth = 8; |
| 105 | +} |
| 106 | + |
| 107 | +// FindTracesRequest represents a request to find traces. |
| 108 | +// It can be used to retrieve the traces (FindTraces) or simply |
| 109 | +// the trace IDs (FindTraceIDs). |
| 110 | +message FindTracesRequest { |
| 111 | + TraceQueryParameters query = 1; |
| 112 | +} |
| 113 | + |
| 114 | +// FoundTraceID is a wrapper around trace ID returned from FindTraceIDs |
| 115 | +// with an optional time range that may be used in GetTraces calls. |
| 116 | +// |
| 117 | +// The time range is provided as an optimization hint for some storage backends |
| 118 | +// that can perform more efficient queries when they know the approximate time range. |
| 119 | +// The value should not be used for precise time-based filtering or assumptions. |
| 120 | +// It is meant as a rough boundary and may not be populated in all cases. |
| 121 | +message FoundTraceID { |
| 122 | + bytes trace_id = 1; |
| 123 | + google.protobuf.Timestamp start = 2; |
| 124 | + google.protobuf.Timestamp end = 3; |
| 125 | +} |
| 126 | + |
| 127 | +// FindTraceIDsResponse represents the response for FindTracesRequest. |
| 128 | +message FindTraceIDsResponse { |
| 129 | + repeated FoundTraceID trace_ids = 1; |
| 130 | +} |
| 131 | + |
| 132 | +// TraceReader is a service that allows reading traces from storage. |
| 133 | +// Note that if you implement this service, you should also implement |
| 134 | +// OTEL's TraceService in package opentelemetry.proto.collector.trace.v1 |
| 135 | +// to allow pushing traces to the storage backend |
| 136 | +// (https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/trace/v1/trace_service.proto) |
| 137 | +service TraceReader { |
| 138 | + // GetTraces returns a stream that retrieves all traces with given IDs. |
| 139 | + // |
| 140 | + // Chunking requirements: |
| 141 | + // - A single TracesData chunk MUST NOT contain spans from multiple traces. |
| 142 | + // - Large traces MAY be split across multiple, *consecutive* TracesData chunks. |
| 143 | + // - Each returned TracesData object MUST NOT be empty. |
| 144 | + // |
| 145 | + // Edge cases: |
| 146 | + // - If no spans are found for any given trace ID, the ID is ignored. |
| 147 | + // - If none of the trace IDs are found in the storage, an empty response is returned. |
| 148 | + rpc GetTraces(GetTracesRequest) returns (stream opentelemetry.proto.trace.v1.TracesData) {} |
| 149 | + |
| 150 | + // GetServices returns all service names known to the backend from traces |
| 151 | + // within its retention period. |
| 152 | + rpc GetServices(GetServicesRequest) returns (GetServicesResponse) {} |
| 153 | + |
| 154 | + // GetOperations returns all operation names for a given service |
| 155 | + // known to the backend from traces within its retention period. |
| 156 | + rpc GetOperations(GetOperationsRequest) returns (GetOperationsResponse) {} |
| 157 | + |
| 158 | + // FindTraces returns a stream that retrieves traces matching query parameters. |
| 159 | + // |
| 160 | + // The chunking rules are the same as for GetTraces. |
| 161 | + // |
| 162 | + // If no matching traces are found, an empty stream is returned. |
| 163 | + rpc FindTraces(FindTracesRequest) returns (stream opentelemetry.proto.trace.v1.TracesData) {} |
| 164 | + |
| 165 | + // FindTraceIDs returns a stream that retrieves IDs of traces matching query parameters. |
| 166 | + // |
| 167 | + // If no matching traces are found, an empty stream is returned. |
| 168 | + // |
| 169 | + // This call behaves identically to FindTraces, except that it returns only the list |
| 170 | + // of matching trace IDs. This is useful in some contexts, such as batch jobs, where a |
| 171 | + // large list of trace IDs may be queried first and then the full traces are loaded |
| 172 | + // in batches. |
| 173 | + rpc FindTraceIDs(FindTracesRequest) returns (FindTraceIDsResponse) {} |
| 174 | +} |
0 commit comments