-v, --verbosity=LEVEL use the given verbosity LEVEL

-v, --verbosity=LEVEL use the given verbosity LEVEL

[jgart]

Hi Guixers,

Where should the user of the Guix command-line interface be expected to read about the verbosity LEVEL argument that they can pass to `--verbosity` and that is also valid?

all best,

jgart

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[Maxim Cournoyer]

Hi jgart,

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

> Hi Guixers,
>
> Where should the user of the Guix command-line interface be expected
> to read about the verbosity LEVEL argument that they can pass to
> `--verbosity` and that is also valid?

See info '(guix) Invoking guix build':

--8<---------------cut here---------------start------------->8---
‘-v LEVEL’
‘--verbosity=LEVEL’
     Use the given verbosity LEVEL, an integer.  Choosing 0 means that
     no output is produced, 1 is for quiet output; 2 is similar to 1 but
     it additionally displays download URLs; 3 shows all the build log
     output on standard error.
--8<---------------cut here---------------end--------------->8---

-- 
Thanks,
Maxim

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[Simon Tournier]

Hi,

On Tue, 26 Sep 2023 at 12:19, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:

>> Where should the user of the Guix command-line interface be expected
>> to read about the verbosity LEVEL argument that they can pass to
>> `--verbosity` and that is also valid?

To answer a question elsewhere in this threads, I think these levels
come from Nix and daemon side.

> See info '(guix) Invoking guix build':
>
> --8<---------------cut here---------------start------------->8---
> ‘-v LEVEL’
> ‘--verbosity=LEVEL’
>      Use the given verbosity LEVEL, an integer.  Choosing 0 means that
>      no output is produced, 1 is for quiet output; 2 is similar to 1 but
>      it additionally displays download URLs; 3 shows all the build log
>      output on standard error.
> --8<---------------cut here---------------end--------------->8---

Maybe, we could add an option as ’--list-verbosity’ which would display
that information.

Well, the main issue, IMHO, is that the option ’--verbosity’ is not
shared across various command-line scripts, but implemented script per
script, IIRC.

Cheers,
simon

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[Maxim Cournoyer]

Hi,

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi,
>
> On Tue, 26 Sep 2023 at 12:19, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:
>
>>> Where should the user of the Guix command-line interface be expected
>>> to read about the verbosity LEVEL argument that they can pass to
>>> `--verbosity` and that is also valid?
>
> To answer a question elsewhere in this threads, I think these levels
> come from Nix and daemon side.
>
>> See info '(guix) Invoking guix build':
>>
>> --8<---------------cut here---------------start------------->8---
>> ‘-v LEVEL’
>> ‘--verbosity=LEVEL’
>>      Use the given verbosity LEVEL, an integer.  Choosing 0 means that
>>      no output is produced, 1 is for quiet output; 2 is similar to 1 but
>>      it additionally displays download URLs; 3 shows all the build log
>>      output on standard error.
>> --8<---------------cut here---------------end--------------->8---
>
> Maybe, we could add an option as ’--list-verbosity’ which would display
> that information.
>
> Well, the main issue, IMHO, is that the option ’--verbosity’ is not
> shared across various command-line scripts, but implemented script per
> script, IIRC.

Oh, is it?  That's not great.  I've never used it, but Guix already
soft-depends on guile-lib, and guile-lib provides a logging library.
Perhaps if we used that we would benefit from some standardized and
global way to perform logging across at least the host-side code?  And
that'd help more straightforwardly reason and explain the levels?

I have experience with logging from Python and would like to have a
similar tool available in Guix.  Instead of adding pk all over the place
when debugging enabling the debug level (assuming we've added a few well
placed debug level logging directives in the code) would help trace
execution and pinpoint where things go wrong easily.

-- 
Thanks,
Maxim

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[Simon Tournier]

Hi,

On Wed, 11 Oct 2023 at 11:11, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:

>> To answer a question elsewhere in this threads, I think these levels
>> come from Nix and daemon side.
>>
>>> See info '(guix) Invoking guix build':
>>>
>>> --8<---------------cut here---------------start------------->8---
>>> ‘-v LEVEL’
>>> ‘--verbosity=LEVEL’
>>>      Use the given verbosity LEVEL, an integer.  Choosing 0 means that
>>>      no output is produced, 1 is for quiet output; 2 is similar to 1 but
>>>      it additionally displays download URLs; 3 shows all the build log
>>>      output on standard error.
>>> --8<---------------cut here---------------end--------------->8---
>>
>> Maybe, we could add an option as ’--list-verbosity’ which would display
>> that information.
>>
>> Well, the main issue, IMHO, is that the option ’--verbosity’ is not
>> shared across various command-line scripts, but implemented script per
>> script, IIRC.
>
> Oh, is it?   That's not great.

Well, maybe the first step would to refactor and move to
%standard-build-options.  Or something like that.

guix/scripts/build.scm reads:

--8<---------------cut here---------------start------------->8---
(define (show-help)
  (display (G_ "Usage: guix build [OPTION]... PACKAGE-OR-DERIVATION...
Build the given PACKAGE-OR-DERIVATION and return their output paths.\n"))

[...]

  (display (G_ "
  -v, --verbosity=LEVEL  use the given verbosity LEVEL"))

(define %options
  ;; Specifications of the command-line options.
[...]
         (option '(#\v "verbosity") #t #f
                 (lambda (opt name arg result)
                   (let ((level (string->number* arg)))
                     (alist-cons 'verbosity level
                                 (alist-delete 'verbosity result)))))
--8<---------------cut here---------------end--------------->8---

And guix/scripts/package.scm reads:

--8<---------------cut here---------------start------------->8---
(define (show-help)
  (display (G_ "Usage: guix package [OPTION]...
Install, remove, or upgrade packages in a single transaction.\n"))

[...]

  (display (G_ "
  -v, --verbosity=LEVEL  use the given verbosity LEVEL"))
  (newline)

(define %options
  ;; Specification of the command-line options.
[...]
         (option '(#\v "verbosity") #t #f
                 (lambda (opt name arg result arg-handler)
                   (let ((level (string->number* arg)))
                     (values (alist-cons 'verbosity level
                                         (alist-delete 'verbosity result))
                             #f))))
--8<---------------cut here---------------end--------------->8---

For some instances. :-)


> Oh, is it?  That's not great.  I've never used it, but Guix already
> soft-depends on guile-lib, and guile-lib provides a logging library.
> Perhaps if we used that we would benefit from some standardized and
> global way to perform logging across at least the host-side code?  And
> that'd help more straightforwardly reason and explain the levels?

Well, I think the ’verbosity’ is something passed to some C++
guix-daemon side and not used on Guile side.


Cheers,
simon

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[jgart]

Hi Maxim,

That's awesome documentation! Thanks for doing that. Approved.

Do you want to merge this?

yours truly,

jgart

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[Maxim Cournoyer]

Hi,

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

> Hi Maxim,
>
> That's awesome documentation! Thanks for doing that. Approved.

> Do you want to merge this?

There seems to be a misunderstanding; it's already documented.  If you
run the info command I shared you'll see I copied the text from there.

-- 
Thanks,
Maxim

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[jgart]

Hi Maxim,

But it's not below in the --help of `guix build` command.

It just says

> use the given verbosity LEVEL

```
[jgart@fedora_user ~]$ guix build --help
...
  -d, --derivations      return the derivation paths of the given packages
      --check            rebuild items to check for non-determinism issues
      --repair           repair the specified items
  -r, --root=FILE        make FILE a symlink to the result, and register it
                         as a garbage collector root
  -v, --verbosity=LEVEL  use the given verbosity LEVEL
  -q, --quiet            do not show the build log
...
```

But what if the user doesn't know what the verbosity LEVELs are?

And what if the user also doesn't know that they are documented in the info manual?

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[jgart]

> 1 is for quiet output; 2 is similar to 1 but it additionally displays download URLs; 

> it additionally displays

I think it is confusing to use the word "additionally" here as there is nothing that we know about the quiet output for the description that let's us then conceptualize what will be added to it.

In other words, level 1 should be described with more detail than "1 is for quiet output". 

What should we expect to see in the content of verbosity level 1 in general.

I would have to find the time to conduct some empirical usages with the --verbosity flag to answer that question succinctly and in the general across guix subcommands beyond just describing it as "quiet output".

WDYT, nitpick? maybe/maybenot

jgart

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[Maxim Cournoyer]

Hi,

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

>> 1 is for quiet output; 2 is similar to 1 but it additionally displays download URLs; 
>
>> it additionally displays
>
> I think it is confusing to use the word "additionally" here as there is nothing that we know about the quiet output for the description that let's us then conceptualize what will be added to it.
>
> In other words, level 1 should be described with more detail than "1 is for quiet output". 
>
> What should we expect to see in the content of verbosity level 1 in general.
>
> I would have to find the time to conduct some empirical usages with the --verbosity flag to answer that question succinctly and in the general across guix subcommands beyond just describing it as "quiet output".
>
> WDYT, nitpick? maybe/maybenot

I agree it can be improved, but I'd also have to read the code to know
what each level exactly do.

I think it could make things simpler to use nouns for the level, as they
could mean something without having to be explained to verbosely, e.g.:

debug (very verbose)
info (include some extra messages)
warning (warnings and errors -- the default level)
error (errors only)

Basically like what the levels of the 'logging' Python library are
expected to do, which the logging library included with guile-lib is
inspired by.

-- 
Thanks,
Maxim

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[jgart]

Hi Maxim,

Thanks for the reply and info.

I don't mind doing the work to find out exactly what is being logged with deep understanding of Guile/Guix's logging mechanism. A bird's eye view while still understanding the low level and commenting on it.

It will require some time to do that research and write a good explanation.

I'm in no rush so I will try unless someone else gets to it first.

Might be good to talk with the person who wrote that logging to discuss the information and concepts involved in the context of guile and guix.

all best,

jgart

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[Maxim Cournoyer]

Hello,

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

> Hi Maxim,
>
> Thanks for the reply and info.
>
> I don't mind doing the work to find out exactly what is being logged
> with deep understanding of Guile/Guix's logging mechanism. A bird's
> eye view while still understanding the low level and commenting on it.
>
> It will require some time to do that research and write a good explanation.
>
> I'm in no rush so I will try unless someone else gets to it first.
>
> Might be good to talk with the person who wrote that logging to
> discuss the information and concepts involved in the context of guile
> and guix.

There might have been some discussion on guix-devel (you can search
through the archives); otherwise I believe it was implemented by
Ludovic.

-- 
Thanks,
Maxim

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[jgart]

Some prescriptive logging documentation for inspiration:

https://textual.textualize.io/guide/devtools/#increasing-verbosity

Re: -v, --verbosity=LEVEL use the given verbosity LEVEL

[Simon Tournier]

Hi,

On Sat, 23 Sep 2023 at 18:08, "jgart" <jgart@dismail.de> wrote:

> Where should the user of the Guix command-line interface be expected
> to read about the verbosity LEVEL argument that they can pass to
> `--verbosity` and that is also valid? 

Well, for helping me in muscling my memory, I have this patch applied to
some Guix I run.

--8<---------------cut here---------------start------------->8---
diff --git a/guix/scripts/build.scm b/guix/scripts/build.scm
index 72a24f91ac..35cb888c3b 100644
--- a/guix/scripts/build.scm
+++ b/guix/scripts/build.scm
@@ -452,8 +452,10 @@ (define (show-help)
   -r, --root=FILE        make FILE a symlink to the result, and register it
                          as a garbage collector root"))
   (display (G_ "
-  -v, --verbosity=LEVEL  use the given verbosity LEVEL"))
-  (display (G_ "
+  -v, --verbosity=LEVEL  use the given verbosity LEVEL, range 0-3
+                         0 = no output, 1 = quiet, 2 = 1 + download URLs,
+                         3 = all on standard error"))
+    (display (G_ "
   -q, --quiet            do not show the build log"))
   (display (G_ "
       --log-file         return the log file names for the given derivations"))
--8<---------------cut here---------------end--------------->8---

Cheers,
simon