hpc · reidpr · Sep 15, 2023 · Apr 14, 2023 · Apr 14, 2023 · Apr 17, 2023
diff --git a/bin/ch-completion.bash b/bin/ch-completion.bash
@@ -113,7 +113,7 @@ _im
8000
age_build_opts="-b --bind --build-arg -f --file --force
 _image_common_opts="-a --arch --always-download --auth --cache
                     --cache-large --dependencies -h --help
                     --no-cache --no-lock --no-xattrs --profile
-                    --rebuild --password-many -s --storage
+                    --rebuild --password-many -q --quiet -s --storage
                     --tls-no-verify -v --verbose --version"
 
 _image_subcommands="build build-cache delete gestalt

diff --git a/bin/ch-image.py.in b/bin/ch-image.py.in
@@ -131,6 +131,10 @@ def main():
            [["--profile"],
             { "action": "store_true",
               "help": "dump profile to “./profile.{p,txt}”" }],
+           [["-q", "--quiet"],
+            { "action": "count",
+              "default": 0,
+              "help": "print less output (can be repeated)"}],
            [["-s", "--storage"],
             { "metavar": "DIR",
               "type": fs.Path,
@@ -240,6 +244,11 @@ def main():
   # python-path
    tp = sp.add_parser("python-path", "print path to python interpreter in use")
    add_opts(tp, misc.gestalt_python_path, deps_check=False, stog_init=False)
+   # logging
+   tp = sp.add_parser("logging", "print logging messages at all levels")
+   add_opts(tp, misc.gestalt_logging, deps_check=False, stog_init=False)
+   tp.add_argument("--fail", action="store_true",
+                   help="also generate a fatal error")
 
    # import
    sp = ap.add_parser("import", "copy external image into storage")

diff --git a/bin/ch-run-oci.py.in b/bin/ch-run-oci.py.in
@@ -92,6 +92,7 @@ def args_parse():
    args_.no_lock = False
    args_.password_many = False
    args_.profile = False
+   args_.quiet = False
    args_.storage = None
    args_.tls_no_verify = False
    args_.no_xattrs = False

diff --git a/doc/ch-image.rst b/doc/ch-image.rst
@@ -90,6 +90,9 @@ Common options placed before or after the sub-command:
   :code:`--no-xattrs`
     Ignore xattrs and ACLs.
 
+  :code:`--password-many`
+    Re-prompt the user every time a registry password is needed.
+
   :code:`--profile`
     Dump profile to files :code:`/tmp/chofile.p` (:code:`cProfile` dump
     format) and :code:`/tmp/chofile.txt` (text summary). You can convert the
@@ -98,13 +101,15 @@ Common options placed before or after the sub-command:
     subprocesses. Profile data should still be written on fatal errors, but
     not if the program crashes.
 
+  :code:`-q, --quiet`
+    Be quieter; can be repeated. Incompatible with :code:`-v` and suppresses
+    :code:`--debug` regardless of option order. See the :ref:`FAQ entry on
+    verbosity <faq_verbosity>` for details.
+
   :code:`--rebuild`
     Execute all instructions, even if they are build cache hits, except for
     :code:`FROM` which is retrieved from cache on hit.
 
-  :code:`--password-many`
-    Re-prompt the user every time a registry password is needed.
-
   :code:`-s`, :code:`--storage DIR`
     Set the storage directory (see below for important details).
 
@@ -113,7 +118,8 @@ Common options placed before or after the sub-command:
     unless you understand the risks.)
 
   :code:`-v`, :code:`--verbose`
-    Print extra chatter; can be repeated.
+    Print extra chatter; can be repeated. See the :ref:`FAQ entry on verbosity
+    <faq_verbosity>` for details.
 
 
 Architecture

diff --git a/doc/dev.rst b/doc/dev.rst
@@ -943,54 +943,6 @@ This form of list should be used unless some API requires something else.
     char **list = list_new(sizeof(char *), 0)
     list_append((void **)list, &bar, sizeof(char *));  // OK
 
-Logging
--------
-
-Charliecloud uses reasonably standard log levels for its stderr logging. The
-verbosity can be increased by up to three :code:`-v` command line arguments.
-Both the Python and C code use the same levels by calling logging functions
-named by level. The main error can be accompanied by a hint. The levels are:
-
-  1. **FATAL**; always printed. Some error condition that makes it impossible
-     to proceed. The program exits unsuccessfully immediately after printing
-     the error. Examples: unknown image type, Dockerfile parse error.
-
-  2. **WARNING**; always printed. Unexpected condition the user needs to know
-     about but that should not stop the program. Examples: :code:`ch-run
-     --mount` with a directory image (which does not use a mount point),
-     unsupported Dockerfile instructions that are ignored.
-
-  3. **INFO**; always printed. Chatter useful enough to always be printed.
-     Example: progress messages during image download and unpacking. Note
-     :code:`ch-run` is silent during normal operations and does not have any
-     INFO logging.
-
-  4. **VERBOSE**; printed if :code:`-v` or more. Diagnostic information useful
-     for debugging user containers, the Charliecloud installation, and
-     Charliecloud itself. Examples: :code:`ch-run --join` coordination
-     progress, :code:`ch-image` internal paths, Dockerfile parse tree.
-
-  5. **DEBUG**; printed if :code:`-vv` or more. More detailed diagnostic
-     information useful for debugging Charliecloud. Examples: data structures
-     unserialized from image registry metadata JSON, image reference parse
-     tree.
-
-  6. **TRACE**; printed if :code:`-vvv`. Grotesquely detailed diagnostic
-     information for debugging Charliecloud, to the extent it interferes with
-     normal use. A sensible person might use a `debugger
-     <https://twitter.com/wesamo__/status/1464764461831663626>`_ instead.
-     Examples: component-by-component progress of bind-mount target directory
-     analysis/creation, text of image registry JSON, every single file
-     unpacked from image layers.
-
-There is no level ERROR; anything important the user needs to know about is
-WARNING if we can safely proceed or FATAL if not.
-
-.. warning::
-
-   Do not use INFO for *output*. For example, the results of :code:`ch-image
-   list` just use plain :code:`print()` to stdout.
-
 
 OCI technical notes
 ===================

diff --git a/doc/faq.rst b/doc/faq.rst
@@ -394,8 +394,6 @@ of the default 1001:1001), i.e. :code:`--gid=5`. Then, step 4 succeeds because
 the call is mapped to :code:`chown("/dev/pts/0", 1000, 1001)` and MATLAB is
 happy.
 
