Skip to content

Index

frequenz.client.common.metrics ¤

Metrics definitions.

Classes¤

frequenz.client.common.metrics.AggregatedMetricValue dataclass ¤

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 optional, accommodating scenarios where only subsets of this information are available.

Source code in frequenz/client/common/metrics/_sample.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
@dataclass(frozen=True, kw_only=True)
class AggregatedMetricValue:
    """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
    optional, accommodating scenarios where only subsets of this information
    are available.
    """

    avg: float
    """The derived average value of the metric."""

    min: float | None
    """The minimum measured value of the metric."""

    max: float | None
    """The maximum measured value of the metric."""

    raw: Sequence[float]
    """All the raw individual values (it might be empty if not provided by the component)."""

    def __str__(self) -> str:
        """Return the short string representation of this instance."""
        extra: list[str] = []
        if self.min is not None:
            extra.append(f"min:{self.min}")
        if self.max is not None:
            extra.append(f"max:{self.max}")
        if len(self.raw) > 0:
            extra.append(f"num_raw:{len(self.raw)}")
        extra_str = f"<{' '.join(extra)}>" if extra else ""
        return f"avg:{self.avg}{extra_str}"
Attributes¤
avg instance-attribute ¤
avg: float

The derived average value of the metric.

max instance-attribute ¤
max: float | None

The maximum measured value of the metric.

min instance-attribute ¤
min: float | None

The minimum measured value of the metric.

raw instance-attribute ¤
raw: Sequence[float]

All the raw individual values (it might be empty if not provided by the component).

Functions¤
__str__ ¤
__str__() -> str

Return the short string representation of this instance.

Source code in frequenz/client/common/metrics/_sample.py 
58
59
60
61
62
63
64
65
66
67
68
def __str__(self) -> str:
    """Return the short string representation of this instance."""
    extra: list[str] = []
    if self.min is not None:
        extra.append(f"min:{self.min}")
    if self.max is not None:
        extra.append(f"max:{self.max}")
    if len(self.raw) > 0:
        extra.append(f"num_raw:{len(self.raw)}")
    extra_str = f"<{' '.join(extra)}>" if extra else ""
    return f"avg:{self.avg}{extra_str}"

frequenz.client.common.metrics.AggregationMethod ¤

Bases: Enum

The type of the aggregated value.

Source code in frequenz/client/common/metrics/_sample.py 
18
19
20
21
22
23
24
25
26
27
28
29
@enum.unique
class AggregationMethod(enum.Enum):
    """The type of the aggregated value."""

    AVG = "avg"
    """The average value of the metric."""

    MIN = "min"
    """The minimum value of the metric."""

    MAX = "max"
    """The maximum value of the metric."""
Attributes¤
AVG class-attribute instance-attribute ¤
AVG = 'avg'

The average value of the metric.

MAX class-attribute instance-attribute ¤
MAX = 'max'

The maximum value of the metric.

MIN class-attribute instance-attribute ¤
MIN = 'min'

The minimum value of the metric.

frequenz.client.common.metrics.Bounds dataclass ¤

A set of lower and upper bounds for any metric.

The lower bound must be less than or equal to the upper bound.

The units of the bounds are always the same as the related metric.

Source code in frequenz/client/common/metrics/_bounds.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
@dataclasses.dataclass(frozen=True, kw_only=True)
class Bounds:
    """A set of lower and upper bounds for any metric.

    The lower bound must be less than or equal to the upper bound.

    The units of the bounds are always the same as the related metric.
    """

    lower: float | None = None
    """The lower bound.

    If `None`, there is no lower bound.
    """

    upper: float | None = None
    """The upper bound.

    If `None`, there is no upper bound.
    """

    def __post_init__(self) -> None:
        """Validate these bounds."""
        if self.lower is None:
            return
        if self.upper is None:
            return
        if self.lower > self.upper:
            raise ValueError(
                f"Lower bound ({self.lower}) must be less than or equal to upper "
                f"bound ({self.upper})"
            )

    def __str__(self) -> str:
        """Return a string representation of these bounds."""
        return f"[{self.lower}, {self.upper}]"
Attributes¤
lower class-attribute instance-attribute ¤
lower: float | None = None

The lower bound.

If None, there is no lower bound.

upper class-attribute instance-attribute ¤
upper: float | None = None

The upper bound.

If None, there is no upper bound.

Functions¤
__post_init__ ¤
__post_init__() -> None

Validate these bounds.

Source code in frequenz/client/common/metrics/_bounds.py 
31
32
33
34
35
36
37
38
39
40
41
def __post_init__(self) -> None:
    """Validate these bounds."""
    if self.lower is None:
        return
    if self.upper is None:
        return
    if self.lower > self.upper:
        raise ValueError(
            f"Lower bound ({self.lower}) must be less than or equal to upper "
            f"bound ({self.upper})"
        )
__str__ ¤
__str__() -> str

Return a string representation of these bounds.

Source code in frequenz/client/common/metrics/_bounds.py 
43
44
45
def __str__(self) -> str:
    """Return a string representation of these bounds."""
    return f"[{self.lower}, {self.upper}]"

frequenz.client.common.metrics.Metric ¤

Bases: Enum

List of supported metrics.

Metric units are as follows:

  • VOLTAGE: V (Volts)
  • CURRENT: A (Amperes)
  • POWER_ACTIVE: W (Watts)
  • POWER_APPARENT: VA (Volt-Amperes)
  • POWER_REACTIVE: VAr (Volt-Amperes reactive)
  • ENERGY_ACTIVE: Wh (Watt-hours)
  • ENERGY_APPARENT: VAh (Volt-Ampere hours)
  • ENERGY_REACTIVE: VArh (Volt-Ampere reactive hours)
  • FREQUENCY: Hz (Hertz)
  • TEMPERATURE: °C (Degree Celsius)
  • BATTERY_SOC_PCT: % (percentage)
  • BATTERY_CAPACITY: Wh (Watt-hours)
  • FACTOR: no unit
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 start time of the accumulation period, and therefore can be inconsistent.

Source code in frequenz/client/common/metrics/_metric.py 
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
@enum.unique
class Metric(enum.Enum):
    """List of supported metrics.

    Metric units are as follows:

    * `VOLTAGE`: V (Volts)
    * `CURRENT`: A (Amperes)
    * `POWER_ACTIVE`: W (Watts)
    * `POWER_APPARENT`: VA (Volt-Amperes)
    * `POWER_REACTIVE`: VAr (Volt-Amperes reactive)
    * `ENERGY_ACTIVE`: Wh (Watt-hours)
    * `ENERGY_APPARENT`: VAh (Volt-Ampere hours)
    * `ENERGY_REACTIVE`: VArh (Volt-Ampere reactive hours)
    * `FREQUENCY`: Hz (Hertz)
    * `TEMPERATURE`: °C (Degree Celsius)
    * `BATTERY_SOC_PCT`: % (percentage)
    * `BATTERY_CAPACITY`: Wh (Watt-hours)
    * `FACTOR`: no unit

    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 start time of the accumulation
          period, and therefore can be inconsistent.
    """

    UNSPECIFIED = metrics_pb2.METRIC_UNSPECIFIED
    """The metric is unspecified (this should not be used)."""

    DC_VOLTAGE = metrics_pb2.METRIC_DC_VOLTAGE
    """The DC voltage."""

    DC_CURRENT = metrics_pb2.METRIC_DC_CURRENT
    """The DC current."""

    DC_POWER = metrics_pb2.METRIC_DC_POWER
    """The DC power."""

    AC_FREQUENCY = metrics_pb2.METRIC_AC_FREQUENCY
    """The AC frequency."""

    AC_VOLTAGE = metrics_pb2.METRIC_AC_VOLTAGE
    """The AC electric potential difference."""

    AC_VOLTAGE_PHASE_1_N = metrics_pb2.METRIC_AC_VOLTAGE_PHASE_1_N
    """The AC electric potential difference between phase 1 and neutral."""

    AC_VOLTAGE_PHASE_2_N = metrics_pb2.METRIC_AC_VOLTAGE_PHASE_2_N
    """The AC electric potential difference between phase 2 and neutral."""

    AC_VOLTAGE_PHASE_3_N = metrics_pb2.METRIC_AC_VOLTAGE_PHASE_3_N
    """The AC electric potential difference between phase 3 and neutral."""

    AC_VOLTAGE_PHASE_1_PHASE_2 = metrics_pb2.METRIC_AC_VOLTAGE_PHASE_1_PHASE_2
    """The AC electric potential difference between phase 1 and phase 2."""

    AC_VOLTAGE_PHASE_2_PHASE_3 = metrics_pb2.METRIC_AC_VOLTAGE_PHASE_2_PHASE_3
    """The AC electric potential difference between phase 2 and phase 3."""

    AC_VOLTAGE_PHASE_3_PHASE_1 = metrics_pb2.METRIC_AC_VOLTAGE_PHASE_3_PHASE_1
    """The AC electric potential difference between phase 3 and phase 1."""

    AC_CURRENT = metrics_pb2.METRIC_AC_CURRENT
    """The AC current."""

    AC_CURRENT_PHASE_1 = metrics_pb2.METRIC_AC_CURRENT_PHASE_1
    """The AC current in phase 1."""

    AC_CURRENT_PHASE_2 = metrics_pb2.METRIC_AC_CURRENT_PHASE_2
    """The AC current in phase 2."""

    AC_CURRENT_PHASE_3 = metrics_pb2.METRIC_AC_CURRENT_PHASE_3
    """The AC current in phase 3."""

    AC_POWER_APPARENT = metrics_pb2.METRIC_AC_POWER_APPARENT
    """The AC apparent power."""

    AC_POWER_APPARENT_PHASE_1 = metrics_pb2.METRIC_AC_POWER_APPARENT_PHASE_1
    """The AC apparent power in phase 1."""

    AC_POWER_APPARENT_PHASE_2 = metrics_pb2.METRIC_AC_POWER_APPARENT_PHASE_2
    """The AC apparent power in phase 2."""

    AC_POWER_APPARENT_PHASE_3 = metrics_pb2.METRIC_AC_POWER_APPARENT_PHASE_3
    """The AC apparent power in phase 3."""

    AC_POWER_ACTIVE = metrics_pb2.METRIC_AC_POWER_ACTIVE
    """The AC active power."""

    AC_POWER_ACTIVE_PHASE_1 = metrics_pb2.METRIC_AC_POWER_ACTIVE_PHASE_1
    """The AC active power in phase 1."""

    AC_POWER_ACTIVE_PHASE_2 = metrics_pb2.METRIC_AC_POWER_ACTIVE_PHASE_2
    """The AC active power in phase 2."""

    AC_POWER_ACTIVE_PHASE_3 = metrics_pb2.METRIC_AC_POWER_ACTIVE_PHASE_3
    """The AC active power in phase 3."""

    AC_POWER_REACTIVE = metrics_pb2.METRIC_AC_POWER_REACTIVE
    """The AC reactive power."""

    AC_POWER_REACTIVE_PHASE_1 = metrics_pb2.METRIC_AC_POWER_REACTIVE_PHASE_1
    """The AC reactive power in phase 1."""

    AC_POWER_REACTIVE_PHASE_2 = metrics_pb2.METRIC_AC_POWER_REACTIVE_PHASE_2
    """The AC reactive power in phase 2."""

    AC_POWER_REACTIVE_PHASE_3 = metrics_pb2.METRIC_AC_POWER_REACTIVE_PHASE_3
    """The AC reactive power in phase 3."""

    AC_POWER_FACTOR = metrics_pb2.METRIC_AC_POWER_FACTOR
    """The AC power factor."""

    AC_POWER_FACTOR_PHASE_1 = metrics_pb2.METRIC_AC_POWER_FACTOR_PHASE_1
    """The AC power factor in phase 1."""

    AC_POWER_FACTOR_PHASE_2 = metrics_pb2.METRIC_AC_POWER_FACTOR_PHASE_2
    """The AC power factor in phase 2."""

    AC_POWER_FACTOR_PHASE_3 = metrics_pb2.METRIC_AC_POWER_FACTOR_PHASE_3
    """The AC power factor in phase 3."""

    AC_ENERGY_APPARENT = metrics_pb2.METRIC_AC_ENERGY_APPARENT
    """The AC apparent energy."""

    AC_ENERGY_APPARENT_PHASE_1 = metrics_pb2.METRIC_AC_ENERGY_APPARENT_PHASE_1
    """The AC apparent energy in phase 1."""

    AC_ENERGY_APPARENT_PHASE_2 = metrics_pb2.METRIC_AC_ENERGY_APPARENT_PHASE_2
    """The AC apparent energy in phase 2."""

    AC_ENERGY_APPARENT_PHASE_3 = metrics_pb2.METRIC_AC_ENERGY_APPARENT_PHASE_3
    """The AC apparent energy in phase 3."""

    AC_ENERGY_ACTIVE = metrics_pb2.METRIC_AC_ENERGY_ACTIVE
    """The AC active energy."""

    AC_ENERGY_ACTIVE_PHASE_1 = metrics_pb2.METRIC_AC_ENERGY_ACTIVE_PHASE_1
    """The AC active energy in phase 1."""

    AC_ENERGY_ACTIVE_PHASE_2 = metrics_pb2.METRIC_AC_ENERGY_ACTIVE_PHASE_2
    """The AC active energy in phase 2."""

    AC_ENERGY_ACTIVE_PHASE_3 = metrics_pb2.METRIC_AC_ENERGY_ACTIVE_PHASE_3
    """The AC active energy in phase 3."""

    AC_ENERGY_ACTIVE_CONSUMED = metrics_pb2.METRIC_AC_ENERGY_ACTIVE_CONSUMED
    """The AC active energy consumed."""

    AC_ENERGY_ACTIVE_CONSUMED_PHASE_1 = (
        metrics_pb2.METRIC_AC_ENERGY_ACTIVE_CONSUMED_PHASE_1
    )
    """The AC active energy consumed in phase 1."""

    AC_ENERGY_ACTIVE_CONSUMED_PHASE_2 = (
        metrics_pb2.METRIC_AC_ENERGY_ACTIVE_CONSUMED_PHASE_2
    )
    """The AC active energy consumed in phase 2."""

    AC_ENERGY_ACTIVE_CONSUMED_PHASE_3 = (
        metrics_pb2.METRIC_AC_ENERGY_ACTIVE_CONSUMED_PHASE_3
    )
    """The AC active energy consumed in phase 3."""

    AC_ENERGY_ACTIVE_DELIVERED = metrics_pb2.METRIC_AC_ENERGY_ACTIVE_DELIVERED
    """The AC active energy delivered."""

    AC_ENERGY_ACTIVE_DELIVERED_PHASE_1 = (
        metrics_pb2.METRIC_AC_ENERGY_ACTIVE_DELIVERED_PHASE_1
    )
    """The AC active energy delivered in phase 1."""

    AC_ENERGY_ACTIVE_DELIVERED_PHASE_2 = (
        metrics_pb2.METRIC_AC_ENERGY_ACTIVE_DELIVERED_PHASE_2
    )
    """The AC active energy delivered in phase 2."""

    AC_ENERGY_ACTIVE_DELIVERED_PHASE_3 = (
        metrics_pb2.METRIC_AC_ENERGY_ACTIVE_DELIVERED_PHASE_3
    )
    """The AC active energy delivered in phase 3."""

    AC_ENERGY_REACTIVE = metrics_pb2.METRIC_AC_ENERGY_REACTIVE
    """The AC reactive energy."""

    AC_ENERGY_REACTIVE_PHASE_1 = metrics_pb2.METRIC_AC_ENERGY_REACTIVE_PHASE_1
    """The AC reactive energy in phase 1."""

    AC_ENERGY_REACTIVE_PHASE_2 = metrics_pb2.METRIC_AC_ENERGY_REACTIVE_PHASE_2
    """The AC reactive energy in phase 2."""

    AC_ENERGY_REACTIVE_PHASE_3 = metrics_pb2.METRIC_AC_ENERGY_REACTIVE_PHASE_3
    """The AC reactive energy in phase 3."""

    AC_TOTAL_HARMONIC_DISTORTION_CURRENT = (
        metrics_pb2.METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT
    )
    """The AC total harmonic distortion current."""

    AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_1 = (
        metrics_pb2.METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_1
    )
    """The AC total harmonic distortion current in phase 1."""

    AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_2 = (
        metrics_pb2.METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_2
    )
    """The AC total harmonic distortion current in phase 2."""

    AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_3 = (
        metrics_pb2.METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_3
    )
    """The AC total harmonic distortion current in phase 3."""

    BATTERY_CAPACITY = metrics_pb2.METRIC_BATTERY_CAPACITY
    """The capacity of the battery."""

    BATTERY_SOC_PCT = metrics_pb2.METRIC_BATTERY_SOC_PCT
    """The state of charge of the battery as a percentage."""

    BATTERY_TEMPERATURE = metrics_pb2.METRIC_BATTERY_TEMPERATURE
    """The temperature of the battery."""

    INVERTER_TEMPERATURE = metrics_pb2.METRIC_INVERTER_TEMPERATURE
    """The temperature of the inverter."""

    INVERTER_TEMPERATURE_CABINET = metrics_pb2.METRIC_INVERTER_TEMPERATURE_CABINET
    """The temperature of the inverter cabinet."""

    INVERTER_TEMPERATURE_HEATSINK = metrics_pb2.METRIC_INVERTER_TEMPERATURE_HEATSINK
    """The temperature of the inverter heatsink."""

    INVERTER_TEMPERATURE_TRANSFORMER = (
        metrics_pb2.METRIC_INVERTER_TEMPERATURE_TRANSFORMER
    )
    """The temperature of the inverter transformer."""

    EV_CHARGER_TEMPERATURE = metrics_pb2.METRIC_EV_CHARGER_TEMPERATURE
    """The temperature of the EV charger."""

    SENSOR_WIND_SPEED = metrics_pb2.METRIC_SENSOR_WIND_SPEED
    """The speed of the wind measured."""

    SENSOR_WIND_DIRECTION = metrics_pb2.METRIC_SENSOR_WIND_DIRECTION
    """The direction of the wind measured."""

    SENSOR_TEMPERATURE = metrics_pb2.METRIC_SENSOR_TEMPERATURE
    """The temperature measured."""

    SENSOR_RELATIVE_HUMIDITY = metrics_pb2.METRIC_SENSOR_RELATIVE_HUMIDITY
    """The relative humidity measured."""

    SENSOR_DEW_POINT = metrics_pb2.METRIC_SENSOR_DEW_POINT
    """The dew point measured."""

    SENSOR_AIR_PRESSURE = metrics_pb2.METRIC_SENSOR_AIR_PRESSURE
    """The air pressure measured."""

    SENSOR_IRRADIANCE = metrics_pb2.METRIC_SENSOR_IRRADIANCE
    """The irradiance measured."""
Attributes¤
AC_CURRENT class-attribute instance-attribute ¤
AC_CURRENT = METRIC_AC_CURRENT

The AC current.

AC_CURRENT_PHASE_1 class-attribute instance-attribute ¤
AC_CURRENT_PHASE_1 = METRIC_AC_CURRENT_PHASE_1

The AC current in phase 1.

AC_CURRENT_PHASE_2 class-attribute instance-attribute ¤
AC_CURRENT_PHASE_2 = METRIC_AC_CURRENT_PHASE_2

The AC current in phase 2.

AC_CURRENT_PHASE_3 class-attribute instance-attribute ¤
AC_CURRENT_PHASE_3 = METRIC_AC_CURRENT_PHASE_3

The AC current in phase 3.

AC_ENERGY_ACTIVE class-attribute instance-attribute ¤
AC_ENERGY_ACTIVE = METRIC_AC_ENERGY_ACTIVE

The AC active energy.

AC_ENERGY_ACTIVE_CONSUMED class-attribute instance-attribute ¤
AC_ENERGY_ACTIVE_CONSUMED = METRIC_AC_ENERGY_ACTIVE_CONSUMED

The AC active energy consumed.

AC_ENERGY_ACTIVE_CONSUMED_PHASE_1 class-attribute instance-attribute ¤
AC_ENERGY_ACTIVE_CONSUMED_PHASE_1 = (
    METRIC_AC_ENERGY_ACTIVE_CONSUMED_PHASE_1
)

