|
| 1 | +// Metrics definitions. |
| 2 | +// |
| 3 | +// Copyright: |
| 4 | +// Copyright 2023 Frequenz Energy-as-a-Service GmbH |
| 5 | +// |
| 6 | +// License: |
| 7 | +// MIT |
| 8 | + |
| 9 | +syntax = "proto3"; |
| 10 | + |
| 11 | +package frequenz.api.common.v1.metrics; |
| 12 | + |
| 13 | +import "frequenz/api/common/v1/metrics/bounds.proto"; |
| 14 | + |
| 15 | +import "google/protobuf/timestamp.proto"; |
| 16 | + |
| 17 | +// Represents a single sample of a specific metric, the value of which is either |
| 18 | +// measured or derived at a particular time. |
| 19 | +message SimpleMetricValue { |
| 20 | + // The value of the metric, which could be either measured or derived. |
| 21 | + float value = 2; |
| 22 | +} |
| 23 | + |
| 24 | +// Encapsulates derived statistical summaries of a single metric. |
| 25 | +// |
| 26 | +// The message allows for the reporting of statistical summaries — minimum, |
| 27 | +// maximum, and average values - as well as the complete list of individual |
| 28 | +// samples if available. |
| 29 | +// |
| 30 | +// This message represents derived metrics and contains fields for statistical |
| 31 | +// summaries—minimum, maximum, and average values. Individual measurements are |
| 32 | +// are optional, accommodating scenarios where only subsets of this information |
| 33 | +// are available. |
| 34 | +message AggregatedMetricValue { |
| 35 | + // The derived average value of the metric. |
| 36 | + float avg_value = 2; |
| 37 | + |
| 38 | + // The minimum measured value of the metric. |
| 39 | + optional float min_value = 3; |
| 40 | + |
| 41 | + // The maximum measured value of the metric. |
| 42 | + optional float max_value = 4; |
| 43 | + |
| 44 | + // Optional array of all the raw individual values. |
| 45 | + repeated float raw_values = 5; |
| 46 | +} |
| 47 | + |
| 48 | +// `MetricValueVariant` serves as a union type that can encapsulate either a |
| 49 | +// `SimpleMetricValue` or an `AggregatedMetricValue`. |
| 50 | +// |
| 51 | +// This message is designed to offer flexibility in capturing different |
| 52 | +// granularities of metric samples—either a simple single-point measurement |
| 53 | +// or an aggregated set of measurements for a metric. |
| 54 | +// |
| 55 | +// A `MetricValueVariant` can hold either a `SimpleMetricValue` or an |
| 56 | +// `AggregatedMetricValue`, but not both simultaneously. Setting one will |
| 57 | +// nullify the other. |
| 58 | +message MetricValueVariant { |
| 59 | + oneof metric_value_variant { |
| 60 | + SimpleMetricValue simple_metric = 1; |
| 61 | + AggregatedMetricValue aggregated_metric = 2; |
| 62 | + } |
| 63 | +} |
| 64 | + |
| 65 | +// List of supported metrics. |
| 66 | +// |
| 67 | +// !!! note |
| 68 | +// AC energy metrics information: |
| 69 | +// |
| 70 | +// * This energy metric is reported directly from the component, and not a |
| 71 | +// result of aggregations in our systems. If a component does not have this |
| 72 | +// metric, this field cannot be populated. |
| 73 | +// |
| 74 | +// * Components that provide energy metrics reset this metric from time to |
| 75 | +// time. This behaviour is specific to each component model. E.g., some |
| 76 | +// components reset it on UTC 00:00:00. |
| 77 | +// |
| 78 | +// * This energy metric does not specify the timestamp since when the energy |
| 79 | +// was being accumulated, and therefore can be inconsistent. |
| 80 | +enum Metric { |
| 81 | + // Default value. |
| 82 | + METRIC_UNSPECIFIED = 0; |
| 83 | + |
| 84 | + // DC electricity metrics |
| 85 | + METRIC_DC_VOLTAGE = 1; |
| 86 | + METRIC_DC_CURRENT = 2; |
| 87 | + METRIC_DC_POWER = 3; |
| 88 | + |
| 89 | + // General AC electricity metrics |
| 90 | + METRIC_AC_FREQUENCY = 10; |
| 91 | + METRIC_AC_VOLTAGE = 11; |
| 92 | + METRIC_AC_VOLTAGE_PHASE_1_N = 12; |
| 93 | + METRIC_AC_VOLTAGE_PHASE_2_N = 13; |
| 94 | + METRIC_AC_VOLTAGE_PHASE_3_N = 14; |
| 95 | + METRIC_AC_VOLTAGE_PHASE_1_PHASE_2 = 15; |
| 96 | + METRIC_AC_VOLTAGE_PHASE_2_PHASE_3 = 16; |
| 97 | + METRIC_AC_VOLTAGE_PHASE_3_PHASE_1 = 17; |
| 98 | + METRIC_AC_CURRENT = 18; |
| 99 | + METRIC_AC_CURRENT_PHASE_1 = 19; |
| 100 | + METRIC_AC_CURRENT_PHASE_2 = 20; |
| 101 | + METRIC_AC_CURRENT_PHASE_3 = 21; |
| 102 | + |
| 103 | + // AC power metrics |
| 104 | + METRIC_AC_APPARENT_POWER = 22; |
| 105 | + METRIC_AC_APPARENT_POWER_PHASE_1 = 23; |
| 106 | + METRIC_AC_APPARENT_POWER_PHASE_2 = 24; |
| 107 | + METRIC_AC_APPARENT_POWER_PHASE_3 = 25; |
| 108 | + METRIC_AC_ACTIVE_POWER = 26; |
| 109 | + METRIC_AC_ACTIVE_POWER_PHASE_1 = 27; |
| 110 | + METRIC_AC_ACTIVE_POWER_PHASE_2 = 28; |
| 111 | + METRIC_AC_ACTIVE_POWER_PHASE_3 = 29; |
| 112 | + METRIC_AC_REACTIVE_POWER = 30; |
| 113 | + METRIC_AC_REACTIVE_POWER_PHASE_1 = 31; |
| 114 | + METRIC_AC_REACTIVE_POWER_PHASE_2 = 32; |
| 115 | + METRIC_AC_REACTIVE_POWER_PHASE_3 = 33; |
| 116 | + |
| 117 | + // AC Power factor |
| 118 | + METRIC_AC_POWER_FACTOR = 40; |
| 119 | + METRIC_AC_POWER_FACTOR_PHASE_1 = 41; |
| 120 | + METRIC_AC_POWER_FACTOR_PHASE_2 = 42; |
| 121 | + METRIC_AC_POWER_FACTOR_PHASE_3 = 43; |
| 122 | + |
| 123 | + // AC energy metrics |
| 124 | + METRIC_AC_APPARENT_ENERGY = 50; |
| 125 | + METRIC_AC_APPARENT_ENERGY_PHASE_1 = 51; |
| 126 | + METRIC_AC_APPARENT_ENERGY_PHASE_2 = 52; |
| 127 | + METRIC_AC_APPARENT_ENERGY_PHASE_3 = 53; |
| 128 | + METRIC_AC_ACTIVE_ENERGY = 54; |
| 129 | + METRIC_AC_ACTIVE_ENERGY_PHASE_1 = 55; |
| 130 | + METRIC_AC_ACTIVE_ENERGY_PHASE_2 = 56; |
| 131 | + METRIC_AC_ACTIVE_ENERGY_PHASE_3 = 57; |
| 132 | + METRIC_AC_ACTIVE_ENERGY_CONSUMED = 58; |
| 133 | + METRIC_AC_ACTIVE_ENERGY_CONSUMED_PHASE_1 = 59; |
| 134 | + METRIC_AC_ACTIVE_ENERGY_CONSUMED_PHASE_2 = 60; |
| 135 | + METRIC_AC_ACTIVE_ENERGY_CONSUMED_PHASE_3 = 61; |
| 136 | + METRIC_AC_ACTIVE_ENERGY_DELIVERED = 62; |
| 137 | + METRIC_AC_ACTIVE_ENERGY_DELIVERED_PHASE_1 = 63; |
| 138 | + METRIC_AC_ACTIVE_ENERGY_DELIVERED_PHASE_2 = 64; |
| 139 | + METRIC_AC_ACTIVE_ENERGY_DELIVERED_PHASE_3 = 65; |
| 140 | + METRIC_AC_REACTIVE_ENERGY = 66; |
| 141 | + METRIC_AC_REACTIVE_ENERGY_PHASE_1 = 67; |
| 142 | + METRIC_AC_REACTIVE_ENERGY_PHASE_2 = 69; |
| 143 | + METRIC_AC_REACTIVE_ENERGY_PHASE_3 = 70; |
| 144 | + |
| 145 | + // AC harmonics |
| 146 | + METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT = 80; |
| 147 | + METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_1 = 81; |
| 148 | + METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_2 = 82; |
| 149 | + METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_3 = 83; |
| 150 | + |
| 151 | + // General BMS metrics. |
| 152 | + METRIC_BATTERY_CAPACITY = 101; |
| 153 | + METRIC_BATTERY_SOC_PCT = 102; |
| 154 | + METRIC_BATTERY_TEMPERATURE = 103; |
| 155 | + |
| 156 | + // General inverter metrics. |
| 157 | + METRIC_INVERTER_TEMPERATURE = 120; |
| 158 | + METRIC_INVERTER_TEMPERATURE_CABINET = 121; |
| 159 | + METRIC_INVERTER_TEMPERATURE_HEATSINK = 122; |
| 160 | + METRIC_INVERTER_TEMPERATURE_TRANSFORMER = 123; |
| 161 | + |
| 162 | + // EV charging station metrics. |
| 163 | + METRIC_EV_CHARGER_TEMPERATURE = 140; |
| 164 | + |
| 165 | + // General sensor metrics |
| 166 | + METRIC_SENSOR_WIND_SPEED = 160; |
| 167 | + METRIC_SENSOR_WIND_DIRECTION = 162; |
| 168 | + METRIC_SENSOR_TEMPERATURE = 163; |
| 169 | + METRIC_SENSOR_RELATIVE_HUMIDITY = 164; |
| 170 | + METRIC_SENSOR_DEW_POINT = 165; |
| 171 | + METRIC_SENSOR_AIR_PRESSURE = 166; |
| 172 | + METRIC_SENSOR_IRRADIANCE = 167; |
| 173 | +} |
| 174 | + |
| 175 | +// Representation of a sampled metric along with its value. |
| 176 | +// |
| 177 | +// !!! note |
| 178 | +// This represents a single sample of a specific metric, the value of which |
| 179 | +// is either measured or derived at a particular time. The real-time |
| 180 | +// system-defined bounds are optional and may not always be present or set. |
| 181 | +// |
| 182 | +// !!! note |
| 183 | +// ### Relationship Between Bounds and Metric Samples |
| 184 | +// Suppose a metric sample for active power has a lower-bound of -10,000 W, |
| 185 | +// and an upper-bound of 10,000 W. For the system to accept a charge |
| 186 | +// command, clients need to request current values within the bounds. |
| 187 | +message MetricSample { |
| 188 | + // The UTC timestamp of when the metric was sampled. |
| 189 | + google.protobuf.Timestamp sampled_at = 1; |
| 190 | + |
| 191 | + // The metric that was sampled. |
| 192 | + Metric metric = 2; |
| 193 | + |
| 194 | + // The value of the sampled metric. |
| 195 | + MetricValueVariant value = 3; |
| 196 | + |
| 197 | + // List of bounds that apply to the metric sample. |
| 198 | + // |
| 199 | + // These bounds adapt in real-time to reflect the operating conditions at the |
| 200 | + // time of aggregation or derivation. |
| 201 | + // |
| 202 | + // #### Multiple Bounds |
| 203 | + // |
| 204 | + // In the case of certain components like batteries, multiple bounds might |
| 205 | + // exist. These multiple bounds collectively extend the range of allowable |
| 206 | + // values, effectively forming a union of all given bounds. In such cases, |
| 207 | + // the value of the metric must be within at least one of the bounds. |
| 208 | + // In accordance with the passive sign convention, bounds that limit discharge |
| 209 | + // would have negative numbers, while those limiting charge, such as for the |
| 210 | + // State of Power (SoP) metric, would be positive. Hence bounds can have |
| 211 | + // positive and negative values depending on the metric they represent. |
| 212 | + // |
| 213 | + // #### Example |
| 214 | + // |
| 215 | + // The diagram below illustrates the relationship between the bounds. |
| 216 | + // ``` |
| 217 | + // bound[0].lower bound[1].upper |
| 218 | + // <-------|============|------------------|============|---------> |
| 219 | + // bound[0].upper bound[1].lower |
| 220 | + // ``` |
| 221 | + // ---- values here are disallowed and will be rejected |
| 222 | + // ==== values here are allowed and will be accepted |
| 223 | + repeated Bounds bounds = 4; |
| 224 | + |
| 225 | + // An optional string that can be used to identify the source of the metric. |
| 226 | + // |
| 227 | + // This is expected to be populated when the same `Metric` variant can be |
| 228 | + // obtained from multiple sensors in the component. Knowing the source of the |
| 229 | + // metric can help in certain control and monitoring applications. |
| 230 | + // |
| 231 | + // E.g., a hybrid inverter can have a DC string for a battery and another DC |
| 232 | + // string for a PV array. The source names could resemble, say, |
| 233 | + // `dc_battery_0` and ``dc_pv_0`. A metric like DC voltage can be obtained |
| 234 | + // from both sources. For an application to determine the SoC of the battery |
| 235 | + // using the battery voltage, the source of the voltage metric is important. |
| 236 | + // |
| 237 | + // In cases where the component has just one source for a metric, then this |
| 238 | + // field is not expected to be present, because the source is implicit. |
| 239 | + optional string source = 5; |
| 240 | +} |
0 commit comments