From 609c7ea90757a0f982a44e62fb82686552306ee2 Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Tue, 29 Oct 2024 10:41:11 +0100 Subject: [PATCH 1/3] Improve documentation of `ComponentMetricRequest` In particular clarify the use of the `namespace` attribute and its relationship with the channel name. Signed-off-by: Leandro Lucarella --- .../_component_metric_request.py | 39 +++++++++++-------- 1 file changed, 23 insertions(+), 16 deletions(-) diff --git a/src/frequenz/sdk/microgrid/_data_sourcing/_component_metric_request.py b/src/frequenz/sdk/microgrid/_data_sourcing/_component_metric_request.py index bdbbc2daf..29bf5c6dd 100644 --- a/src/frequenz/sdk/microgrid/_data_sourcing/_component_metric_request.py +++ b/src/frequenz/sdk/microgrid/_data_sourcing/_component_metric_request.py @@ -13,18 +13,28 @@ @dataclass class ComponentMetricRequest: - """A request object to start streaming a metric for a component.""" + """A request to start streaming a component's metric. + + Requesters use this class to specify which component's metric they want to subscribe + to, including the component ID, metric ID, and an optional start time. The + `namespace` is defined by the requester and influences the construction of the + channel name via the `get_channel_name()` method. + + The `namespace` allows differentiation of data streams for the same component and + metric. For example, requesters can use different `namespace` values to subscribe to + raw or resampled data streams separately. This ensures that each requester receives + the appropriate type of data without interference. Requests with the same + `namespace`, `component_id`, and `metric_id` will use the same channel, preventing + unnecessary duplication of data streams. + + The requester and provider must use the same channel name so that they can + independently retrieve the same channel from the `ChannelRegistry`. This is + achieved by using the `get_channel_name` method to generate the name on both sides + based on parameters set by the requesters. + """ namespace: str - """The namespace that this request belongs to. - - Metric requests with a shared namespace enable the reuse of channels within - that namespace. - - If for example, an actor making a multiple requests, uses the name of the - actor as the namespace, then requests from the actor will get reused when - possible. - """ + """A client-defined identifier influencing the channel name.""" component_id: int """The ID of the requested component.""" @@ -35,17 +45,14 @@ class ComponentMetricRequest: start_time: datetime | None """The start time from which data is required. - When None, we will stream only live data. + If None, only live data is streamed. """ def get_channel_name(self) -> str: - """Return a channel name constructed from Self. - - This channel name can be used by the sending side and receiving sides to - identify the right channel from the ChannelRegistry. + """Construct the channel name based on the request parameters. Returns: - A string denoting a channel name. + A string representing the channel name. """ return ( f"component_metric_request Date: Tue, 29 Oct 2024 10:41:49 +0100 Subject: [PATCH 2/3] Make the channel name shorter for `ComponentMetricRequest` The `start_time` is optional, and rarely used (for the time being not even supported), so there is no need to include it in the channel name when it is not present at all. Signed-off-by: Leandro Lucarella --- .../_data_sourcing/_component_metric_request.py | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/frequenz/sdk/microgrid/_data_sourcing/_component_metric_request.py b/src/frequenz/sdk/microgrid/_data_sourcing/_component_metric_request.py index 29bf5c6dd..fcf8e7f5d 100644 --- a/src/frequenz/sdk/microgrid/_data_sourcing/_component_metric_request.py +++ b/src/frequenz/sdk/microgrid/_data_sourcing/_component_metric_request.py @@ -54,9 +54,12 @@ def get_channel_name(self) -> str: Returns: A string representing the channel name. """ + start = f",start={self.start_time}" if self.start_time else "" return ( - f"component_metric_request" + f"metric_id={self.metric_id.name}" + f"{start}" + ">" ) From 15e8d0201e9bff7403fedca74f03a20e27a563ff Mon Sep 17 00:00:00 2001 From: Leandro Lucarella Date: Tue, 29 Oct 2024 10:44:14 +0100 Subject: [PATCH 3/3] Update release notes Signed-off-by: Leandro Lucarella --- RELEASE_NOTES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 907cef2e1..487e1b4dd 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -17,6 +17,7 @@ * The `MovingWindow` now take all arguments as keyword-only to avoid mistakes. * The `frequenz-quantities` dependency was bumped to `1.0.0rc3`. +* The `ComponentMetricsRequest` now produces a channel name without the `start_date` if the `start_date` is `None`. If you are somehow relying on the old behavior, please update your code. ## New Features