feat: add logs-dir config to set custom logging location

This also allows logs-max to be set to 0 to disable log file writing.

Closes #4466
Closes #4206

2 files changed, 46 insertions, 6 deletions

diff --git a/docs/content/using-npm/config.md b/docs/content/using-npm/config.md
index 76e5e35e6..39870922c 100644
--- a/docs/content/using-npm/config.md
+++ b/docs/content/using-npm/config.md
@@ -1027,6 +1027,17 @@ See also the `foreground-scripts` config.
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
+#### `logs-dir`
+
+* Default: A directory named `_logs` inside the cache
+* Type: null or Path
+
+The location of npm's log directory. See [`npm logging`](/using-npm/logging)
+for more information.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
 #### `logs-max`
 
 * Default: 10
@@ -1034,6 +1045,8 @@ See also the `foreground-scripts` config.
 
 The maximum number of log files to store.
 
+If set to 0, no log files will be written for the current run.
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
@@ -1628,9 +1641,9 @@ particular, use care when overriding this setting for public packages.
 * Default: false
 * Type: Boolean
 
-If true, writes an `npm-debug` log to `_logs` and timing information to
-`_timing.json`, both in your cache, even if the command completes
-successfully. `_timing.json` is a newline delimited list of JSON objects.
+If true, writes a debug log to `logs-dir` and timing information to
+`_timing.json` in the cache, even if the command completes successfully.
+`_timing.json` is a newline delimited list of JSON objects.
 
 You can quickly view it with this [json](https://npm.im/json) command line:
 `npm exec -- json -g < ~/.npm/_timing.json`.
diff --git a/docs/content/using-npm/logging.md b/docs/content/using-npm/logging.md
index b7c5e8997..eb83b167e 100644
--- a/docs/content/using-npm/logging.md
+++ b/docs/content/using-npm/logging.md
@@ -1,13 +1,24 @@
 ---
 title: Logging
 section: 7
-description: Why, What & How we Log
+description: Why, What & How We Log
 ---
 
 ### Description
 
 The `npm` CLI has various mechanisms for showing different levels of information back to end-users for certain commands, configurations & environments.
 
+### Setting Log File Location
+
+All logs are written to a debug log, with the path to that file printed if the execution of a command fails.
+
+The default location of the logs directory is a directory named `_logs` inside the npm cache. This can be changed
+with the `logs-dir` config option.
+
+Log files will be removed from the `logs-dir` when the number of log files exceeds `logs-max`, with the oldest logs being deleted first.
+
+To turn off logs completely set `--logs-max=0`.
+
 ### Setting Log Levels
 
 #### `loglevel`
@@ -28,8 +39,6 @@ The default value of `loglevel` is `"notice"` but there are several levels/types
 
 All logs pertaining to a level proceeding the current setting will be shown.
 
-All logs are written to a debug log, with the path to that file printed if the execution of a command fails.
-
 ##### Aliases
 
 The log levels listed above have various corresponding aliases, including:
@@ -47,6 +56,15 @@ The log levels listed above have various corresponding aliases, including:
 
 The `npm` CLI began hiding the output of lifecycle scripts for `npm install` as of `v7`. Notably, this means you will not see logs/output from packages that may be using "install scripts" to display information back to you or from your own project's scripts defined in `package.json`. If you'd like to change this behavior & log this output you can set `foreground-scripts` to `true`.
 
+### Timing Information
+
+The `--timing` config can be set which does two things:
+
+1. Always shows the full path to the debug log regardless of command exit status
+1. Write timing information to a timing file in the cache or `logs-dir`
+
+This file is a newline delimited list of JSON  objects that can be inspected to see timing data for each task in a `npm` CLI run.
+
 ### Registry Response Headers
 
 #### `npm-notice`
@@ -55,6 +73,15 @@ The `npm` CLI reads from & logs any `npm-notice` headers that are returned from
 
 This header is not cached, and will not be logged if the request is served from the cache.
 
+### Logs and Sensitive Information
+
+The `npm` CLI makes a best effort to redact the following from terminal output and log files:
+
+- Passwords inside basic auth URLs
+- npm tokens
+
+However, this behavior should not be relied on to keep all possible sensitive information redacted. If you are concerned about secrets in your log file or terminal output, you can use `--loglevel=silent` and `--logs-max=0` to ensure no logs are written to your terminal or filesystem.
+
 ### See also
 
 * [config](/using-npm/config)