Units used in the progress meter are not clear #883

Closed
zuzzurro opened this Issue Jun 16, 2016 · 13 comments

Projects

None yet

3 participants

@zuzzurro

The curl progress bar can be used for a quick estimation of the performance of the connection, however the number and the unit is confusing. It shows lowercase "k" where it should show KiBps and M instead of MiBps.

I'm not the only one confused as this link shows:

http://superuser.com/questions/951056/what-units-does-curl-use-for-bandwidth

I also think that probably bits should be used instead of bytes here as it's more common to use bits when talking about network speed (or at least it may have a -option for that)

@jay
Member
jay commented Jun 16, 2016

That's a fair point. I know I've heard it suggested a few times before but I can't find any references. curl has always used 1024 multiplier and I think it is too late to change that. I could see it showing 1234K instead of 1234k maybe, but there's not enough room there for KiB and MiB. And I disagree about using bits instead of bytes.

@jay jay added the enhancement label Jun 16, 2016
@bagder
Member
bagder commented Jun 16, 2016

The fact that a few persons have been uncertain what it means is not really a factor we can do much about. No matter what we do, there will be a few such persons. We've used the 1024 based system for the progress meter since the beginning and we've always showed bytes and bytes/second and that is in fact what most download tools show. I cannot see any strong reason to change that and I would object to the need for an option that would do nothing but multiplying the numbers with 8 just to show them as bits.

The most complete docs for the progress meter right now is probably the progress meter section in the everything curl boo

@bagder bagder closed this Jun 16, 2016
@jay
Member
jay commented Jun 16, 2016

I think you closed this prematurely at least let's have a discussion. What's wrong with something like --show-rate-units? We could dump them similar to this code PostUpload. Example:

Other data rate units:

                  5.18 Mbps
               5179.48 kbps
                  0.62 MiB/s
                632.26 KiB/s
                647.43 kB/s
             647435.00 B/s
@bagder
Member
bagder commented Jun 16, 2016

Ok, let's discuss it. But I want someone to first tell me exactly why another option and extra code for this is necessary. The days of just adding more options without careful consideration and thinking about the weight they add is over.

@bagder bagder reopened this Jun 16, 2016
@zuzzurro

The documentation is nice, but at least you should align the case of "K" Kilobytes between the docs and the actual printout..
Also, by looking for instance at
https://en.wikipedia.org/wiki/Binary_prefix

it seems clear that lowercase k is mandated by SI (and stand for 1000) while uppercase K is more common for computers and standard for instance in Jedec

@bagder
Member
bagder commented Jun 16, 2016

you should

... that is not an argument that works on me. We've been using this output for a very long time and I think stability and consistency now weighs more than "you should use SI nomenclature" speak. Sorry.

@zuzzurro

I did not say anything about aligning to SI nomenclature. Have you read you documentation page?

it says:

Units

The progress meter displays bytes and bytes per second.

It will also use suffixes for larger amounts of bytes, using the 1024 base system so 1024 is one kilobyte (1K), 2048 is 2K etc. curl supports these:
Suffix Amount Name
K 2^10 kilobyte
M 2^20 megabyte
G 2^30 gigabyte
T 2^40 terrabyte
P 2^50 petabyte

You use K everywhere, but then you print "k" in the meter...

@jay
Member
jay commented Jun 16, 2016

Dumping the other rate units isn't necessary but I think it could be helpful to give the curl tool user an option, at least, if they want to see kbps or something. As far as replacing k with K in the progress my thinking there is the latter is less ambiguous because there's no data rate unit that uses an uppercase K and represents bits (afaik).

@bagder
Member
bagder commented Jun 16, 2016

think it could be helpful to give the curl tool user an option

Sure, but that's like the -# option. Useful to like one in a million users. Not worth the code. Not worth the documentation. Because in the end the feature is so small and unimportant that nobody will bother to use it...

@zuzzurro
zuzzurro commented Jun 16, 2016 edited

I have been using and recommending curl since version 0.1 probably. I use it for downloading and I use it for troubleshooting.
I have been chasing today a nasty problem affecting services currently in production for THE major sport event ongoing in Europe and I used curl for my work.
As part of my troubleshooting knowing precisely the bandwidth available was key to understand where the problem lied.
After careful analysis i (thinking in terms of KBps) i almost had a heart attack thinking that maybe the units were wrong. I firstly checked the man page and there's no mention of that in there. Then I googled for it and lo and behold there's a whole page dedicated to it, in superuser.com.
Do as you wish, but at least put the documentation in the place that Unix people look for, the man page.

Thanks a lot for your kindness and understanding, and the tool that I will continue using

@jay
Member
jay commented Jun 16, 2016

Because in the end the feature is so small and unimportant that nobody will bother to use it...

So you say. Let's leave this open for a bit and see if there are any other opinions.

@bagder
Member
bagder commented Jun 17, 2016

The man page has been updated slightly to mention the units.

@zuzzurro

I'm happy with this change. Still the documentation uses one more time the uppercase K for Kilobytes while the code really has

snprintf(max5, 6, "%4" CURL_FORMAT_CURL_OFF_T "k", bytes/ONE_KILOBYTE);

It seems it would be easy to make documentation and code the same, but at least people will be able to look it up in the manual

@bagder bagder closed this in 046c2c8 Jun 21, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment