From 31b098ee26ed17facb132278bb3205e80e2a760d Mon Sep 17 00:00:00 2001
From: Darcy Clarke <darcy@darcyclarke.me>
Date: Thu, 2 Dec 2021 15:36:32 -0500
Subject: [PATCH] docs: add logging docs

PR-URL: https://github.com/npm/cli/pull/4113
Credit: @darcyclarke
Close: #4113
Reviewed-by: @lukekarrys
---
 docs/content/using-npm/logging.md | 60 +++++++++++++++++++++++++++++++
 docs/nav.yml                      |  3 ++
 2 files changed, 63 insertions(+)
 create mode 100644 docs/content/using-npm/logging.md

diff --git a/docs/content/using-npm/logging.md b/docs/content/using-npm/logging.md
new file mode 100644
index 0000000000000..b7c5e89977899
--- /dev/null
+++ b/docs/content/using-npm/logging.md
@@ -0,0 +1,60 @@
+---
+title: Logging
+section: 7
+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 Levels
+
+#### `loglevel`
+
+`loglevel` is a global argument/config that can be set to determine the type of information to be displayed.
+
+The default value of `loglevel` is `"notice"` but there are several levels/types of logs available, including:
+
+- `"silent"`
+- `"error"`
+- `"warn"`
+- `"notice"`
+- `"http"`
+- `"timing"`
+- `"info"`
+- `"verbose"`
+- `"silly"`
+
+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:
+
+- `-d`: `--loglevel info`
+- `--dd`: `--loglevel verbose`
+- `--verbose`: `--loglevel verbose`
+- `--ddd`: `--loglevel silly`
+- `-q`: `--loglevel warn`
+- `--quiet`: `--loglevel warn`
+- `-s`: `--loglevel silent`
+- `--silent`: `--loglevel silent`
+
+#### `foreground-scripts`
+
+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`.
+
+### Registry Response Headers
+
+#### `npm-notice`
+
+The `npm` CLI reads from & logs any `npm-notice` headers that are returned from the configured registry. This mechanism can be used by third-party registries to provide useful information when network-dependent requests occur.
+
+This header is not cached, and will not be logged if the request is served from the cache.
+
+### See also
+
+* [config](/using-npm/config)
diff --git a/docs/nav.yml b/docs/nav.yml
index a45aefbb03d28..a82847fc39760 100644
--- a/docs/nav.yml
+++ b/docs/nav.yml
@@ -235,6 +235,9 @@
   - title: Config
     url: /using-npm/config
     description: About npm configuration
+  - title: Logging
+    url: /using-npm/logging
+    description: Why, What & How we Log
   - title: Scope
     url: /using-npm/scope
     description: Scoped packages