Introduce API v1alpha11 #151
Conversation
github-actions
bot
added
part:docs
stefan-brus-frequenz
force-pushed
the
v1alpha11
branch
from
31e2026 to
51251e4
Compare
Signed-off-by: Stefan Brus <stefan.brus@frequenz.com>
stefan-brus-frequenz
force-pushed
the
v1alpha11
branch
from
51251e4 to
fb06178
Compare
There was a problem hiding this comment.
Pull request overview
This PR introduces API version v1alpha11 of the Frequenz Reporting Service, focusing on clarifying and improving the documentation of resampling and streaming semantics. The primary goal is to enhance documentation correctness and consistency while introducing some breaking API changes.
Changes:
- Clarified resampling semantics: explicitly defined as time-grid materialization with interval-based timestamps and upsert stream behavior
- Updated
sample_timesemantics to represent origin time when not resampled, interval start when resampled - Changed
TimeFiltermessage to usefrequenz.api.common.v1alpha8.types.Intervalinstead of separatestart_timeandend_timefields - Renamed service from
ReportingtoReportingServiceto align with other Frequenz services - Enhanced documentation with examples showing empty values, interval-based timestamps, and non-append-only behavior
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 11 comments.
| File | Description |
|---|---|
| proto/frequenz/api/reporting/v1alpha11/reporting.proto | New API version introducing comprehensive documentation updates for resampling and streaming semantics, service renaming, and TimeFilter restructuring |
| RELEASE_NOTES.md | Added release notes documenting the new v1alpha11 API version and its changes |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // The formula and metric must have been specified in the corresponding | ||
| // request. A single aggregated sample for the metric is returned in the | ||
| // sample field. Each message covers a single formula. For multiple | ||
| // formulars provided in the request, expect sequential messages in the |
There was a problem hiding this comment.
Spelling error: "formulars" should be "formulas".
| // formulars provided in the request, expect sequential messages in the | |
| // formulas provided in the request, expect sequential messages in the |
| // | ||
| // !!! caution "Supported metrics" | ||
| // Ensure the chosen metric is supported by all relevant microgrid | ||
| // electrical components. Failure to meet these conditions might results |
There was a problem hiding this comment.
Grammar error: "might results" should be "might result".
| // electrical components. Failure to meet these conditions might results | |
| // electrical components. Failure to meet these conditions might result |
| // resampled data. | ||
| // | ||
| // !!! example "Example: Downsampling from 1-second to 15-minute intervals" | ||
| // The stored time series has a effective sampling resolution of Δt = 1 |
There was a problem hiding this comment.
Grammar error: "has a effective" should be "has an effective".
| // The stored time series has a effective sampling resolution of Δt = 1 | |
| // The stored time series has an effective sampling resolution of Δt = 1 |
| // | ||
| // 2. Dedicated formulas: These support basic math operators while | ||
| // concatenating microgrid electrical component IDs. | ||
| // Example: `#1 + #2 - #3`, `(#3 * #2) /# 1` |
There was a problem hiding this comment.
Possible typo in formula example: /# 1 appears to have misplaced space. Should likely be / #1.
| // Example: `#1 + #2 - #3`, `(#3 * #2) /# 1` | |
| // Example: `#1 + #2 - #3`, `(#3 * #2) / #1` |
| // microgrids and electrical components. | ||
| // | ||
| // !!! note | ||
| // The filter can specify a list of metrics to be return but also |
There was a problem hiding this comment.
Grammar error: "to be return" should be "to be returned".
| // The filter can specify a list of metrics to be return but also | |
| // The filter can specify a list of metrics to be returned but also |
| // Semantics: | ||
| // - If `end_time` is provided, it MUST be ≤ the current server time. The | ||
| // server streams all samples t where start_time ≤ t < end_time and | ||
| // then closes the stream. | ||
| // | ||
| // - If `end_time` is omitted, the server streams all historical samples | ||
| // t ≥ start_time (if provided) and then continues streaming new samples | ||
| // in real time. The stream remains open indefinitely. | ||
| // | ||
| // - If `start_time` is omitted: | ||
| // – and `end_time` is omitted: the stream produces no historical data | ||
| // and begins streaming real-time samples only. | ||
| // – and `end_time` is provided: the historical window is empty and | ||
| // the stream closes immediately. | ||
| // | ||
| // Validation rules: | ||
| // - end_time > now() → INVALID_ARGUMENT |
There was a problem hiding this comment.
Documentation refers to start_time and end_time fields, but the actual field is now interval of type frequenz.api.common.v1alpha8.types.Interval. The documentation should be updated to reference the correct field structure (e.g., interval.start and interval.end or similar, depending on the Interval message definition).
| // This message represents the aggregated - across multiple electrical | ||
| // components or sensors- result for one metric and one aggregation |
There was a problem hiding this comment.
Grammar/formatting issue: Inconsistent spacing around hyphens/dashes. "aggregated - across multiple electrical components or sensors- result" should be "aggregated—across multiple electrical components or sensors—result" (em dashes without spaces) or "aggregated (across multiple electrical components or sensors) result" (parentheses) for better readability.
| // This message represents the aggregated - across multiple electrical | |
| // components or sensors- result for one metric and one aggregation | |
| // This message represents the result of aggregation across multiple electrical | |
| // components or sensors for one metric and one aggregation |
| // The formula and metric must have been specified in the corresponding | ||
| // request. A single aggregated sample for the metric is returned in the | ||
| // sample field. Each message covers a single formula. For multiple | ||
| // formulars provided in the request, expect sequential |
There was a problem hiding this comment.
Spelling error: "formulars" should be "formulas".
| // formulars provided in the request, expect sequential | |
| // formulas provided in the request, expect sequential |
| // which are included in the data stream. If multiple `MetricConnections` | ||
| // messages are specified for different metrics, the filters apply | ||
| // separately to each metric. The `connections` specified here correspond | ||
| // to the `connections` field in the `MetricSample` message defined in |
There was a problem hiding this comment.
Incomplete sentence: "which are included in the data stream" appears to be missing a word. Should likely be "which connections are included" or similar.
| // which are included in the data stream. If multiple `MetricConnections` | |
| // messages are specified for different metrics, the filters apply | |
| // separately to each metric. The `connections` specified here correspond | |
| // to the `connections` field in the `MetricSample` message defined in | |
| // which connections are included in the data stream. If multiple | |
| // `MetricConnections` messages are specified for different metrics, the | |
| // filters apply separately to each metric. The `connections` specified | |
| // here correspond to the `connections` field in the `MetricSample` |
| // aggregation_config: { | ||
| // microgrid_id: 1, | ||
| // metric: "DC_VOLTAGE_V", | ||
| // aggregation_formula: "avg(1,2,3)" |
There was a problem hiding this comment.
Inconsistent formula syntax: avg(1,2,3) should use avg(#1,#2,#3) to be consistent with the established pattern for referencing electrical component IDs (see lines 371, 382, 930).
| // aggregation_formula: "avg(1,2,3)" | |
| // aggregation_formula: "avg(#1,#2,#3)" |
3 participants
Replaces #146
This PR clarifies resampling and streaming semantics of the Reporting API. The primary focus of this change is documentation correctness and consistency. Some breaking API changes are introduced.
Key improvements:
Resampling is now explicitly defined as time-grid materialization over telemetry data, applied to both historical and real-time streams.
sample_time semantics are clarified:
origin time when not resampled,
interval start when resampled.
Resampled streams are time-keyed upsert streams:
metric values may be unset if no data contributed to an interval,
intervals may be re-emitted with updated values when late telemetry arrives.
Examples and field documentation were updated to reflect:
empty values,
interval-based timestamps,
non-append-only behavior.
Some schema or wire-format changes were made.