Add support for bounds in client (frequenz-floss#98)

Bounds can now be requested via the client and are provided through the
flat iterator. They can be identified via their category
`metric_bound[i]_{upper,lower}`. Each individual bound is provided as
its own sample.

Support for states and bound is also added to the CLI tool via the
`--bounds` flag.

Fixes
frequenz-floss#20.

Author: cwasicki

RELEASE_NOTES.md

@@ -13,8 +13,11 @@
 * States can now be requested via the client and are provided through the flat iterator.
   They can be identified via their category `state`, `warning` and `error`, respectively.
   Each individual state is provided as its own sample.
+* Bounds can now be requested via the client and are provided through the flat iterator.
+  They can be identified via their category `metric_bound[i]_{upper,lower}`.
+  Each individual bound is provided as its own sample.
 
-* Support for states is also added to the CLI tool via the `--states` flag.
+* Support for states and bound is also added to the CLI tool via the `--states` and `--bounds` flag, respectively.
 
 ## Bug Fixes
 

src/frequenz/client/reporting/__main__.py

@@ -39,6 +39,11 @@ def main() -> None:
         action="store_true",
         help="Include states in the output",
     )
+    parser.add_argument(
+        "--bounds",
+        action="store_true",
+        help="Include bounds in the output",
+    )
     parser.add_argument(
         "--start",
         type=datetime.fromisoformat,
@@ -72,6 +77,7 @@ def main() -> None:
             args.end,
             args.resolution,
             states=args.states,
+            bounds=args.bounds,
             service_address=args.url,
             key=args.key,
             fmt=args.format,
@@ -88,6 +94,7 @@ async def run(
     end_dt: datetime,
     resolution: int,
     states: bool,
+    bounds: bool,
     service_address: str,
     key: str,
     fmt: str,
@@ -102,6 +109,7 @@ async def run(
         end_dt: end datetime
         resolution: resampling resolution in sec
         states: include states in the output
+        bounds: include bounds in the output
         service_address: service address
         key: API key
         fmt: output format
@@ -129,6 +137,7 @@ def data_iter() -> AsyncIterator[MetricSample]:
             end_dt=end_dt,
             resolution=resolution,
             include_states=states,
+            include_bounds=bounds,
         )
 
     if fmt == "iter":

src/frequenz/client/reporting/_client.py

@@ -98,6 +98,23 @@ def __iter__(self) -> Iterator[MetricSample]:
                     metric=met,
                     value=value,
                 )
+                for i, bound in enumerate(msample.bounds):
+                    if bound.lower:
+                        yield MetricSample(
+                            timestamp=ts,
+                            microgrid_id=mid,
+                            component_id=cid,
+                            metric=f"{met}_bound_{i}_lower",
+                            value=bound.lower,
+                        )
+                    if bound.upper:
+                        yield MetricSample(
+                            timestamp=ts,
+                            microgrid_id=mid,
+                            component_id=cid,
+                            metric=f"{met}_bound_{i}_upper",
+                            value=bound.upper,
+                        )
             for state in cdata.states:
                 ts = state.sampled_at.ToDatetime()
                 for name, category in {
@@ -145,6 +162,7 @@ async def list_single_component_data(
         end_dt: datetime,
         resolution: int | None,
         include_states: bool = False,
+        include_bounds: bool = False,
     ) -> AsyncIterator[MetricSample]:
         """Iterate over the data for a single metric.
 
@@ -156,6 +174,7 @@ async def list_single_component_data(
             end_dt: The end date and time.
             resolution: The resampling resolution for the data, represented in seconds.
             include_states: Whether to include the state data.
+            include_bounds: Whether to include the bound data.
 
         Yields:
             A named tuple with the following fields:
@@ -169,6 +188,7 @@ async def list_single_component_data(
             end_dt=end_dt,
             resolution=resolution,
             include_states=include_states,
+            include_bounds=include_bounds,
         ):
             for entry in batch:
                 yield entry
@@ -183,6 +203,7 @@ async def list_microgrid_components_data(
         end_dt: datetime,
         resolution: int | None,
         include_states: bool = False,
+        include_bounds: bool = False,
     ) -> AsyncIterator[MetricSample]:
         """Iterate over the data for multiple microgrids and components.
 
@@ -194,6 +215,7 @@ async def list_microgrid_components_data(
             end_dt: The end date and time.
             resolution: The resampling resolution for the data, represented in seconds.
             include_states: Whether to include the state data.
+            include_bounds: Whether to include the bound data.
 
         Yields:
             A named tuple with the following fields:
@@ -210,6 +232,7 @@ async def list_microgrid_components_data(
             end_dt=end_dt,
             resolution=resolution,
             include_states=include_states,
+            include_bounds=include_bounds,
         ):
             for entry in batch:
                 yield entry
@@ -225,6 +248,7 @@ async def _list_microgrid_components_data_batch(
         end_dt: datetime,
         resolution: int | None,
         include_states: bool = False,
+        include_bounds: bool = False,
     ) -> AsyncIterator[ComponentsDataBatch]:
         """Iterate over the component data batches in the stream.
 
@@ -238,6 +262,7 @@ async def _list_microgrid_components_data_batch(
             end_dt: The end date and time.
             resolution: The resampling resolution for the data, represented in seconds.
             include_states: Whether to include the state data.
+            include_bounds: Whether to include the bound data.
 
         Yields:
             A ComponentsDataBatch object of microgrid components data.
@@ -262,7 +287,13 @@ def dt2ts(dt: datetime) -> PBTimestamp:
             if include_states
             else PBIncludeOptions.FilterOption.FILTER_OPTION_EXCLUDE
         )
+        incl_bounds = (
+            PBIncludeOptions.FilterOption.FILTER_OPTION_INCLUDE
+            if include_bounds
+            else PBIncludeOptions.FilterOption.FILTER_OPTION_EXCLUDE
+        )
         include_options = PBIncludeOptions(
+            bounds=incl_bounds,
             states=incl_states,
         )