The AC active energy consumed in phase 1.

AC_ENERGY_ACTIVE_CONSUMED_PHASE_2 class-attribute instance-attribute ¤
AC_ENERGY_ACTIVE_CONSUMED_PHASE_2 = (
    METRIC_AC_ENERGY_ACTIVE_CONSUMED_PHASE_2
)

The AC active energy consumed in phase 2.

AC_ENERGY_ACTIVE_CONSUMED_PHASE_3 class-attribute instance-attribute ¤
AC_ENERGY_ACTIVE_CONSUMED_PHASE_3 = (
    METRIC_AC_ENERGY_ACTIVE_CONSUMED_PHASE_3
)

The AC active energy consumed in phase 3.

AC_ENERGY_ACTIVE_DELIVERED class-attribute instance-attribute ¤
AC_ENERGY_ACTIVE_DELIVERED = (
    METRIC_AC_ENERGY_ACTIVE_DELIVERED
)

The AC active energy delivered.

AC_ENERGY_ACTIVE_DELIVERED_PHASE_1 class-attribute instance-attribute ¤
AC_ENERGY_ACTIVE_DELIVERED_PHASE_1 = (
    METRIC_AC_ENERGY_ACTIVE_DELIVERED_PHASE_1
)

The AC active energy delivered in phase 1.

AC_ENERGY_ACTIVE_DELIVERED_PHASE_2 class-attribute instance-attribute ¤
AC_ENERGY_ACTIVE_DELIVERED_PHASE_2 = (
    METRIC_AC_ENERGY_ACTIVE_DELIVERED_PHASE_2
)

The AC active energy delivered in phase 2.

AC_ENERGY_ACTIVE_DELIVERED_PHASE_3 class-attribute instance-attribute ¤
AC_ENERGY_ACTIVE_DELIVERED_PHASE_3 = (
    METRIC_AC_ENERGY_ACTIVE_DELIVERED_PHASE_3
)

The AC active energy delivered in phase 3.

AC_ENERGY_ACTIVE_PHASE_1 class-attribute instance-attribute ¤
AC_ENERGY_ACTIVE_PHASE_1 = METRIC_AC_ENERGY_ACTIVE_PHASE_1

The AC active energy in phase 1.

AC_ENERGY_ACTIVE_PHASE_2 class-attribute instance-attribute ¤
AC_ENERGY_ACTIVE_PHASE_2 = METRIC_AC_ENERGY_ACTIVE_PHASE_2

The AC active energy in phase 2.

AC_ENERGY_ACTIVE_PHASE_3 class-attribute instance-attribute ¤
AC_ENERGY_ACTIVE_PHASE_3 = METRIC_AC_ENERGY_ACTIVE_PHASE_3

The AC active energy in phase 3.

AC_ENERGY_APPARENT class-attribute instance-attribute ¤
AC_ENERGY_APPARENT = METRIC_AC_ENERGY_APPARENT

The AC apparent energy.

AC_ENERGY_APPARENT_PHASE_1 class-attribute instance-attribute ¤
AC_ENERGY_APPARENT_PHASE_1 = (
    METRIC_AC_ENERGY_APPARENT_PHASE_1
)

The AC apparent energy in phase 1.

AC_ENERGY_APPARENT_PHASE_2 class-attribute instance-attribute ¤
AC_ENERGY_APPARENT_PHASE_2 = (
    METRIC_AC_ENERGY_APPARENT_PHASE_2
)

The AC apparent energy in phase 2.

AC_ENERGY_APPARENT_PHASE_3 class-attribute instance-attribute ¤
AC_ENERGY_APPARENT_PHASE_3 = (
    METRIC_AC_ENERGY_APPARENT_PHASE_3
)

The AC apparent energy in phase 3.

AC_ENERGY_REACTIVE class-attribute instance-attribute ¤
AC_ENERGY_REACTIVE = METRIC_AC_ENERGY_REACTIVE

The AC reactive energy.

AC_ENERGY_REACTIVE_PHASE_1 class-attribute instance-attribute ¤
AC_ENERGY_REACTIVE_PHASE_1 = (
    METRIC_AC_ENERGY_REACTIVE_PHASE_1
)

The AC reactive energy in phase 1.

AC_ENERGY_REACTIVE_PHASE_2 class-attribute instance-attribute ¤
AC_ENERGY_REACTIVE_PHASE_2 = (
    METRIC_AC_ENERGY_REACTIVE_PHASE_2
)

The AC reactive energy in phase 2.

AC_ENERGY_REACTIVE_PHASE_3 class-attribute instance-attribute ¤
AC_ENERGY_REACTIVE_PHASE_3 = (
    METRIC_AC_ENERGY_REACTIVE_PHASE_3
)

The AC reactive energy in phase 3.

AC_FREQUENCY class-attribute instance-attribute ¤
AC_FREQUENCY = METRIC_AC_FREQUENCY

The AC frequency.

AC_POWER_ACTIVE class-attribute instance-attribute ¤
AC_POWER_ACTIVE = METRIC_AC_POWER_ACTIVE

The AC active power.

AC_POWER_ACTIVE_PHASE_1 class-attribute instance-attribute ¤
AC_POWER_ACTIVE_PHASE_1 = METRIC_AC_POWER_ACTIVE_PHASE_1

The AC active power in phase 1.

AC_POWER_ACTIVE_PHASE_2 class-attribute instance-attribute ¤
AC_POWER_ACTIVE_PHASE_2 = METRIC_AC_POWER_ACTIVE_PHASE_2

The AC active power in phase 2.

AC_POWER_ACTIVE_PHASE_3 class-attribute instance-attribute ¤
AC_POWER_ACTIVE_PHASE_3 = METRIC_AC_POWER_ACTIVE_PHASE_3

The AC active power in phase 3.

AC_POWER_APPARENT class-attribute instance-attribute ¤
AC_POWER_APPARENT = METRIC_AC_POWER_APPARENT

The AC apparent power.

AC_POWER_APPARENT_PHASE_1 class-attribute instance-attribute ¤
AC_POWER_APPARENT_PHASE_1 = METRIC_AC_POWER_APPARENT_PHASE_1

The AC apparent power in phase 1.

AC_POWER_APPARENT_PHASE_2 class-attribute instance-attribute ¤
AC_POWER_APPARENT_PHASE_2 = METRIC_AC_POWER_APPARENT_PHASE_2

The AC apparent power in phase 2.

AC_POWER_APPARENT_PHASE_3 class-attribute instance-attribute ¤
AC_POWER_APPARENT_PHASE_3 = METRIC_AC_POWER_APPARENT_PHASE_3

The AC apparent power in phase 3.

AC_POWER_FACTOR class-attribute instance-attribute ¤
AC_POWER_FACTOR = METRIC_AC_POWER_FACTOR

The AC power factor.

AC_POWER_FACTOR_PHASE_1 class-attribute instance-attribute ¤
AC_POWER_FACTOR_PHASE_1 = METRIC_AC_POWER_FACTOR_PHASE_1

The AC power factor in phase 1.

AC_POWER_FACTOR_PHASE_2 class-attribute instance-attribute ¤
AC_POWER_FACTOR_PHASE_2 = METRIC_AC_POWER_FACTOR_PHASE_2

The AC power factor in phase 2.

AC_POWER_FACTOR_PHASE_3 class-attribute instance-attribute ¤
AC_POWER_FACTOR_PHASE_3 = METRIC_AC_POWER_FACTOR_PHASE_3

The AC power factor in phase 3.

AC_POWER_REACTIVE class-attribute instance-attribute ¤
AC_POWER_REACTIVE = METRIC_AC_POWER_REACTIVE

The AC reactive power.

AC_POWER_REACTIVE_PHASE_1 class-attribute instance-attribute ¤
AC_POWER_REACTIVE_PHASE_1 = METRIC_AC_POWER_REACTIVE_PHASE_1

The AC reactive power in phase 1.

AC_POWER_REACTIVE_PHASE_2 class-attribute instance-attribute ¤
AC_POWER_REACTIVE_PHASE_2 = METRIC_AC_POWER_REACTIVE_PHASE_2

The AC reactive power in phase 2.

AC_POWER_REACTIVE_PHASE_3 class-attribute instance-attribute ¤
AC_POWER_REACTIVE_PHASE_3 = METRIC_AC_POWER_REACTIVE_PHASE_3

The AC reactive power in phase 3.

AC_TOTAL_HARMONIC_DISTORTION_CURRENT class-attribute instance-attribute ¤
AC_TOTAL_HARMONIC_DISTORTION_CURRENT = (
    METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT
)

The AC total harmonic distortion current.

AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_1 class-attribute instance-attribute ¤
AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_1 = (
    METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_1
)

The AC total harmonic distortion current in phase 1.

AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_2 class-attribute instance-attribute ¤
AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_2 = (
    METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_2
)

The AC total harmonic distortion current in phase 2.

AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_3 class-attribute instance-attribute ¤
AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_3 = (
    METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_3
)

The AC total harmonic distortion current in phase 3.

AC_VOLTAGE class-attribute instance-attribute ¤
AC_VOLTAGE = METRIC_AC_VOLTAGE

The AC electric potential difference.

AC_VOLTAGE_PHASE_1_N class-attribute instance-attribute ¤
AC_VOLTAGE_PHASE_1_N = METRIC_AC_VOLTAGE_PHASE_1_N

The AC electric potential difference between phase 1 and neutral.

AC_VOLTAGE_PHASE_1_PHASE_2 class-attribute instance-attribute ¤
AC_VOLTAGE_PHASE_1_PHASE_2 = (
    METRIC_AC_VOLTAGE_PHASE_1_PHASE_2
)

The AC electric potential difference between phase 1 and phase 2.

AC_VOLTAGE_PHASE_2_N class-attribute instance-attribute ¤
AC_VOLTAGE_PHASE_2_N = METRIC_AC_VOLTAGE_PHASE_2_N

The AC electric potential difference between phase 2 and neutral.

AC_VOLTAGE_PHASE_2_PHASE_3 class-attribute instance-attribute ¤
AC_VOLTAGE_PHASE_2_PHASE_3 = (
    METRIC_AC_VOLTAGE_PHASE_2_PHASE_3
)

The AC electric potential difference between phase 2 and phase 3.

AC_VOLTAGE_PHASE_3_N class-attribute instance-attribute ¤
AC_VOLTAGE_PHASE_3_N = METRIC_AC_VOLTAGE_PHASE_3_N

The AC electric potential difference between phase 3 and neutral.

AC_VOLTAGE_PHASE_3_PHASE_1 class-attribute instance-attribute ¤
AC_VOLTAGE_PHASE_3_PHASE_1 = (
    METRIC_AC_VOLTAGE_PHASE_3_PHASE_1
)

The AC electric potential difference between phase 3 and phase 1.

BATTERY_CAPACITY class-attribute instance-attribute ¤
BATTERY_CAPACITY = METRIC_BATTERY_CAPACITY

The capacity of the battery.

BATTERY_SOC_PCT class-attribute instance-attribute ¤
BATTERY_SOC_PCT = METRIC_BATTERY_SOC_PCT

The state of charge of the battery as a percentage.

BATTERY_TEMPERATURE class-attribute instance-attribute ¤
BATTERY_TEMPERATURE = METRIC_BATTERY_TEMPERATURE

The temperature of the battery.

DC_CURRENT class-attribute instance-attribute ¤
DC_CURRENT = METRIC_DC_CURRENT

The DC current.

DC_POWER class-attribute instance-attribute ¤
DC_POWER = METRIC_DC_POWER

The DC power.

DC_VOLTAGE class-attribute instance-attribute ¤
DC_VOLTAGE = METRIC_DC_VOLTAGE

The DC voltage.

EV_CHARGER_TEMPERATURE class-attribute instance-attribute ¤
EV_CHARGER_TEMPERATURE = METRIC_EV_CHARGER_TEMPERATURE

The temperature of the EV charger.

INVERTER_TEMPERATURE class-attribute instance-attribute ¤
INVERTER_TEMPERATURE = METRIC_INVERTER_TEMPERATURE

The temperature of the inverter.

INVERTER_TEMPERATURE_CABINET class-attribute instance-attribute ¤
INVERTER_TEMPERATURE_CABINET = (
    METRIC_INVERTER_TEMPERATURE_CABINET
)

The temperature of the inverter cabinet.

INVERTER_TEMPERATURE_HEATSINK class-attribute instance-attribute ¤
INVERTER_TEMPERATURE_HEATSINK = (
    METRIC_INVERTER_TEMPERATURE_HEATSINK
)

The temperature of the inverter heatsink.

INVERTER_TEMPERATURE_TRANSFORMER class-attribute instance-attribute ¤
INVERTER_TEMPERATURE_TRANSFORMER = (
    METRIC_INVERTER_TEMPERATURE_TRANSFORMER
)

The temperature of the inverter transformer.

SENSOR_AIR_PRESSURE class-attribute instance-attribute ¤
SENSOR_AIR_PRESSURE = METRIC_SENSOR_AIR_PRESSURE

The air pressure measured.

SENSOR_DEW_POINT class-attribute instance-attribute ¤
SENSOR_DEW_POINT = METRIC_SENSOR_DEW_POINT

The dew point measured.

SENSOR_IRRADIANCE class-attribute instance-attribute ¤
SENSOR_IRRADIANCE = METRIC_SENSOR_IRRADIANCE

The irradiance measured.

SENSOR_RELATIVE_HUMIDITY class-attribute instance-attribute ¤
SENSOR_RELATIVE_HUMIDITY = METRIC_SENSOR_RELATIVE_HUMIDITY

The relative humidity measured.

SENSOR_TEMPERATURE class-attribute instance-attribute ¤
SENSOR_TEMPERATURE = METRIC_SENSOR_TEMPERATURE

The temperature measured.

SENSOR_WIND_DIRECTION class-attribute instance-attribute ¤
SENSOR_WIND_DIRECTION = METRIC_SENSOR_WIND_DIRECTION

The direction of the wind measured.

SENSOR_WIND_SPEED class-attribute instance-attribute ¤
SENSOR_WIND_SPEED = METRIC_SENSOR_WIND_SPEED

The speed of the wind measured.

UNSPECIFIED class-attribute instance-attribute ¤
UNSPECIFIED = METRIC_UNSPECIFIED

The metric is unspecified (this should not be used).

frequenz.client.common.metrics.MetricConnection dataclass ¤

A connection to a metric representing from which a metric was obtained.

Source code in frequenz/client/common/metrics/_sample.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
@dataclass(frozen=True, kw_only=True)
class MetricConnection:
    """A connection to a metric representing from which a metric was obtained."""

    category: MetricConnectionCategory | int
    """The category of the connection from which the metric was obtained."""

    name: str | None = None
    """The name of the specific connection from which the metric was obtained.

    This is expected to be populated when the same `Metric` variant can be obtained from
    multiple distinct inputs or connection points on the component. Knowing the
    connection for the metric can help in certain control and monitoring applications.
    """

    def __str__(self) -> str:
        """Return a string representation of this connection."""
        category_name = (
            str(self.category)
            if isinstance(self.category, int)
            else f"<CATEGORY={self.category.name}>"
        )
        if self.name is not None:
            return f"{category_name}({self.name})"
        return category_name
Attributes¤
category instance-attribute ¤
category: MetricConnectionCategory | int

The category of the connection from which the metric was obtained.

name class-attribute instance-attribute ¤
name: str | None = None

The name of the specific connection from which the metric was obtained.

This is expected to be populated when the same Metric variant can be obtained from multiple distinct inputs or connection points on the component. Knowing the connection for the metric can help in certain control and monitoring applications.

Functions¤
__str__ ¤
__str__() -> str

Return a string representation of this connection.

Source code in frequenz/client/common/metrics/_sample.py 
115
116
117
118
119
120
121
122
123
124
def __str__(self) -> str:
    """Return a string representation of this connection."""
    category_name = (
        str(self.category)
        if isinstance(self.category, int)
        else f"<CATEGORY={self.category.name}>"
    )
    if self.name is not None:
        return f"{category_name}({self.name})"
    return category_name

frequenz.client.common.metrics.MetricConnectionCategory ¤

Bases: Enum

The categories of connections from which metrics can be obtained.

Source code in frequenz/client/common/metrics/_sample.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
@enum.unique
class MetricConnectionCategory(enum.Enum):
    """The categories of connections from which metrics can be obtained."""

    UNSPECIFIED = metrics_pb2.METRIC_CONNECTION_CATEGORY_UNSPECIFIED
    """The connection category was not specified (do not use)."""

    OTHER = metrics_pb2.METRIC_CONNECTION_CATEGORY_OTHER
    """A generic connection for metrics that do not fit into any other category."""

    BATTERY = metrics_pb2.METRIC_CONNECTION_CATEGORY_BATTERY
    """A connection to a metric representing a battery."""

    PV = metrics_pb2.METRIC_CONNECTION_CATEGORY_PV
    """A connection to a metric representing a PV (photovoltaic) array or string."""

    AMBIENT = metrics_pb2.METRIC_CONNECTION_CATEGORY_AMBIENT
    """A connection to a metric representing ambient conditions."""

    CABINET = metrics_pb2.METRIC_CONNECTION_CATEGORY_CABINET
    """A connection to a metric representing a cabinet or an enclosure."""

    HEATSINK = metrics_pb2.METRIC_CONNECTION_CATEGORY_HEATSINK
    """A connection to a metric representing a heatsink."""

    TRANSFORMER = metrics_pb2.METRIC_CONNECTION_CATEGORY_TRANSFORMER
    """A connection to a metric representing a transformer."""
Attributes¤
AMBIENT class-attribute instance-attribute ¤
AMBIENT = METRIC_CONNECTION_CATEGORY_AMBIENT

A connection to a metric representing ambient conditions.

BATTERY class-attribute instance-attribute ¤
BATTERY = METRIC_CONNECTION_CATEGORY_BATTERY

A connection to a metric representing a battery.

CABINET class-attribute instance-attribute ¤
CABINET = METRIC_CONNECTION_CATEGORY_CABINET

A connection to a metric representing a cabinet or an enclosure.

HEATSINK class-attribute instance-attribute ¤
HEATSINK = METRIC_CONNECTION_CATEGORY_HEATSINK

A connection to a metric representing a heatsink.

OTHER class-attribute instance-attribute ¤
OTHER = METRIC_CONNECTION_CATEGORY_OTHER

A generic connection for metrics that do not fit into any other category.

PV class-attribute instance-attribute ¤
PV = METRIC_CONNECTION_CATEGORY_PV

