unable to find documentation on meaning of CPU colours or monocrome chars

[bahbarnett]

Hi,

Decades long 'top' user, but am moving to htop due to its coolness, and just so many cores these days.

As a new user, I looked in the man pages, in the /usr/share/doc/README (Debian bullseye user), and the onboard help for info, but it's just not clear to me what the CPU chart chars mean. FYI, htop -v shows 3.0.5.

When I do look at the help, I see this:

CPU usage bar: [low-priority/normal/kernel/virtualiz               used%]
Memory bar:    [used/buffers/cache                            used/total]
Swap bar:      [used                                          used/total]
Type and layout of header meters are configurable in the setup screen.
In monochrome, meters display as different chars, in order: |#*@$%&.

OK, we have order, but what does '|#*@$%&' map to?

The best I can guess, is the CPU usage bar info above. But this lists 4 things,. yet the 'map' of chars lists 7 things.

If it's a list of "this maps to CPU, then Mem, then Swap", we're looking at 8 things. And even if I double up on 'used', so it's 7 things, the | shows up in 'cpu' and 'mem' bars, so it doesn't jive with the list of chars. EG, | in 'mem' cannot be 'low-priority'.

So I am confused as to what means what.

Maybe I'm being obtuse here, but if so, please un-obtusify me. :P

Thanks

[BenBE]

Will have to look in the code, but IIRC with 3.0.5 there were still some information in the help screen missing. For the development head on the main branch That part of the help screen looks like this:

htop 3.2.0-dev - (C) 2004-2019 Hisham Muhammad. (C) 2020-2021 htop dev team.
Released under the GNU GPLv2+. See 'man' page for more info.

CPU usage bar: [low/normal/kernel/irq/soft-irq/steal/guest/io-wait used%]
Memory bar:    [used/buffers/shared/cache                     used/total]
Swap bar:      [used/cache                                    used/total]
Type and layout of header meters are configurable in the setup screen.

Process state: R: running; S: sleeping; T: traced/stopped; Z: zombie; D: disk sleep

In the code this is rendered by the following lines of code (and the few lines around that). The important part is that this depends on one configuration option: st->settings->detailedCPUTime, which if enabled displays the used CPU time in finer detail by splitting out irq, soft-irq and io-wait times from the kernel time.

For the display of those meters the important part are these lines with BarMeterMode_characters[i] being the character to print and i being the index of the graph element to draw. That mapping is 1:1 like the list mentioned above, thus | maps to the first item drawn (low), # (normal), etc.

IMHO there are two issues here, that make this a bit confusing: First that the character string isn't dependent on the configuration setting and always shows the full list* and second that the list shown in the meter to explain the mapping is dependent on the setting and thus may "hide" some options that could be displayed in the meter.

[bahbarnett]

OK, things make sense now. Thanks.

I looked in the manpage, and others might too, so the simplest method might be to just add detailed info there. Lots of room to make it clear, and no code needed. Removing the "In monochrome, meters display as different chars, in order: |#*@$%&.", IMO, would be preferable to inaccurate (from initial end-user impressions) information, or even "See manpage for monochrome this and that" could work too.

Just a thought, and thanks again for the info.

[BenBE]

My Troff foo isn't good enough for tables, thus only a small idea: In the manpage where it describes the CPU meter we could insert a small table with the attribute and two columns showing providing the attribute name, its color, its monochrome replacement and a short description of what this attribute represents.

Note that the replacement characters apply to all meters (with more than one attribute), not just the CPU display. So e.g. for the memory meter you have a similar mapping of those characters that's currently under-accounted for. Thus the above idea probably should be replicated for all those other meter's descriptions too.