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 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..fcf8e7f5d 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,21 +45,21 @@ 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. """ + 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}" + ">" )