Skip to content

Improve docs for AddComponentBounds RPC #318

@tiyash-basu-frequenz

Description

@tiyash-basu-frequenz

What's needed?

The AddComponentBounds RPC is the following:

// Adds inclusion bounds for a given metric of a given component. Returns the
// time at which the bounds will expire (as a timestamp (UTC)).
//
// The request parameters allows users to select a duration until
// which the bounds will stay in effect. If no duration is provided, then the
// bounds will be removed after a default duration of 5 seconds.
//
// Inclusion bounds give the range that the system will try to keep the
// metric within. If the metric goes outside of these bounds, the system will
// try to bring it back within the bounds.
// If the bounds for a metric are [[`lower_1`, `upper_1`],
// [`lower_2`, `upper_2`]], then this metric's `value` needs to comply with
// the constraints
// `lower_1 <= value <= upper_1` OR `lower_2 <= value <= upper_2`.
//
// If multiple inclusion bounds have been provided for a metric, then the
// overlapping bounds are merged into a single bound, and non-overlapping
// bounds are kept separate.
// E.g. if the bounds are [[0, 10], [5, 15], [20, 30]], then the resulting
// bounds will be [[0, 15], [20, 30]].
//
// The following diagram illustrates how bounds are applied:
// ```
// lower_1 upper_1
// <----|========|--------|========|-------->
// lower_2 upper_2
// ```
// The bounds in this example are `[[lower_1, upper_1], [lower_2, upper_2]]`.
// ---- values here are considered out of range.
// ==== values here are considered within range.
//
// Note that for power metrics, regardless of the bounds, 0W is always
// allowed.
rpc AddComponentBounds(AddComponentBoundsRequest)
returns (AddComponentBoundsResponse);

The docs may seem ambiguous due to the inclusion of the legacy term inclusion.

Proposed solution

There are at least two potential improvements here:

  • The docs still use the term inclusion, which is no relevant to the Microgrid API anymore, and should be removed.
  • The example section should be extended, to contain example of different scenarios, along with explanation of the behaviour of the API in those cases.

Use cases

No response

Alternatives and workarounds

No response

Additional context

No response

Metadata

Metadata

Assignees

No one assigned

    Labels

    part:❓We need to figure out which part is affectedpriority:❓We need to figure out how soon this should be addressedtype:enhancementNew feature or enhancement visitble to users

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions