Rename MetricSample.source to MetricSample.connection (#347)

This commit renames the `source` field in the `MetricSample` message to
`connection`. This change is made to clarify the purpose of the field,
as it specifically refers to the connection point from which the metric
was obtained, rather than a generic source.

closes #260

Author: tiyash-basu-frequenz

RELEASE_NOTES.md

@@ -37,6 +37,7 @@
 - Renamed `sampled_at` timestamps for metric samples to `sample_time`.
 - Remove `SensorMetricSample` in favour of using `MetricSample` for sensors.
 - Remove `SensorMetric` enum, since it was unused and redundant.
+- Renamed `MetricSample.source` to `MetricSample.connection` to make it more specific as to what it refers to.
 
 ## Bug Fixes
 

proto/frequenz/api/common/v1/metrics/metrics.proto

@@ -222,19 +222,27 @@ message MetricSample {
   // ==== values here are allowed and will be accepted
   repeated Bounds bounds = 4;
 
-  // An optional string that can be used to identify the source of the metric.
+  // An optional string that can be used to identify 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 sensors in the component. Knowing the source of the
-  // metric can help in certain control and monitoring applications.
+  // 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.
   //
-  // 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.
+  // E.g.,
+  // - A PV inverter might have multiple PV strings connected (e.g.,
+  //   `pv_string_1`, `pv_string_2`).
+  // - A hybrid inverter can have a DC connection for a battery (e.g.,
+  //   `dc_battery_0`) and another for a PV array (e.g., `dc_pv_0`). A metric
+  //   like DC voltage can be obtained from both connections. For an application
+  //   to determine the SoC of the battery using its voltage, identifying the
+  //   `dc_battery_0` connection is important.
+  // - A sensor unit might report temperature from different connected probes
+  //   (e.g., `temp_sensor_outdoor`, `temp_sensor_indoor`).
   //
-  // 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.
-  optional string source = 5;
+  // In cases where the component has just one such connection for a metric,
+  // or the context is otherwise unambiguous, this field is not expected to
+  // be present, because the connection is implicit.
+  optional string connection = 5;
 }

proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto

@@ -528,12 +528,14 @@ message ElectricalComponentStateSnapshot {
 //          metric: "DC_VOLTAGE_V",
 //          value: {},
 //          bounds: {},
+//          connection: "battery_0"
 //        },
 //        {
 //          sample_time: "2023-10-01T00:00:00Z",
 //          metric: "DC_VOLTAGE_V",
 //          value: {},
 //          bounds: {},
+//          connection: "pv_0"
 //        }
 //      ],
 //      states: [

proto/frequenz/api/common/v1/microgrid/sensors/sensors.proto

@@ -182,14 +182,14 @@ message SensorStateSnapshot {
 //          metric: "METRIC_SENSOR_TEMPERATURE",
 //          value: metric_value_variant: {simple_metric: {value: 23.5},
 //          bounds: {}
-//          source: {}
+//          connection: {}
 //        },
 //        {
 //          sample_time: "2023-10-01T00:00:00Z",
 //          metric: "METRIC_SENSOR_RELATIVE_HUMIDITY",
 //          value: metric_value_variant: {simple_metric: {value: 23.5},
 //          bounds: {}
-//          source: "humidity_sensor_1"
+//          connection: "humidity_sensor_1"
 //        }
 //      ],
 //      states: [
@@ -206,6 +206,10 @@ message SensorData {
   uint64 sensor_id = 1;
 
   // List of measurements for a metric of the specific microgrid sensor.
+  //
+  // Note that these metric samples will not necessarily contain bounds, since
+  // bounds are required for control operations, which are not applicable to
+  // sensors.
   repeated frequenz.api.common.v1.metrics.MetricSample metric_samples = 2;
 
   // List of states of a specific microgrid sensor.