-.. _faq_docker2tar-size:
-
 :code:`ch-convert` from Docker incorrect image sizes
 ----------------------------------------------------
 
@@ -1031,7 +1029,6 @@ One fix is to configure your :code:`.bashrc` or equivalent to:
          fi
     }
 
-
 How can I build images for a foreign architecture?
 --------------------------------------------------
 
@@ -1079,7 +1076,6 @@ install :code:`qemu-*-static`, is to populate a chroot for it with the `PRoot
 specifying a :code:`qemu-*-static` binary (perhaps obtained by unpacking a
 distribution package).
 
-
 How can I use tarball base images from e.g. linuxcontainers.org?
 ----------------------------------------------------------------
 
@@ -1098,6 +1094,157 @@ linuxcontainers.org uses the opposite order for “le” in the architecture nam
   $ wget https://uk.lxd.images.canonical.com/images/alpine/3.15/ppc64el/default/20220304_13:00/rootfs.tar.xz
   $ ch-image import rootfs.tar.xz ppc64le/alpine:3.17
 
+.. _faq_verbosity:
+
+How can I control Charliecloud’s quietness or verbosity?
+--------------------------------------------------------
+
+Charliecloud logs various chatter about what is going on to standard error.
+This is distinct from *output*, e.g., :code:`ch-image list` prints the list of
+images to standard output. We use reasonably standard log levels:
+
+  1. **Error**. Some error condition that makes it impossible to proceed. The
+     program exits soon after printing the error. Examples: unknown image
+     type, Dockerfile parse error. (There is an internal distinction between
+     “fatal” and “error” levels, but this isn’t really meaningful to users.)
+
+  2. **Warning**. Unexpected condition the user needs to know about but that
+     should not stop the program. Examples: :code:`ch-run --mount` with a
+     directory image (which does not use a mount point), unsupported
+     Dockerfile instructions that are ignored.
+
+  3. **Info**. Chatter useful enough to be printed by default. Example:
+     progress messages during image download and unpacking. (:code:`ch-run` is
+     silent during normal operations and does not have any “info” logging.)
+
+  4. **Verbose**. Diagnostic information useful for debugging user containers,
+     the Charliecloud installation, and Charliecloud itself. Examples:
+     :code:`ch-run --join` coordination progress, :code:`ch-image` internal
+     paths, Dockerfile parse tree.
+
+  5. **Debug**. More detailed diagnostic information useful for debugging
+     Charliecloud. Examples: data structures unserialized from image registry
+     metadata JSON, image reference parse tree.
+
+  6. **Trace**; printed if :code:`-vvv`. Grotesquely detailed diagnostic
+     information for debugging Charliecloud, to the extent it interferes with
+     normal use. A sensible person might use a `debugger
+     <https://twitter.com/wesamo__/status/1464764461831663626>`_ instead.
+     Examples: component-by-component progress of bind-mount target directory
+     analysis/creation, text of image registry JSON, every single file
+     unpacked from image layers.
+
+Charliecloud also runs sub-programs at various times, notably commands in
+:code:`RUN` instructions and :code:`git(1)` to manage the build cache. These
+programs have their own standard error and standard output streams, which
+Charliecloud either suppresses or passes through depending on verbosity level.
+
+Most Charliecloud programs accept :code:`-v` to increase logging verbosity and
+:code:`-q` to decrease it. Generally:
+
+  * Each :code:`-v` (up to three) makes Charliecloud noisier.
+
+  * :code:`-q` suppresses normal logging.
+
+  * :code:`-qq` also suppresses stdout for the program and its subprocesses,
+    and warnings from the program.
+
+  * :code:`-qqq` also suppresses subprocess stderr. (This means subprocesses
+    are completely silenced no matter what goes wrong!)
+
+This table list which logging is printed at which verbosity levels (✅
+indicates printed, ❌ suppressed).
+
+.. list-table::
+   :header-rows: 1
+
+   * -
+     - :code:`-vvv`
+     - :code:`-vv`
+     - :code:`-v`
+     - def.
+     - :code:`-q`
+     - :code:`-qq`
+     - :code:`-qqq`
+   * - trace
+     - ✅
+     - ❌
+     - ❌
+     - ❌
+     - ❌
+     - ❌
+     - ❌
+   * - debug
+     - ✅
+     - ✅
+     - ❌
+     - ❌
+     - ❌
+     - ❌
+     - ❌
+   * - verbose
+     - ✅
+     - ✅
+     - ✅
+     - ❌
+     - ❌
+     - ❌
+     - ❌
+   * - info
+     - ✅
+     - ✅
+     - ✅
+     - ✅
+     - ❌
+     - ❌
+     - ❌
+   * - program stdout
+     - ✅
+     - ✅
+     - [1]
+     - [1]
+     - [1]
+     - ❌
+     - ❌
+   * - subprocess stdout
+     - ✅
+     - ✅
+     - [1]
+     - [1]
+     - [1]
+     - ❌
+     - ❌
+   * - warning
+     - ✅
+     - ✅
+     - ✅
+     - ✅
+     - ✅
+     - ❌
+     - ❌
+   * - subprocess stderr
+     - ✅
+     - ✅
+     - ✅
+     - ✅
+     - ✅
+     - ✅
+     - ❌
+   * - error
+     - ✅
+     - ✅
+     - ✅
+     - ✅
+     - ✅
+     - ✅
+     - ✅
+
+Notes:
+
+1. Charliecloud handles subprocess stdout on case-by-case basis for these log
+   levels. For example, sometimes it’s passed through by default (e.g.,
+   :code:`RUN`) and sometimes it’s captured for internal use (e.g., many
+   :code:`git(1)` invocations).
 
 ..  LocalWords:  CAs SY Gutmann AUTH rHsFFqwwqh MrieaQ Za loc mpihello mvo du
