diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 3c289037..df6a2401 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -56,6 +56,10 @@ - [bootc image](experimental-bootc-image.md) - [--progress-fd](experimental-progress-fd.md) +- +# Troubleshooting + +- [increasing_logging_verbosity](increasing_logging_verbosity.md) # More information diff --git a/docs/src/increasing_logging_verbosity.md b/docs/src/increasing_logging_verbosity.md new file mode 100644 index 00000000..b717d015 --- /dev/null +++ b/docs/src/increasing_logging_verbosity.md @@ -0,0 +1,48 @@ +# Increasing Logging Verbosity + +When troubleshooting issues with **bootc**, it is often helpful to enable **verbose logging** to gain additional insights into its execution flow. + +## Using the `--verbose` Flag +Most **bootc** commands support the `--verbose` flag, which enables detailed logging output. The verbosity level determines how much information is logged. + +### **Verbosity Levels** +The `--verbose` flag can be used multiple times (`-v`, `-vv`, `-vvv`) to increase the verbosity of logging: + +| Verbosity Level | Flag Used | Logs Enabled | +|---------------|-----------|--------------| +| **WARN** (default) | *(no flag)* | Only warnings and errors | +| **INFO** | `-v` | Warnings, errors, and general information | +| **DEBUG** | `-vv` | Info, warnings, errors, and debug logs | +| **TRACE** | `-vvv` or more | All logs, including low-level tracing | + +### Example Usage +To switch to a new container image with verbose logging enabled: +```sh +bootc switch --apply -vv quay.io/centos-bootc/centos-bootc:stream9 +``` +This command will print **INFO, DEBUG, and WARN logs**, helping diagnose issues during the `switch` process. + +### Example Output (Verbose Mode Enabled with `-vv`) +```sh +$ bootc switch --apply -vvv quay.io/centos-bootc/centos-bootc:stream9 +TRACE Verified uid 0 with CAP_SYS_ADMIN +DEBUG Re-executing current process for _ostree_unshared +DEBUG Already in a mount namespace +DEBUG Current security context is unconfined_u:system_r:install_t:s0:c1023 +INFO We have install_t +INFO Staged: None +DEBUG Rollback queued=false +DEBUG Wrote merge commit b8761b75924d7f21e7f92abc8fd8b3c645d289fc91555 +DEBUG new_with_config: Spawned skopeo pid=1023 +TRACE new_with_config: impl_request: sending request Initialize +TRACE new_with_config: impl_request: completed request Config=ImageProxy +``` +With `-vvv`, the output includes **INFO, DEBUG, WARN, and TRACE** level messages. + +## Using the `RUST_LOG` Environment Variable +For even more detailed logging, use the `RUST_LOG` environment variable (if applicable for Rust-based components): + +```sh +RUST_LOG=debug bootc switch --apply -vvv quay.io/centos-bootc/centos-bootc:stream9 +``` +The environment variable will override the `-vvv` and enable **DEBUG** level logs for Rust-based sub-components within **bootc**. diff --git a/docs/src/man/bootc-container-lint.md b/docs/src/man/bootc-container-lint.md index 7607d365..bc49996c 100644 --- a/docs/src/man/bootc-container-lint.md +++ b/docs/src/man/bootc-container-lint.md @@ -22,6 +22,12 @@ part of a build process; it will error if any problems are detected. : Operate on the provided rootfs +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **\--fatal-warnings** : Make warnings fatal diff --git a/docs/src/man/bootc-container.md b/docs/src/man/bootc-container.md index 7b8928c4..0d883b50 100644 --- a/docs/src/man/bootc-container.md +++ b/docs/src/man/bootc-container.md @@ -13,6 +13,12 @@ Operations which can be executed as part of a container build # OPTIONS +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **-h**, **\--help** : Print help diff --git a/docs/src/man/bootc-edit.md b/docs/src/man/bootc-edit.md index 41b25748..4ece78bd 100644 --- a/docs/src/man/bootc-edit.md +++ b/docs/src/man/bootc-edit.md @@ -26,6 +26,12 @@ Only changes to the \`spec\` section are honored. : Use filename to edit system specification +**-v**, **\--verbose...** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **\--quiet** : Dont display progress diff --git a/docs/src/man/bootc-install-ensure-completion.md b/docs/src/man/bootc-install-ensure-completion.md index f532c254..d785ff1d 100644 --- a/docs/src/man/bootc-install-ensure-completion.md +++ b/docs/src/man/bootc-install-ensure-completion.md @@ -21,6 +21,12 @@ your code is using \`bootc install to-filesystem\` from the start. # OPTIONS +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **-h**, **\--help** : Print help (see a summary with -h) diff --git a/docs/src/man/bootc-install-print-configuration.md b/docs/src/man/bootc-install-print-configuration.md index bfa266c8..38070908 100644 --- a/docs/src/man/bootc-install-print-configuration.md +++ b/docs/src/man/bootc-install-print-configuration.md @@ -21,6 +21,12 @@ string-valued filesystem name suitable for passing to \`mkfs.\$type\`. # OPTIONS +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **-h**, **\--help** : Print help (see a summary with -h) diff --git a/docs/src/man/bootc-install-to-disk.md b/docs/src/man/bootc-install-to-disk.md index 865968d5..1d4c3545 100644 --- a/docs/src/man/bootc-install-to-disk.md +++ b/docs/src/man/bootc-install-to-disk.md @@ -28,6 +28,12 @@ more complex such as RAID, LVM, LUKS etc. # OPTIONS +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **\--wipe** : Automatically wipe all existing data on device diff --git a/docs/src/man/bootc-install-to-existing-root.md b/docs/src/man/bootc-install-to-existing-root.md index bd70d65b..a6e8020f 100644 --- a/docs/src/man/bootc-install-to-existing-root.md +++ b/docs/src/man/bootc-install-to-existing-root.md @@ -41,6 +41,12 @@ cleaned up if desired when rebooted into the new root. However, the running system (and all files) will remain in place until reboot +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **\--source-imgref**=*SOURCE_IMGREF* : Install the system from an explicitly given source. diff --git a/docs/src/man/bootc-install-to-filesystem.md b/docs/src/man/bootc-install-to-filesystem.md index 69732179..b0807f54 100644 --- a/docs/src/man/bootc-install-to-filesystem.md +++ b/docs/src/man/bootc-install-to-filesystem.md @@ -33,6 +33,12 @@ is currently expected to be empty by default. If not provided, the UUID of the target filesystem will be used. +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **\--boot-mount-spec**=*BOOT_MOUNT_SPEC* : Mount specification for the /boot filesystem. diff --git a/docs/src/man/bootc-install.md b/docs/src/man/bootc-install.md index bffa66ba..bdd7a240 100644 --- a/docs/src/man/bootc-install.md +++ b/docs/src/man/bootc-install.md @@ -30,6 +30,12 @@ includes other setup and metadata. # OPTIONS +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **-h**, **\--help** : Print help (see a summary with -h) diff --git a/docs/src/man/bootc-rollback.md b/docs/src/man/bootc-rollback.md index 35d5a081..21475bb4 100644 --- a/docs/src/man/bootc-rollback.md +++ b/docs/src/man/bootc-rollback.md @@ -28,6 +28,12 @@ rollback invocation. # OPTIONS +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **-h**, **\--help** : Print help (see a summary with -h) diff --git a/docs/src/man/bootc-status.md b/docs/src/man/bootc-status.md index bf95ce20..b1ad96ba 100644 --- a/docs/src/man/bootc-status.md +++ b/docs/src/man/bootc-status.md @@ -29,6 +29,12 @@ not \`null\`. # OPTIONS +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **\--format**=*FORMAT* : The output format\ diff --git a/docs/src/man/bootc-switch.md b/docs/src/man/bootc-switch.md index 7be8478b..7ee64512 100644 --- a/docs/src/man/bootc-switch.md +++ b/docs/src/man/bootc-switch.md @@ -30,6 +30,12 @@ updates via container image tags; for example, : Dont display progress +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **\--apply** : Restart or reboot into the new target image. diff --git a/docs/src/man/bootc-upgrade.md b/docs/src/man/bootc-upgrade.md index 86d4b804..17913b0c 100644 --- a/docs/src/man/bootc-upgrade.md +++ b/docs/src/man/bootc-upgrade.md @@ -31,6 +31,12 @@ the update in addition. : Dont display progress +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **\--check** : Check if an update is available without applying it. diff --git a/docs/src/man/bootc-usr-overlay.md b/docs/src/man/bootc-usr-overlay.md index f8b19e4f..a4bb5661 100644 --- a/docs/src/man/bootc-usr-overlay.md +++ b/docs/src/man/bootc-usr-overlay.md @@ -33,6 +33,12 @@ unmount\". # OPTIONS +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **-h**, **\--help** : Print help (see a summary with -h) diff --git a/docs/src/man/bootc.md b/docs/src/man/bootc.md index 87ecf930..7ed36148 100644 --- a/docs/src/man/bootc.md +++ b/docs/src/man/bootc.md @@ -20,6 +20,12 @@ pulled and \`bootc upgrade\`. # OPTIONS +**-v**, **\--verbose** + +: Increase logging verbosity + + Use `-vv`, `-vvv` to increase verbosity more. + **-h**, **\--help** : Print help (see a summary with -h)