Skip to content

metric_sample_pb2

frequenz.api.common.v1.metrics.metric_sample_pb2 ¤

Generated protocol buffer code.

Attributes¤

frequenz.api.common.v1.metrics.metric_sample_pb2.METRIC_AC_APPARENT_ENERGY module-attribute ¤

AC energy metrics

frequenz.api.common.v1.metrics.metric_sample_pb2.METRIC_AC_APPARENT_POWER module-attribute ¤

AC power metrics

frequenz.api.common.v1.metrics.metric_sample_pb2.METRIC_AC_FREQUENCY module-attribute ¤

General AC electricity metrics

frequenz.api.common.v1.metrics.metric_sample_pb2.METRIC_AC_POWER_FACTOR module-attribute ¤

AC Power factor

frequenz.api.common.v1.metrics.metric_sample_pb2.METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT module-attribute ¤

AC harmonics

frequenz.api.common.v1.metrics.metric_sample_pb2.METRIC_BATTERY_CAPACITY module-attribute ¤

General BMS metrics.

frequenz.api.common.v1.metrics.metric_sample_pb2.METRIC_DC_VOLTAGE module-attribute ¤

DC electricity metrics

frequenz.api.common.v1.metrics.metric_sample_pb2.METRIC_EV_CHARGER_TEMPERATURE module-attribute ¤

EV charging station metrics.

frequenz.api.common.v1.metrics.metric_sample_pb2.METRIC_INVERTER_TEMPERATURE module-attribute ¤

General inverter metrics.

frequenz.api.common.v1.metrics.metric_sample_pb2.METRIC_SENSOR_WIND_SPEED module-attribute ¤

General sensor metrics

frequenz.api.common.v1.metrics.metric_sample_pb2.METRIC_UNSPECIFIED module-attribute ¤

Default value.

Classes¤

frequenz.api.common.v1.metrics.metric_sample_pb2.AggregatedMetricValue ¤

Bases: Message

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.

Attributes¤
avg_value instance-attribute ¤

The derived average value of the metric.

max_value instance-attribute ¤

The maximum measured value of the metric.

min_value instance-attribute ¤

The minimum measured value of the metric.

raw_values property ¤

Optional array of all the raw individual values.

frequenz.api.common.v1.metrics.metric_sample_pb2.Metric ¤

Bases: _Metric

List of supported metrics.

Note

AC energy metrics information:

  • This energy metric is reported directly from the component, and not a result of aggregations in our systems. If a component does not have this metric, this field cannot be populated.

  • Components that provide energy metrics reset this metric from time to time. This behaviour is specific to each component model. E.g., some components reset it on UTC 00:00:00.

  • This energy metric does not specify the timestamp since when the energy was being accumulated, and therefore can be inconsistent.

frequenz.api.common.v1.metrics.metric_sample_pb2.MetricSample ¤

Bases: Message

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.

Attributes¤
bounds property ¤

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

metric instance-attribute ¤

The metric that was sampled.

sampled_at property ¤

The UTC timestamp of when the metric was sampled.

source instance-attribute ¤

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.

value property ¤

The value of the sampled metric.

frequenz.api.common.v1.metrics.metric_sample_pb2.MetricValueVariant ¤

Bases: Message

MetricValueVariant serves as a union type that can encapsulate either a SimpleMetricValue or an AggregatedMetricValue.

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 MetricValueVariant can hold either a SimpleMetricValue or an AggregatedMetricValue, but not both simultaneously. Setting one will nullify the other.

frequenz.api.common.v1.metrics.metric_sample_pb2.SimpleMetricValue ¤

Bases: Message

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

Attributes¤
value instance-attribute ¤

The value of the metric, which could be either measured or derived.