--debug LEVEL not documented in CLI

--debug LEVEL not documented in CLI

[jgart]

Hi Guixers,

--debug is not documented in the CLI. 

What debug LEVEL's are permissible?

For example, is 79 allowed?

Or 5, 4, 3, 2, 1?

What is the difference between the LEVELs? Where is the input LEVEL cutoff? At 6?

The --help says the following only:

--debug=LEVEL      produce debugging output at LEVEL

WDYT

Re: --debug LEVEL not documented in CLI

[Wilko Meyer]

Hi,
 
"jgart" <jgart@dismail.de> writes:

> What debug LEVEL's are permissible?
>
> For example, is 79 allowed?
>
> Or 5, 4, 3, 2, 1?
>
> What is the difference between the LEVELs? Where is the input LEVEL cutoff? At 6?

The documentation[0] on common build options seems to be a bit more
detailed on this at least on what range is available:

>> Produce debugging output coming from the build daemon. level must be
>> an integer between 0 and 5; higher means more verbose output. Setting
>> a level of 4 or more may be helpful when debugging setup issues with
>> the build daemon.

So a range between 0 and 5 seems to be in use. It's possible to use a
level >5, e.g. 79 or something else, which has the same effect as using
5 as a debug level.

However it's not quite clear from the documentaton itself what the
respective debug levels do. The levels seem to be defined in
nix/libutil/types.hh:

typedef enum {
    lvlError = 0,
    lvlInfo,
    lvlTalkative,
    lvlChatty,
    lvlDebug,
    lvlVomit
} Verbosity;

and all/most(?) levels seem to be in use:

(guix230 (~/devel/guix)) λ rg -cl 'lvl(Error|Info|Talkative|Chatty|Debug|Vomit)'                              
nix/nix-daemon/guix-daemon.cc:6
nix/libutil/serialise.cc:1
nix/libutil/util.hh:1
nix/nix-daemon/nix-daemon.cc:6
nix/libutil/types.hh:6
nix/libutil/util.cc:9
nix/libutil/affinity.cc:3
nix/libstore/sqlite.cc:2
nix/libstore/local-store.cc:18
nix/libstore/globals.cc:1
nix/libstore/optimise-store.cc:15
nix/libstore/pathlocks.cc:2
nix/libstore/build.cc:45
nix/libstore/gc.cc:21
(guix230 (~/devel/guix)) λ rg 'lvl(Error|Info|Talkative|Chatty|Debug|Vomit)' nix/libstore/local-store.cc  
154:        printMsg(lvlError, "waiting for the big store lock...");
829:		if (!err.empty()) printMsg(lvlError, "substitute: " + err);
1240:    printMsg(lvlInfo, format("exporting path `%1%'") % path);
1453:    printMsg(lvlError, format("reading the store..."));
1464:    printMsg(lvlInfo, "checking path existence...");
1477:        printMsg(lvlInfo, "checking hashes...");
1486:                printMsg(lvlTalkative, format("checking contents of `%1%'") % *i);
1490:                    printMsg(lvlError, format("path `%1%' was modified! "
1500:                        printMsg(lvlError, format("fixing missing hash on `%1%'") % *i);
1507:                        printMsg(lvlError, format("updating size field on `%1%' to %2%") % *i % current.second);
1520:                    printMsg(lvlError, format("error: %1%") % e.msg());
1522:                    printMsg(lvlError, format("warning: %1%") % e.msg());
1541:        printMsg(lvlError, format("path `%1%' is not in the store") % path);
1559:            printMsg(lvlError, format("path `%1%' disappeared, removing from database...") % path);
1562:            printMsg(lvlError, format("path `%1%' disappeared, but it still has valid referrers!") % path);
1567:                    printMsg(lvlError, format("warning: %1%") % e.msg());
1584:    printMsg(lvlInfo, format("checking path `%1%'...") % path);
1595:    if (!res) printMsg(lvlError, format("path `%1%' is corrupted or missing!") % path);

judging from my experience, the difference between 0..3 doesn't seem
to be that noticeable in terms of increased verbosity; 4..5
seem to be pretty verbose (whereas the difference between 4 and 5 is
also barely noticeable).

I think it'd be good to update the documention/--help output with a bit
more explanation on this (for this, it'd be probably good to know more
about when to use which level/what the implications of each level are).

[0]: https://guix.gnu.org/manual/en/html_node/Common-Build-Options.html

-- 
Kind regards,

Wilko Meyer
w@wmeyer.eu

Re: --debug LEVEL not documented in CLI

[Wilko Meyer]

"jgart" <jgart@dismail.de> writes:
> WDYT

I filed an issue[0] for this and attached a patch with a possible
suggestion on how to improve the --debug as well as --verbosity help
information on CLI as a first draft.

It, with the patch applied, now reads:

--debug=LEVEL      produce debugging output at LEVEL, value must be an integer
between 0 (more terse) and 5 (more verbose)

for debug, and:

-v, --verbosity=LEVEL  use the given verbosity LEVEL, value must be either 0 (no output),
1 (quiet), 2 (quiet + download URLs) or 3 (build log on STDERR)

for verbosity, which should probably suffice to choose an (more)
appropriate debug/verbosity level when debugging from solely reading the
help information.

I tried to keep this as short as possible, a more detailed description
of the debug levels would probably be feasible for the general guix
documentation (also I'm not quite sure how to document them, e.g. what
the exact differences between the five levels are, except that it gets
more verbose, and when to choose which; maybe someone else is more
knowledgable on this?).

[0]: https://issues.guix.gnu.org/67215

-- 
Kind regards,

Wilko Meyer
w@wmeyer.eu