From cc6c09431d7fe2db8ac1dc7a707f2dab7a7a1f83 Mon Sep 17 00:00:00 2001 From: Luke Karrys Date: Fri, 18 Mar 2022 21:31:37 -0700 Subject: 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 --- docs/content/using-npm/config.md | 19 ++++++++++++++++--- docs/content/using-npm/logging.md | 33 ++++++++++++++++++++++++++++++--- 2 files changed, 46 insertions(+), 6 deletions(-) (limited to 'docs') 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. +#### `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. + + + + #### `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. + @@ -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) -- cgit v1.2.3