docs: Improve ORAS diagnose experience #1483
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: Feynman Zhou <[email protected]>
FeynmanZhou
requested review from
sajayantony,
shizhMSFT,
SteveLasker,
qweeah and
TerryHowe
as code owners
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1483 +/- ##
==========================================
+ Coverage 85.54% 86.02% +0.47%
==========================================
Files 113 118 +5
Lines 3936 4228 +292
==========================================
+ Hits 3367 3637 +270
- Misses 342 352 +10
- Partials 227 239 +12 ☔ View full report in Codecov by Sentry. |
Signed-off-by: Feynman Zhou <[email protected]>
Signed-off-by: Feynman Zhou <[email protected]>
toddysm
reviewed
Aug 21, 2024
There was a problem hiding this comment.
IMHO, if a user decides to get verbose output, he or she will be prepared to receive a lot of information in the output (including very technical information - for example, curl gives details about the encryption algorithm). I am still not convinced that we need to complicate the interface to suppress some of the output.
Wwwsylvia
reviewed
Aug 21, 2024
Wwwsylvia
reviewed
Aug 21, 2024
Wwwsylvia
reviewed
Aug 21, 2024
Wwwsylvia
reviewed
Aug 21, 2024
TerryHowe
reviewed
Aug 21, 2024
1 task
sajayantony
reviewed
Aug 22, 2024
sajayantony
reviewed
Aug 22, 2024
sajayantony
reviewed
Aug 22, 2024
yizha1
reviewed
Aug 27, 2024
shizhMSFT
reviewed
Aug 28, 2024
shizhMSFT
reviewed
Aug 28, 2024
Wwwsylvia
reviewed
Sep 3, 2024
Signed-off-by: Feynman Zhou <[email protected]>
Signed-off-by: Feynman Zhou <[email protected]>
sajayantony
reviewed
Sep 4, 2024
Signed-off-by: Feynman Zhou <[email protected]>
Signed-off-by: Feynman Zhou <[email protected]>
Signed-off-by: Feynman Zhou <[email protected]>
Signed-off-by: Feynman Zhou <[email protected]>
FeynmanZhou
requested review from
TerryHowe,
toddysm,
sajayantony,
Wwwsylvia,
shizhMSFT and
yizha1
shizhMSFT
reviewed
Sep 14, 2024
shizhMSFT
reviewed
Sep 14, 2024
Wwwsylvia
reviewed
Sep 14, 2024
Wwwsylvia
reviewed
Sep 14, 2024
Signed-off-by: Feynman Zhou <[email protected]>
Signed-off-by: Feynman Zhou <[email protected]>
Wwwsylvia
reviewed
Sep 18, 2024
4 tasks
yizha1
reviewed
Sep 19, 2024
shizhMSFT
requested changes
Sep 20, 2024
| - Introduce a new flag `--detail` to replace the existing global flag `--verbose` of commands like `pull`, `push`, `attach`, and `discover` for detailed output. | ||
| - Add separator lines between each request and response for readability. | ||
| - Add timestamp of each request and response to the beginning of each request and response. | ||
| - Add the response body including [error code](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#error-codes) and the metadata of processed OCI object (e.g. image manifest) to the debug logs |
There was a problem hiding this comment.
What does it mean? Is it applicable to OCI image layout?
There was a problem hiding this comment.
The error code is not included in the response body in ORAS debug logs now. We need to add it to make it analyzable.
This is not applicable to OCI image layout but only registry.
There was a problem hiding this comment.
Error code is in the response body as we do extract error code from the JSON response body.
Signed-off-by: Feynman Zhou <[email protected]>
TerryHowe
reviewed
Oct 1, 2024
Signed-off-by: Feynman Zhou <[email protected]>
Signed-off-by: Feynman Zhou <[email protected]>
shizhMSFT
reviewed
Oct 10, 2024
| - Introduce a new flag `--detail` to replace the existing global flag `--verbose` of commands like `pull`, `push`, `attach`, and `discover` for detailed output. | ||
| - Add separator lines between each request and response for readability. | ||
| - Add timestamp of each request and response to the beginning of each request and response. | ||
| - Add the response body including [error code](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#error-codes) and the metadata of processed OCI object (e.g. image manifest) to the debug logs |
There was a problem hiding this comment.
Error code is in the response body as we do extract error code from the JSON response body.
| "Www-Authenticate": "Bearer realm=\"https://ghcr.io/token\",service=\"ghcr.io\",scope=\"repository:oras-project/oras:pull\"" | ||
| "Date": "Fri, 02 Aug 2024 23:56:03 GMT" | ||
| < Response body: | ||
| { |
| - Make the verbose output of command `discover` as a formatted output, controlled by `--format tree-full`. | ||
| - Add an empty line 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. | ||
| - Add the response body including [error code](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#error-codes) and the metadata of processed OCI object (e.g. image manifest) to the debug logs. |
There was a problem hiding this comment.
We should never print out binary response body. We need a list of printable content types such as application/json.
Wwwsylvia
reviewed
Oct 10, 2024
|
|
||
| Currently, the output of ORAS `--verbose` flag only exists in oras `pull/push/attach/discover` commands, which prints out detailed status output and metadata output. Since ORAS v1.2.0, progress bar is enabled in `pull/push/attach` by default, thus the ORAS output is already verbose on a terminal. | ||
|
|
||
| It is intended for end-users who want to observe the detailed file operation when using ORAS. It gives users a comprehensive view of what the tool is doing at every step and how long does it take when push or pull a file. |
Comment on lines
+104
to
+134
| **Current debug log** | ||
|
|
||
| ``` | ||
| [DEBU0000] Request #0 | ||
| > Request URL: "https://ghcr.io/v2/oras-project/oras/manifests/v1.2.0" | ||
| > Request method: "GET" | ||
| > Request headers: | ||
| "User-Agent": "oras/1.2.0+Homebrew" | ||
| "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" | ||
| DEBU[0001] Response #0 | ||
| < Response Status: "401 Unauthorized" | ||
| < Response headers: | ||
| "Content-Length": "73" | ||
| "X-Github-Request-Id": "9FC6:30019C:17C06:1C462:66AD0463" | ||
| "Content-Type": "application/json" | ||
| "Www-Authenticate": "Bearer realm=\"https://ghcr.io/token\",service=\"ghcr.io\",scope=\"repository:oras-project/oras:pull\"" | ||
| "Date": "Fri, 02 Aug 2024 16:08:04 GMT" | ||
| DEBU[0001] Request #1 | ||
| > Request URL: "https://ghcr.io/token?scope=repository%3Aoras-project%2Foras%3Apull&service=ghcr.io" | ||
| > Request method: "GET" | ||
| > Request headers: | ||
| "User-Agent": "oras/1.2.0+Homebrew" | ||
| DEBU[0002] Response #1 | ||
| < Response Status: "200 OK" | ||
| < Response headers: | ||
| "Content-Type": "application/json" | ||
| "Docker-Distribution-Api-Version": "registry/2.0" | ||
| "Date": "Fri, 02 Aug 2024 16:08:05 GMT" | ||
| "Content-Length": "69" | ||
| "X-Github-Request-Id": "9FC6:30019C:17C0D:1C46C:66AD0464" | ||
| ``` |
There was a problem hiding this comment.
Actually, debug logs are showed differently in TTY and non-TTY. For example,
in TTY:
DEBU[0000] Request #0
> Request URL: "http://localhost:5000/v2/240923test1/manifests/v1"
> Request method: "HEAD"
...
in non-TTY:
time=2024-10-10T18:45:10+08:00 level=debug msg=Request #0
> Request URL: "http://localhost:5000/v2/240923test1/manifests/v1"
> Request method: "HEAD"
There was a problem hiding this comment.
Should non-tty use the json formatter? Looks like it has everything else in there for structured logging.
Signed-off-by: Feynman Zhou <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What this PR does / why we need it:
This proposal document aims to:
--verboseand--debugoptions.Which issue(s) this PR fixes (optional, in
fixes #<issue number>(, fixes #<issue_number>, ...)format, will close the issue(s) when PR gets merged):Fixes #1091