Merge pull request #1693 from quarto-dev/add-log-documentation

Add more docs on log configuration

Author: cderv

docs/advanced/environment-vars.qmd

@@ -38,6 +38,14 @@ You can read about other ways to set environment variables in Quarto Projects in
 +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | `QUARTO_CHROMIUM_HEADLESS_MODE` | Used for adaption of the `--headless` mode used with `QUARTO_CHROMIUM` binary. Set to `"none"` for `--headless` , or to `"old"` or `"new"` to pass as argument, e.g. `--headless=<QUARTO_CHROMIUM_HEADLESS_MODE>` . Quarto 1.6 sets `"old"` as default, which works from Chrome 112 to 131. Starting Quarto 1.7.13, `"none"` is the default as [Chrome 132 removed old headless mode](https://developer.chrome.com/blog/removing-headless-old-from-chrome). |
 +---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| `QUARTO_LOG`                    | Those variables controls the logging behavior:                                                                                                                                                                                                                                                                                                                                                                                                              |
+|                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `QUARTO_LOG_LEVEL`              | -   `QUARTO_LOG` is the same as using `--log` at command line. It is used to set the path to the log file                                                                                                                                                                                                                                                                                                                                                   |
+|                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `QUARTO_LOG_FORMAT`             | -   `QUARTO_LOG_LEVEL` is the same as using `--log-level` at command line. It is used to set the max level that will be log. Possible values are `DEBUG`, `INFO`(default), `WARNING`, and `ERROR`.                                                                                                                                                                                                                                                          |
+|                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+|                                 | -   `QUARTO_LOG_FORMAT` is the same as using `--log-format` at command line. It is used to set the format for the log. Possible values are `plain` (default) and `json-stream`.                                                                                                                                                                                                                                                                             |
++---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 ## Variables Quarto sets
 
@@ -78,4 +86,4 @@ ENV["QUARTO_DOCUMENT_PATH"]
 | `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` | Values for `fig-width` and `fig-height` as set in the document metadata                                                                                                                         |
 +--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | `QUARTO_RUN_NO_NETWORK`                    | When `true`, Quarto project scripts written in TypeScript won't be allowed to use the network to download sources. In this setting, those scripts will not have access to the standard library. |
-+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
++--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

docs/troubleshooting/index.qmd

@@ -105,6 +105,10 @@ export QUARTO_LOG_LEVEL=DEBUG
 
 :::
 
+`--log-level debug` can also be passed at command line e.g. `quarto render index.qmd --log-level debug`
+
+If you prefer to have the log be written to file, you can set `QUARTO_LOG` in your environment, or `--log` at command line. 
+
 ### Inspect log files {#log-files}
 
 Quarto creates log files that can help you diagnose problems. These are stored in different locations depending on your operating system: