1// Copyright (c) The Thanos Authors.
2// Licensed under the Apache License 2.0.
3
4syntax = "proto3";
5package thanos;
6
7import "store/storepb/types.proto";
8import "gogoproto/gogo.proto";
9import "store/storepb/prompb/types.proto";
10import "store/labelpb/types.proto";
11import "google/protobuf/any.proto";
12
13option go_package = "storepb";
14
15option (gogoproto.sizer_all) = true;
16option (gogoproto.marshaler_all) = true;
17option (gogoproto.unmarshaler_all) = true;
18option (gogoproto.goproto_getters_all) = false;
19
20// Do not generate XXX fields to reduce memory footprint and opening a door
21// for zero-copy casts to/from prometheus data types.
22option (gogoproto.goproto_unkeyed_all) = false;
23option (gogoproto.goproto_unrecognized_all) = false;
24option (gogoproto.goproto_sizecache_all) = false;
25
26/// Store represents API against instance that stores XOR encoded values with label set metadata (e.g Prometheus metrics).
27service Store {
28  /// Info returns meta information about a store e.g labels that makes that store unique as well as time range that is
29  /// available.
30  rpc Info(InfoRequest) returns (InfoResponse);
31
32  /// Series streams each Series (Labels and chunk/downsampling chunk) for given label matchers and time range.
33  ///
34  /// Series should strictly stream full series after series, optionally split by time. This means that a single frame can contain
35  /// partition of the single series, but once a new series is started to be streamed it means that no more data will
36  /// be sent for previous one.
37  /// Series has to be sorted.
38  ///
39  /// There is no requirements on chunk sorting, however it is recommended to have chunk sorted by chunk min time.
40  /// This heavily optimizes the resource usage on Querier / Federated Queries.
41  rpc Series(SeriesRequest) returns (stream SeriesResponse);
42
43  /// LabelNames returns all label names that is available.
44  /// Currently unimplemented in all Thanos implementations, because Query API does not implement this either.
45  rpc LabelNames(LabelNamesRequest) returns (LabelNamesResponse);
46
47  /// LabelValues returns all label values for given label name.
48  rpc LabelValues(LabelValuesRequest) returns (LabelValuesResponse);
49}
50
51/// WriteableStore represents API against instance that stores XOR encoded values with label set metadata (e.g Prometheus metrics).
52service WriteableStore {
53  // WriteRequest allows you to write metrics to this store via remote write
54  rpc RemoteWrite(WriteRequest) returns (WriteResponse) {}
55}
56
57message WriteResponse {
58}
59
60message WriteRequest {
61  repeated prometheus_copy.TimeSeries timeseries = 1 [(gogoproto.nullable) = false];
62  string tenant = 2;
63  int64 replica = 3;
64}
65
66message InfoRequest {}
67
68enum StoreType {
69  UNKNOWN = 0;
70  QUERY = 1;
71  RULE = 2;
72  SIDECAR = 3;
73  STORE = 4;
74  RECEIVE = 5;
75  // DEBUG represents some debug StoreAPI components e.g. thanos tools store-api-serve.
76  DEBUG = 6;
77}
78
79message InfoResponse {
80  // Deprecated. Use label_sets instead.
81  repeated Label labels = 1 [(gogoproto.nullable) = false, (gogoproto.customtype) = "github.com/thanos-io/thanos/pkg/store/labelpb.ZLabel"];
82  int64 min_time = 2;
83  int64 max_time = 3;
84  StoreType storeType  = 4;
85  // label_sets is an unsorted list of `ZLabelSet`s.
86  repeated ZLabelSet label_sets = 5 [(gogoproto.nullable) = false];
87}
88
89message SeriesRequest {
90  int64 min_time                 = 1;
91  int64 max_time                 = 2;
92  repeated LabelMatcher matchers = 3 [(gogoproto.nullable) = false];
93
94  int64 max_resolution_window = 4;
95  repeated Aggr aggregates    = 5;
96
97  // Deprecated. Use partial_response_strategy instead.
98  bool partial_response_disabled = 6;
99
100  // TODO(bwplotka): Move Thanos components to use strategy instead. Including QueryAPI.
101  PartialResponseStrategy partial_response_strategy = 7;
102
103  // skip_chunks controls whether sending chunks or not in series responses.
104  bool skip_chunks = 8;
105
106  // hints is an opaque data structure that can be used to carry additional information.
107  // The content of this field and whether it's supported depends on the
108  // implementation of a specific store.
109  google.protobuf.Any hints = 9;
110}
111
112enum Aggr {
113  RAW     = 0;
114  COUNT   = 1;
115  SUM     = 2;
116  MIN     = 3;
117  MAX     = 4;
118  COUNTER = 5;
119}
120
121message SeriesResponse {
122  oneof result {
123    /// series contains 1 response series. The series labels are sorted by name.
124    Series series = 1;
125
126    /// warning is considered an information piece in place of series for warning purposes.
127    /// It is used to warn store API user about suspicious cases or partial response (if enabled).
128    string warning = 2;
129
130    /// hints is an opaque data structure that can be used to carry additional information from
131    /// the store. The content of this field and whether it's supported depends on the
132    /// implementation of a specific store. It's also implementation specific if it's allowed that
133    /// multiple SeriesResponse frames contain hints for a single Series() request and how should they
134    /// be handled in such case (ie. merged vs keep the first/last one).
135    google.protobuf.Any hints = 3;
136  }
137}
138
139message LabelNamesRequest {
140  bool partial_response_disabled = 1;
141
142  // TODO(bwplotka): Move Thanos components to use strategy instead. Including QueryAPI.
143  PartialResponseStrategy partial_response_strategy = 2;
144
145  int64 start = 3;
146
147  int64 end = 4;
148
149  // hints is an opaque data structure that can be used to carry additional information.
150  // The content of this field and whether it's supported depends on the
151  // implementation of a specific store.
152  google.protobuf.Any hints = 5;
153}
154
155message LabelNamesResponse {
156  repeated string names    = 1;
157  repeated string warnings = 2;
158
159  /// hints is an opaque data structure that can be used to carry additional information from
160  /// the store. The content of this field and whether it's supported depends on the
161  /// implementation of a specific store.
162  google.protobuf.Any hints = 3;
163}
164
165message LabelValuesRequest {
166  string label = 1;
167
168  bool partial_response_disabled = 2;
169
170  // TODO(bwplotka): Move Thanos components to use strategy instead. Including QueryAPI.
171  PartialResponseStrategy partial_response_strategy = 3;
172
173  int64 start = 4;
174
175  int64 end = 5;
176
177  // hints is an opaque data structure that can be used to carry additional information.
178  // The content of this field and whether it's supported depends on the
179  // implementation of a specific store.
180  google.protobuf.Any hints = 6;
181
182  repeated LabelMatcher matchers = 7 [(gogoproto.nullable) = false];
183}
184
185message LabelValuesResponse {
186  repeated string values   = 1;
187  repeated string warnings = 2;
188
189  /// hints is an opaque data structure that can be used to carry additional information from
190  /// the store. The content of this field and whether it's supported depends on the
191  /// implementation of a specific store.
192  google.protobuf.Any hints = 3;
193}
194