-..  LocalWords:  VirtualSize linuxcontainers jour uk lxd rwxr xr
+..  LocalWords:  VirtualSize linuxcontainers jour uk lxd rwxr xr qq qqq
diff --git a/lib/build_cache.py b/lib/build_cache.py
@@ -1169,7 +1169,7 @@ def summary_print(self):
       print("internal files: %5d %s" % (file_ct, file_suffix))
       print("disk used:      %5d %s" % (byte_ct, byte_suffix))
       # some information directly from Git
-      if (ch.verbose >= 1):
+      if (ch.log_level >= ch.Log_Level.VERBOSE):
          out = self.git(["count-objects", "-vH"]).stdout
          print("Git statistics:")
          print(textwrap.indent(out, "  "), end="")
@@ -1185,7 +1185,7 @@ def tree_print(self):
       # Note the percent codes are interpreted by Git.
       # See: https://git-scm.com/docs/git-log#_pretty_formats
       args = ["log", "--graph", "--all", "--reflog", "--topo-order"]
-      if (ch.verbose == 0):
+      if (ch.log_level == ch.Log_Level.INFO):
          # ref names, subject (instruction), branch heads.
          fmt = "%C(auto)%d %Creset%<|(77,trunc)%s"
          args.append("--decorate-refs=refs/heads")