A connection to a metric representing a PV (photovoltaic) array or string.

TRANSFORMER class-attribute instance-attribute ¤
TRANSFORMER = METRIC_CONNECTION_CATEGORY_TRANSFORMER

A connection to a metric representing a transformer.

UNSPECIFIED class-attribute instance-attribute ¤
UNSPECIFIED = METRIC_CONNECTION_CATEGORY_UNSPECIFIED

The connection category was not specified (do not use).

frequenz.client.common.metrics.MetricSample dataclass ¤

A sampled metric.

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

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.

Source code in frequenz/client/common/metrics/_sample.py 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
@dataclass(frozen=True, kw_only=True)
class MetricSample:
    """A sampled metric.

    This represents a single sample of a specific metric, the value of which is either
    measured 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.
    """

    sample_time: datetime
    """The moment when the metric was sampled."""

    metric: Metric | int
    """The metric that was sampled."""

    # In the protocol this is float | AggregatedMetricValue, but for live data we can't
    # receive the AggregatedMetricValue, so we limit this to float for now.
    value: float | AggregatedMetricValue | None
    """The value of the sampled metric."""

    bounds: list[Bounds]
    """The 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.

    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
        ```
    """

    connection: MetricConnection | None = None
    """The electrical connection within the component from which the metric was sampled.

    This will be present when the same `Metric` can be obtained from multiple electrical
    connections within the component. Knowing the connection can help in certain control
    and monitoring applications.

    In cases where the component has just one connection for a metric, then the
    connection is `None`.

    Example:
        A hybrid inverter can have a DC string for a battery and another DC string for a
        PV array. The connection names could resemble, say, `dc_battery_0` (category
        `BATTERY`) and `dc_pv_0` (category `PV`). A metric like DC voltage can be
        obtained from both connections. For an application to determine the SoC of the
        battery using the battery voltage, which connection the voltage metric was
        sampled from is important.
    """

    def as_single_value(
        self, *, aggregation_method: AggregationMethod = AggregationMethod.AVG
    ) -> float | None:
        """Return the value of this sample as a single value.

        if [`value`][frequenz.client.common.metrics.MetricSample.value] is a `float`,
        it is returned as is. If `value` is an
        [`AggregatedMetricValue`][frequenz.client.common.metrics.AggregatedMetricValue],
        the value is aggregated using the provided `aggregation_method`.

        Args:
            aggregation_method: The method to use to aggregate the value when `value` is
                a `AggregatedMetricValue`.

        Returns:
            The value of the sample as a single value, or `None` if the value is `None`.
        """
        match self.value:
            case float() | int():
                return self.value
            case AggregatedMetricValue():
                match aggregation_method:
                    case AggregationMethod.AVG:
                        return self.value.avg
                    case AggregationMethod.MIN:
                        return self.value.min
                    case AggregationMethod.MAX:
                        return self.value.max
                    case unexpected:
                        assert_never(unexpected)
            case None:
                return None
            case unexpected:
                assert_never(unexpected)
Attributes¤
bounds instance-attribute ¤
bounds: list[Bounds]

The 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.

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
connection class-attribute instance-attribute ¤
connection: MetricConnection | None = None

The electrical connection within the component from which the metric was sampled.

This will be present when the same Metric can be obtained from multiple electrical connections within the component. Knowing the connection can help in certain control and monitoring applications.

In cases where the component has just one connection for a metric, then the connection is None.

Example

A hybrid inverter can have a DC string for a battery and another DC string for a PV array. The connection names could resemble, say, dc_battery_0 (category BATTERY) and dc_pv_0 (category PV). A metric like DC voltage can be obtained from both connections. For an application to determine the SoC of the battery using the battery voltage, which connection the voltage metric was sampled from is important.

metric instance-attribute ¤
metric: Metric | int

The metric that was sampled.

sample_time instance-attribute ¤
sample_time: datetime

The moment when the metric was sampled.

value instance-attribute ¤
value: float | AggregatedMetricValue | None

The value of the sampled metric.

Functions¤
as_single_value ¤
as_single_value(
    *, aggregation_method: AggregationMethod = AVG
) -> float | None

Return the value of this sample as a single value.

if value is a float, it is returned as is. If value is an AggregatedMetricValue, the value is aggregated using the provided aggregation_method.

PARAMETER DESCRIPTION
aggregation_method

The method to use to aggregate the value when value is a AggregatedMetricValue.

TYPE: AggregationMethod DEFAULT: AVG

RETURNS DESCRIPTION
float | None

The value of the sample as a single value, or None if the value is None.
Source code in frequenz/client/common/metrics/_sample.py 
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
def as_single_value(
    self, *, aggregation_method: AggregationMethod = AggregationMethod.AVG
) -> float | None:
    """Return the value of this sample as a single value.

    if [`value`][frequenz.client.common.metrics.MetricSample.value] is a `float`,
    it is returned as is. If `value` is an
    [`AggregatedMetricValue`][frequenz.client.common.metrics.AggregatedMetricValue],
    the value is aggregated using the provided `aggregation_method`.

    Args:
        aggregation_method: The method to use to aggregate the value when `value` is
            a `AggregatedMetricValue`.

    Returns:
        The value of the sample as a single value, or `None` if the value is `None`.
    """
    match self.value:
        case float() | int():
            return self.value
        case AggregatedMetricValue():
            match aggregation_method:
                case AggregationMethod.AVG:
                    return self.value.avg
                case AggregationMethod.MIN:
                    return self.value.min
                case AggregationMethod.MAX:
                    return self.value.max
                case unexpected:
                    assert_never(unexpected)
        case None:
            return None
        case unexpected:
            assert_never(unexpected)