@@ -90,3 +90,89 @@ message Metric {
9090 // ==== vales here are allowed and will be accepted
9191 Bounds system_inclusion_bounds = 5 ;
9292}
93+
94+ // Metrics depicted as a collection of statistical summaries.
95+ //
96+ // Useful when a component has to report multiple values for the same metric.
97+ // E.g., a battery is a collection of several blocks, and each block has a
98+ // temperature sensor. The battery can report a summary of the values provided
99+ // by all these sensors, like, min, max, avg, etc., and if possible, the entire
100+ // array of temperature values.
101+ message MetricAggregation {
102+ // The average value of the metric.
103+ float avg = 1 ;
104+
105+ // The minimum value of the metric.
106+ optional float min = 2 ;
107+
108+ // The maximum value of the metric.
109+ optional float max = 3 ;
110+
111+ // The array of all the metric values.
112+ repeated float raw_values = 12 ;
113+
114+ // The manufacturer's rated bounds of the metric. This may differ from
115+ // `system_bounds` as it does not take into account the current state of the
116+ // overall system.
117+ frequenz.api.common.metrics.Bounds rated_bounds = 13 ;
118+
119+ // The current bounds of the metric, as imposed by the component this metric
120+ // originates from.
121+ frequenz.api.common.metrics.Bounds component_bounds = 14 ;
122+
123+ // These bounds indicate the range of values that are disallowed for the
124+ // metric.
125+ // If these bounds for a metric are [`lower`, `upper`], then this metric's
126+ // `value` needs to comply with the constraints
127+ // `value <= lower` OR `upper <= value`.
128+ //
129+ // It is important to note that these bounds work together with
130+ // `system_inclusion_bounds`.
131+ //
132+ // E.g., for the system to accept a charge command,
133+ // clients need to request power values within the bounds
134+ // `[system_inclusion_bounds.lower, system_exclusion_bounds.lower]`.
135+ // This means that clients can only request charge commands with power values
136+ // that are within the `system_inclusion_bounds`, but not within
137+ // `system_exclusion_bounds`.
138+ // Similarly, for the system to accept a discharge command,
139+ // clients need to request power values within the bounds
140+ // `[system_exclusion_bounds.upper, system_inclusion_bounds.upper]`.
141+ //
142+ // The following diagram illustrates the relationship between the bounds.
143+ // ```
144+ // inclusion.lower inclusion.upper
145+ // <-------|============|------------------|============|--------->
146+ // exclusion.lower exclusion.upper
147+ // ```
148+ // ---- values here are disallowed and wil be rejected
149+ // ==== vales here are allowed and will be accepted
150+ frequenz.api.common.metrics.Bounds system_exclusion_bounds = 4 ;
151+
152+ // These bounds indicate the range of values that are allowed for the metric.
153+ // If these bounds for a metric are [`lower`, `upper`], then this metric's
154+ // `value` needs to comply with the constraint `lower <= value <= upper`
155+ //
156+ // It is important to note that these bounds work together with
157+ // `system_exclusion_bounds`.
158+ //
159+ // E.g., for the system to accept a charge command,
160+ // clients need to request power values within the bounds
161+ // `[system_inclusion_bounds.lower, system_exclusion_bounds.lower]`.
162+ // This means that clients can only request charge commands with power values
163+ // that are within the `system_inclusion_bounds`, but not within
164+ // `system_exclusion_bounds`.
165+ // Similarly, for the system to accept a discharge command,
166+ // clients need to request power values within the bounds
167+ // `[system_exclusion_bounds.upper, system_inclusion_bounds.upper]`.
168+ //
169+ // The following diagram illustrates the relationship between the bounds.
170+ // ```
171+ // inclusion.lower inclusion.upper
172+ // <-------|============|------------------|============|--------->
173+ // exclusion.lower exclusion.upper
174+ // ```
175+ // ---- values here are disallowed and wil be rejected
176+ // ==== vales here are allowed and will be accepted
177+ frequenz.api.common.metrics.Bounds system_inclusion_bounds = 5 ;
178+ }
0 commit comments