Skip to content

Protocol Documentation¤

Table of Contents¤

Top

frequenz/api/common/v1/metrics/metric_sample.proto¤

AggregatedMetricSample¤

Encapsulates derived statistical summaries of a single metric.

The message allows for the reporting of statistical summaries — minimum, maximum, and average values - as well as the complete list of individual samples if available.

This message represents derived metrics and contains fields for statistical summaries—minimum, maximum, and average values. Individual measurements are are optional, accommodating scenarios where only subsets of this information are available.

Field Type Label Description
avg_value float The derived average value of the metric.
min_value float optional The minimum measured value of the metric.
max_value float optional The maximum measured value of the metric.
raw_values float repeated Optional array of all the raw individual values.

MetricSample¤

Representation of a sampled metric along with its value.

Note

This represents a single sample of a specific metric, the value of which is either measured or derived at a particular time. The real-time system-defined bounds are optional and may not always be present or set.

Note

Relationship Between Bounds and Metric Samples¤

Suppose a metric sample for active power has a lower-bound of -10,000 W, and an upper-bound of 10,000 W. For the system to accept a charge command, clients need to request current values within the bounds.

Field Type Label Description
sampled_at google.protobuf.Timestamp The UTC timestamp of when the metric was sampled.
metric Metric The metric that was sampled.
sample MetricSampleVariant The value of the sampled metric.
bounds Bounds repeated List of bounds that apply to the metric sample.

These bounds adapt in real-time to reflect the operating conditions at the time of aggregation or derivation.

Multiple Bounds¤

In the case of certain components like batteries, multiple bounds might exist. These multiple bounds collectively extend the range of allowable values, effectively forming a union of all given bounds. In such cases, the value of the metric must be within at least one of the bounds. In accordance with the passive sign convention, bounds that limit discharge would have negative numbers, while those limiting charge, such as for the State of Power (SoP) metric, would be positive. Hence bounds can have positive and negative values depending on the metric they represent.

Example¤

The diagram below illustrates the relationship between the bounds. bound[0].lower bound[1].upper <-------|============|------------------|============|---------> bound[0].upper bound[1].lower ---- values here are disallowed and will be rejected ==== values here are allowed and will be accepted | | source | string | optional | An optional string that can be used to identify the source of the metric.

This is expected to be populated when the same Metric variant can be obtained from multiple sensors in the component. Knowing the source of the metric can help in certain control and monitoring applications.

