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 "store/labelpb/types.proto";
9import "gogoproto/gogo.proto";
10import "google/protobuf/timestamp.proto";
11
12option go_package = "rulespb";
13
14option (gogoproto.sizer_all) = true;
15option (gogoproto.marshaler_all) = true;
16option (gogoproto.unmarshaler_all) = true;
17option (gogoproto.goproto_getters_all) = false;
18
19// Do not generate XXX fields to reduce memory footprint and opening a door
20// for zero-copy casts to/from prometheus data types.
21option (gogoproto.goproto_unkeyed_all) = false;
22option (gogoproto.goproto_unrecognized_all) = false;
23option (gogoproto.goproto_sizecache_all) = false;
24
25/// Rules represents API that is responsible for gathering rules and their statuses.
26service Rules {
27    /// Rules has info for all rules.
28    /// Returned rules are expected to include external labels.
29    rpc Rules(RulesRequest) returns (stream RulesResponse);
30}
31
32message RulesRequest {
33    enum Type {
34        ALL = 0;
35        /// This will make sure strings.ToLower(.String()) will match 'alert' and 'record' values for
36        /// Prometheus HTTP API.
37        /// NOTE: The implementation has to return empty rule groups as well.
38        ALERT  = 1;
39        RECORD = 2;
40    }
41    Type type = 1;
42    PartialResponseStrategy partial_response_strategy = 2;
43}
44
45message RulesResponse {
46    oneof result {
47        /// group for rule groups. It is up to server implementation to decide how many of those to put here within single frame.
48        RuleGroup group = 1;
49
50        /// warning is considered an information piece in place of series for warning purposes.
51        /// It is used to warn rule API users about suspicious cases or partial response (if enabled).
52        string warning = 2;
53    }
54}
55
56
57/// RuleGroups is set of rule groups.
58/// This and below APIs are meant to be used for unmarshaling and marshsaling rules from/to Prometheus API.
59/// That's why json tag has to be customized and matching https://github.com/prometheus/prometheus/blob/c530b4b456cc5f9ec249f771dff187eb7715dc9b/web/api/v1/api.go#L955
60/// NOTE: See rules_custom_test.go for compatibility tests.
61///
62/// For rule parsing from YAML configuration other struct is used: https://github.com/prometheus/prometheus/blob/20b1f596f6fb16107ef0c244d240b0ad6da36829/pkg/rulefmt/rulefmt.go#L105
63message RuleGroups {
64    repeated RuleGroup groups = 1 [(gogoproto.jsontag) = "groups" ];
65}
66
67/// RuleGroup has info for rules which are part of a group.
68message RuleGroup {
69    string name                               = 1 [(gogoproto.jsontag) = "name" ];
70    string file                               = 2 [(gogoproto.jsontag) = "file" ];
71    repeated Rule rules                       = 3 [(gogoproto.jsontag) = "rules" ];
72    double interval                           = 4 [(gogoproto.jsontag) = "interval" ];
73    double evaluation_duration_seconds        = 5 [(gogoproto.jsontag) = "evaluationTime" ]; // TODO: Is it really second?
74    google.protobuf.Timestamp last_evaluation = 6 [(gogoproto.jsontag) = "lastEvaluation", (gogoproto.stdtime) = true, (gogoproto.nullable) = false ];
75
76    // Thanos specific.
77    PartialResponseStrategy PartialResponseStrategy = 8 [(gogoproto.jsontag) = "partialResponseStrategy" ];
78}
79
80message Rule {
81    oneof result {
82        RecordingRule recording = 1;
83        Alert alert= 2;
84    }
85}
86
87/// AlertState represents state of the alert. Has to match 1:1 Prometheus AlertState:
88//
89// StateInactive is the state of an alert that is neither firing nor pending.
90//StateInactive AlertState = iota
91// StatePending is the state of an alert that has been active for less than
92// the configured threshold duration.
93//StatePending
94// StateFiring is the state of an alert that has been active for longer than
95// the configured threshold duration.
96//StateFiring
97enum AlertState {
98    INACTIVE            = 0;
99    PENDING             = 1;
100    FIRING              = 2;
101}
102
103message AlertInstance {
104    ZLabelSet labels                     = 1 [(gogoproto.jsontag) = "labels", (gogoproto.nullable) = false ];
105    ZLabelSet annotations                = 2 [(gogoproto.jsontag) = "annotations", (gogoproto.nullable) = false ];
106    AlertState state                     = 3 [(gogoproto.jsontag) = "state" ];
107    google.protobuf.Timestamp active_at  = 4 [(gogoproto.jsontag) = "activeAt,omitempty", (gogoproto.stdtime) = true];
108    string value                         = 5 [(gogoproto.jsontag) = "value" ];
109
110    // Thanos specific. Used mainly for alert API purposes.
111    PartialResponseStrategy PartialResponseStrategy = 6 [(gogoproto.jsontag) = "partialResponseStrategy" ];
112}
113
114message Alert {
115    /// state returns the maximum state of alert instances for this rule.
116    AlertState state                          = 1 [(gogoproto.jsontag) = "state" ];
117    string name                               = 2 [(gogoproto.jsontag) = "name" ];
118    string query                              = 3 [(gogoproto.jsontag) = "query" ];
119    double duration_seconds                   = 4 [(gogoproto.jsontag) = "duration" ];
120    ZLabelSet labels                          = 5 [(gogoproto.jsontag) = "labels", (gogoproto.nullable) = false ];
121    ZLabelSet annotations                     = 6 [(gogoproto.jsontag) = "annotations", (gogoproto.nullable) = false ];
122    repeated AlertInstance alerts             = 7 [(gogoproto.jsontag) = "alerts" ];
123    string health                             = 8 [(gogoproto.jsontag) = "health" ];
124    string last_error                         = 9 [(gogoproto.jsontag) = "lastError,omitempty" ];
125    double evaluation_duration_seconds        = 10 [(gogoproto.jsontag) = "evaluationTime" ];
126    google.protobuf.Timestamp last_evaluation = 11 [(gogoproto.jsontag) = "lastEvaluation", (gogoproto.stdtime) = true, (gogoproto.nullable) = false ];
127}
128
129message RecordingRule {
130    string name                               = 1 [(gogoproto.jsontag) = "name" ];
131    string query                              = 2 [(gogoproto.jsontag) = "query" ];
132    ZLabelSet labels                          = 3 [(gogoproto.jsontag) = "labels", (gogoproto.nullable) = false ];
133    string health                             = 4 [(gogoproto.jsontag) = "health" ];
134    string last_error                         = 5 [(gogoproto.jsontag) = "lastError,omitempty" ];
135    double evaluation_duration_seconds        = 6 [(gogoproto.jsontag) = "evaluationTime" ];
136    google.protobuf.Timestamp last_evaluation = 7 [(gogoproto.jsontag) = "lastEvaluation", (gogoproto.stdtime) = true, (gogoproto.nullable) = false ];
137}
138