Improve the diagnostic experience by deprecating the flag "--verbose" and standardize the debug logs

[FeynmanZhou]

Is your feature request related to a problem?

Known problems

• The user is confused about when to use --verbose and --debug.
• Poor readability of debug logs. No separator lines between request and response information. Users need to add separator lines manually for readability.
• Each log entry does not provide a precise timestamp to trace the sequence of events accurately. notation SHOULD use the Nanoseconds precision to print the timestamp in the first field of each line.
• The user environment information is not printed out. This causes a higher cost to reproduce the issues for notation developers locally.

A sample debug log of notation sign:

DEBU[2025-03-31T16:37:29-07:00] Request #0
> Request: "HEAD" "https://ghcr.io/v2/chocolate-labs/oras/manifests/v1"
> Request headers:
   "Accept": "application/vnd.docker.distribution.manifest.v2+json, application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json, application/vnd.oci.artifact.manifest.v1+json"
   "User-Agent": "notation/2.0.0-alpha.1" 
DEBU[2025-03-31T16:37:29-07:00] Response #0
< Response status: "401 Unauthorized"
< Response headers:
   "X-Github-Request-Id": "5BAF:103779:3C9A782:3E5A8CD:67EB2739"
   "Content-Type": "application/json"
   "Www-Authenticate": "Bearer realm=\"https://ghcr.io/token\",service=\"ghcr.io\",scope=\"repository:chocolate-labs/oras:pull\""
   "Date": "Mon, 31 Mar 2025 23:37:29 GMT"
   "Content-Length": "73" 
DEBU[2025-03-31T16:37:29-07:00] started executing credential helper program docker-credential-desktop with action get 
DEBU[2025-03-31T16:37:29-07:00] successfully finished executing credential helper program docker-credential-desktop with action get 
DEBU[2025-03-31T16:37:29-07:00] Request #1
> Request: "GET" "https://ghcr.io/token?scope=repository%3Achocolate-labs%2Foras%3Apull&service=ghcr.io"
> Request headers:
   "Authorization": "*****"
   "User-Agent": "notation/2.0.0-alpha.1" 
DEBU[2025-03-31T16:37:29-07:00] Response #1
< Response status: "200 OK"
< Response headers:
   "Content-Type": "application/json"
   "Docker-Distribution-Api-Version": "registry/2.0"
   "Date": "Mon, 31 Mar 2025 23:37:29 GMT"
   "Content-Length": "137"
   "X-Github-Request-Id": "5BAF:103779:3C9A7BD:3E5A906:67EB2739" 
DEBU[2025-03-31T16:37:29-07:00] Request #2
> Request: "HEAD" "https://ghcr.io/v2/chocolate-labs/oras/manifests/v1"
> Request headers:
   "Accept": "application/vnd.docker.distribution.manifest.v2+json, application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json, application/vnd.oci.artifact.manifest.v1+json"
   "Authorization": "*****"
   "User-Agent": "notation/2.0.0-alpha.1" 
DEBU[2025-03-31T16:37:29-07:00] Response #2
< Response status: "403 Forbidden"
< Response headers:
   "Content-Length": "86"
   "X-Github-Request-Id": "5BAF:103779:3C9A7DA:3E5A92A:67EB2739"
   "Content-Type": "application/json"
   "Docker-Distribution-Api-Version": "registry/2.0"
   "Date": "Mon, 31 Mar 2025 23:37:29 GMT" 
Error: failed to get manifest descriptor: HEAD "https://ghcr.io/v2/chocolate-labs/oras/manifests/v1": response status code 403: Forbidden
feynmanzhou@feynmanzhous-MacBook-Pro Downloads % notation sign ghcr.io/chocolate-labs/oras:v1 --key local-test --signature-format cose -v
Error: failed to get manifest descriptor: HEAD "https://ghcr.io/v2/chocolate-labs/oras/manifests/v1": response status code 403: Forbidden
feynmanzhou@feynmanzhous-MacBook-Pro Downloads % notation inspect ghcr.io/chocolate-labs/oras:v1
Error: failed to get manifest descriptor: HEAD "https://ghcr.io/v2/chocolate-labs/oras/manifests/v1": response status code 403: Forbidden

What solution do you propose?

Improve the diagnostic experience by deprecating the flag "--verbose" and standardize the debug logs.

Currently, notation offers two global options, --verbose and --debug, which enable users to generate verbose output and logs respectively. These features facilitate both users and developers in inspecting notation's performance, interactions with external services and internal systems, and in diagnosing issues by providing a clear picture of the tool's operations.

Given the diverse roles and scenarios in which notation CLI is utilized, we have received feedback from users and developers to improve the diagnostic experience. Enhancing logging experience can significantly benefit notation users and developers by making diagnostics clearer and more unambiguous.

I would propose the following solutions to Notation diagnostic experience:

• Deprecate the --verbose flag but keep --debug flag to avoid ambiguity and duplicated INFO level logs in two outputs. It is reasonable to continue using --debug to enable logs with different levels as it is in notation.
• Add two empty lines as the separator between each request and response for readability.
• Add timestamp of each request and response to the beginning of each request and response. Use the Nanoseconds precision to print the timestamp
• Considering notation is not a daemon service so parsing debug logs to a logging system is not a common scenario. The target users of the debug logs are normal users and notation developers. Thereby, the debug logs in TTY mode and non-TTY (--no-tty) should be consistent, except for the color. Specifically, debug logs SHOULD be colored-code in a TTY mode for better readability on terminal but keeping plain text without color in a non-TTY mode.
• Show running environment details of notation such as OS/Arch in the output of notation version. It would be helpful to help the notation developers locate and reproduce the issue easier.

What alternatives have you considered?

N/A

Any additional context?

No response

[FeynmanZhou]

@JeyJeyGao I've listed my suggested enhancements in this issue. In addiontion to known enhancements above, have you identified others? I will raise a PR for the guidance of the debug logs.

Maybe you could convert each one into a sub-issue when you raise PR for each of them.