E.g., a hybrid inverter can have a DC string for a battery and another DC string for a PV array. The source names could resemble, say, dc_battery_0 and `dc_pv_0. A metric like DC voltage can be obtained from both sources. For an application to determine the SoC of the battery using the battery voltage, the source of the voltage metric is important.

In cases where the component has just one source for a metric, then this field is not expected to be present, because the source is implicit. |

MetricSampleVariant¤

MetricSampleVariant serves as a union type that can encapsulate either a SimpleMetricSample or an AggregatedMetricSample.

This message is designed to offer flexibility in capturing different granularities of metric samples—either a simple single-point measurement or an aggregated set of measurements for a metric.

A MetricSampleVariant can hold either a SimpleMetricSample or an AggregatedMetricSample, but not both simultaneously. Setting one will nullify the other.

Field Type Label Description
simple_metric SimpleMetricSample
aggregated_metric AggregatedMetricSample

SimpleMetricSample¤

Represents a single sample of a specific metric, the value of which is either measured or derived at a particular time.

Field Type Label Description
value float The value of the metric, which could be either measured or derived.

Metric¤

List of supported metrics.

Name Number Description
METRIC_UNSPECIFIED 0 Default value.
METRIC_DC_VOLTAGE 1 DC electricity metrics
METRIC_DC_CURRENT 2
METRIC_DC_POWER 3
METRIC_AC_FREQUENCY 10 General AC electricity metrics
METRIC_AC_VOLTAGE 11
METRIC_AC_VOLTAGE_PHASE_1 12
METRIC_AC_VOLTAGE_PHASE_2 13
METRIC_AC_VOLTAGE_PHASE_3 14
METRIC_AC_APPARENT_CURRENT 15
METRIC_AC_APPARENT_CURRENT_PHASE_1 16
METRIC_AC_APPARENT_CURRENT_PHASE_2 17
METRIC_AC_APPARENT_CURRENT_PHASE_3 18
METRIC_AC_APPARENT_POWER 20 AC power metrics
METRIC_AC_APPARENT_POWER_PHASE_1 21
METRIC_AC_APPARENT_POWER_PHASE_2 22
METRIC_AC_APPARENT_POWER_PHASE_3 23
METRIC_AC_ACTIVE_POWER 24
METRIC_AC_ACTIVE_POWER_PHASE_1 25
METRIC_AC_ACTIVE_POWER_PHASE_2 26
METRIC_AC_ACTIVE_POWER_PHASE_3 27
METRIC_AC_REACTIVE_POWER 28
METRIC_AC_REACTIVE_POWER_PHASE_1 29
METRIC_AC_REACTIVE_POWER_PHASE_2 30
METRIC_AC_REACTIVE_POWER_PHASE_3 31
METRIC_AC_POWER_FACTOR 40 AC Power factor
METRIC_AC_POWER_FACTOR_PHASE_1 41
METRIC_AC_POWER_FACTOR_PHASE_2 42
METRIC_AC_POWER_FACTOR_PHASE_3 43
METRIC_AC_APPARENT_ENERGY 50 AC energy metrics
METRIC_AC_APPARENT_ENERGY_PHASE_1 51
METRIC_AC_APPARENT_ENERGY_PHASE_2 52
METRIC_AC_APPARENT_ENERGY_PHASE_3 53
METRIC_AC_ACTIVE_ENERGY 54
METRIC_AC_ACTIVE_ENERGY_PHASE_1 55
METRIC_AC_ACTIVE_ENERGY_PHASE_2 56
METRIC_AC_ACTIVE_ENERGY_PHASE_3 57
METRIC_AC_ACTIVE_ENERGY_CONSUMED 58
METRIC_AC_ACTIVE_ENERGY_CONSUMED_PHASE_1 59
METRIC_AC_ACTIVE_ENERGY_CONSUMED_PHASE_2 60
METRIC_AC_ACTIVE_ENERGY_CONSUMED_PHASE_3 61
METRIC_AC_ACTIVE_ENERGY_DELIVERED 62
METRIC_AC_ACTIVE_ENERGY_DELIVERED_PHASE_1 63
METRIC_AC_ACTIVE_ENERGY_DELIVERED_PHASE_2 64
METRIC_AC_ACTIVE_ENERGY_DELIVERED_PHASE_3 65
METRIC_AC_REACTIVE_ENERGY 66
METRIC_AC_REACTIVE_ENERGY_PHASE_1 67
METRIC_AC_REACTIVE_ENERGY_PHASE_2 69
METRIC_AC_REACTIVE_ENERGY_PHASE_3 70
METRIC_AC_THD_CURRENT 80 AC harmonics
METRIC_AC_THD_CURRENT_PHASE_1 81
METRIC_AC_THD_CURRENT_PHASE_2 82
METRIC_AC_THD_CURRENT_PHASE_3 83
METRIC_BATTERY_CAPACITY 101 General BMS metrics.
METRIC_BATTERY_SOC_PCT 102
METRIC_BATTERY_TEMPERATURE 103
METRIC_INVERTER_TEMPERATURE 120 General inverter metrics.
METRIC_INVERTER_TEMPERATURE_CABINET 121
METRIC_INVERTER_TEMPERATURE_HEATSINK 122
METRIC_INVERTER_TEMPERATURE_TRANSFORMER 123
METRIC_EV_CHARGER_TEMPERATURE 140 EV charging station metrics.
METRIC_SENSOR_WIND_SPEED 160 General sensor metrics
METRIC_SENSOR_WIND_DIRECTION 162
METRIC_SENSOR_TEMPERATURE 163
METRIC_SENSOR_RELATIVE_HUMIDITY 164
METRIC_SENSOR_DEW_POINT 165
METRIC_SENSOR_AIR_PRESSURE 166
METRIC_SENSOR_IRRADIANCE 167

Scalar Value Types¤

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)