QoS CLI – Warning in case when provided burst is lower than 80% BW

[Arkady Shtempler]

According QoS documentation https://docs.openstack.org/neutron/queens/admin/config-qos.html in order to get the desired BW limit, user must set Burst value which is bigger than 80% of provided by user BW.

--- Configuring the proper burst value is very important. If the burst value is set too low, bandwidth usage will be throttled even with a proper bandwidth limit setting. This issue is discussed in various documentation sources, for example in Juniper’s documentation. Burst value for TCP traffic can be set as 80% of desired bandwidth limit value. For example, if the bandwidth limit is set to 1000kbps then enough burst value will be 800kbit. If the configured burst value is too low, achieved bandwidth limit will be lower than expected. If the configured burst value is too high, too few packets could be limited and achieved bandwidth limit would be higher than expected. ---

In addition to that (note in documentation) we can add this "80% validation" at least on CLI level (not relevant for Rest API) and to prompt some Warning message to the user, in case he’s trying to set burst lower than 80% BW, so he could understand that desired BW won’t be reached.

[Brian Haley (brian-haley)]

For reference, this is what the admin guide says:

"The QoS implementation requires a burst value to ensure proper behavior of bandwidth limit rules in the Open vSwitch and Linux bridge agents. If you do not provide a value, it defaults to 80% of the bandwidth limit which works for typical TCP traffic."

So if you don't specify it, the default of 80% seems like what is wanted, right?

I'm not sure what validation will accomplish since it isn't technically invalid to specify something other than 80%, it just might not function as expected.

I will ping someone more knowledgable with QoS to add their comments.

[Arkady Shtempler (ashtempl)]

There are two notes in documentation regarding 80% Burst.
 1) Default - in case no value is provided for Burst, default will be set to 80% BW - I'm totally OK with it.
 2) Both BW and Burst are set by user in command line, for example:
openstack network qos rule create --type bandwidth-limit --max-kbps 3000 --max-burst-kbits 7 --egress bw-limiter
So in above command user is trying to set BW to 3000 and Burst to 7 (let's say he missed the note about 80% burst in documentation)
So, my suggestion is to add a simple validation of provided by user values and in case when burst is not 80% of BW to prompt user Warning message that will say "WARNING - Burst should be 80% of your BW, desired BW won't be reached with BW 3000 and Burst 7" (or something lie that)
In addition i think that we'll need to add "Yes/No" option, so user will be able to set the parameters anyway, in spite of WARNING message or to reset them.

[Slawek Kaplonski (slaweq)]

Such warning should be added in OpenStack client (if should be added at all).
Personally I don't think that it could be useful/necessary. Operator should read documentation and know about such limitations.
If this should be done in OSC then You should open bug report in storyboard (https://storyboard.openstack.org) instead of launchpad.

[Arkady Shtempler (ashtempl)]

I don't think that operators are 100% familiar with each parameter in command line (including notes) and i'm not sure that first thing operator will do, once desired BW is not reached, is searching notes in OSP documentation, they will probably think that QoS is not working. We can easily prevent them to think so, by adding this Warning message.
Correct me if i'm wrong, but I think that adding such functionality into the code is not something complicated.
Once we agree that this bug (RFE) is relevant, I'll open it on storyboard.

[Armando Migliaccio (armando-migliaccio)]

It seems this is related to bug 1778407. While I appreciate there may be two separate angles to the conversation, may I suggest we keep the discussion in a single place? This would help everybody interested in this topic to be informed and the same page.

Thanks very much for reporting this issue!

[Arkady Shtempler (ashtempl)]

This bug is not duplicated to https://bugs.launchpad.net/neutron/+bug/1778407

Bug 1778407 - is related to DOCUMENTATION
This bug/enhancement - is about adding burst validation to CODE

[Armando Migliaccio (armando-migliaccio)]

In Launchpad there's no good way to link two bug reports and to keep the conversation in one place except making one report duplicate of the other. I imagined that any code changes would lead to documentation changes and that's why I proposed to mark one duplicate so that we can track whatever code/doc improvement in a single place. If you disagree please feel free to hit the - button on bug 1778407

[Arkady Shtempler (ashtempl)]

@Armando, correct me if i'm wrong, but it makes me feel like the main idea of this specific bug is getting lost :(
Do you think that we need this "Warning" message in CLI? Yes or No?
I think that we have to make the decisions previously to finding the best way to track it.

[Armando Migliaccio (armando-migliaccio)]

Just to make sure I understand your intentions correctly. You have been raising two issues around the same QoS use case:

1) Warn the CLI user of a potential edge case given the input parameters;
2) Revise the documentation to further clarify how to handle the specific QoS case.

One could argue that a misuse of the CLI may be the results of a confusing/incomplete/non-inviting documentation.

I was suggesting to track the improvements with a single report. If you'd want prefer to track it separately, that's fine by me.

[Arkady Shtempler (ashtempl)]

Yes, these two issues are around the same QoS use case (80% Bandwidth), but there is no logical bond between them, so I want to track these bugs separately.

[Lajos Katona (lajos-katona)]

@Arkady: I checked the CLI in python-openstackclient, and now for --max-burst-kbits there is this help message:
"Maximum burst in kilobits, 0 means automatic"

Do you think that adding some extra text that default is 80% of the --max-kbps value?

[Lajos Katona (lajos-katona)]

@Arkady: back to your suggestion to add a validator or similar for max-burst-kbps value to check that is 80% of the max-kbps value (if set by the user) and
* give warning if not => that is possible as I see in python-openstackclient, but personally I don't feel that "openstackish", perhaps others have other opinion.
** this way the user should see a warning
** she/he can update the rule to change the burst value to 80% of the max-kbps.

* To give a yes/no option to the user if she/he accept the warning and stop the execution of the command if no was selected, to tell the truth I feel that this is far from how openstack CLI works.

[Slawek Kaplonski (slaweq)]

@Lajos: I think that Your idea with adding such info to help message would be very good and simple solution for this issue. I'm fine with that.

[Lajos Katona (lajos-katona)]

I uploaded a patch for the help message extension, and marked as closes-bug, we can change that if the decision is to change the CLI behavior as well:
https://review.openstack.org/588168

[OpenStack Infra (hudson-openstack)]

Related fix proposed to branch: master
Review: https://review.openstack.org/591623

[Lajos Katona (lajos-katona)]

https://review.openstack.org/588168 was merged to python-openstackclient

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/591623
Committed: https://git.openstack.org/cgit/openstack/neutron/commit/?id=52f0096d13192aa35287e9f552c8245401dba087
Submitter: Zuul
Branch: master

commit 52f0096d13192aa35287e9f552c8245401dba087
Author: Slawek Kaplonski <email address hidden>
Date: Tue Aug 14 13:05:20 2018 +0200

    [Docs] Update note about default burst value in QoS bw limit

    This patch combines two separate notes about burst value in
    QoS bandwidth limit rules into one to make it more clear for
    readers.

    Change-Id: I48fa93969416db0b0049af533b6aa4021fa22616
    Related-Bug: #1777866

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/python-openstackclient 3.17.0 release.

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/python-openstackclient 3.18.0 release.