Add verbose http logging to blob fetch

[sajayantony]

What is the version of your ORAS CLI

1.0.0

What would you like to be added?

Currently there is no output in oras blob fetch that would enable users to debug or learn about the http request path that is being taken.

❯ oras blob fetch --verbose --output ~/temp/scratch  docker.io/library/hello-world@sha256:2db29710123e3e53a794f2694094b9b4338aa9ee5c40b930cb8063a1be392c54

The goal was to see the response status code and how the client might follow the blob request to a CDN endpoint.

Why is this needed for ORAS?

ORAS as a tool is expected to use to inspect/query the registry and having this output helps validate if a server is behaving correctly.

Are you willing to submit PRs to contribute to this feature?

• Yes, I am willing to implement it.

[qweeah]

supported via oras blob fetch --debug/-d

[qweeah]

Reopening this since --debug does not clearly imply that its output shows the request path taken by the to-be-executed command. Also it's worth discussion that what kind of logs should we add to --verbose

[sajayantony]

Both me and @toddysm were confused as to why --verbose didn't have any output. I understand that --debug has the output but the main point here is layered exposure of detailed logging. Possibly even differently formatted logs. e.g. raw json response could be included in --debug. Also, I think verbose logging might even benefit if its human readable.

Typically, I consider when --debug is enabled, the command will output much more detailed and technical information about what it is doing, including internal state, API calls, and other low-level details. This can be useful for developers or advanced users who need to debug or diagnose issues with a command or operation and possibly include timing information.

[toddysm]

curl doesn't have --debug and --verbose. The only option is --verbose and it is very helpful to track the HTTP request/response. As @sajayantony mentions above, having the --verbose option with no changes in output is weird. Also, there is no clarity what is the purpose of it. We have two scenarios here:

1. Getting troubleshooting information for the API exchange or the steps the tool performs. In this case we can use --debug as until now or --verbose as curl does (as well as other tools).
2. Adding additional details from command outputs that can be beneficial for users. This is --detailed output though and not --verbose IMHO. Example is:
   • oras discover ... -o tree shows only the tree with the digests
   • oras discover ... -o tree --detailed shows also annotations
     Designing on the fly above but trying to convey what the experience can be.

[qweeah]

Trying to understand the proposed change:

• move http-level request/response logs from --debug to --verbose
• add a new flag --detailed to show current verbose output (update: this is not needed)
• reserve --debug for more low-level and technical information

@toddysm @sajayantony Can you help confirm?

[toddysm]

I don't think we need both --debug and --verbose. --verbose should be enough for the purposes and it is consistent with other tools. We should not introduce --debug in the future because it is confusing.

--detailed was just an example trying to illustrate a scenario where we can suppress some output that is helpful for the user. I don't think we need to add this right now because it is not properly designed.

Hope this helps.

[qweeah]

Below is the output of oras cp with and without --verbose

# 1. current verbose output
$ oras cp docker.io/library/hello-world:latest --platform linux/amd64 --to-oci-layout . --verbose
Copying 2db29710123e application/vnd.docker.image.rootfs.diff.tar.gzip
Copying feb5d9fea6a5 application/vnd.docker.container.image.v1+json
Copied  2db29710123e application/vnd.docker.image.rootfs.diff.tar.gzip
Copied  feb5d9fea6a5 application/vnd.docker.container.image.v1+json
Copying f54a58bc1aac application/vnd.docker.distribution.manifest.v2+json
Copied  f54a58bc1aac application/vnd.docker.distribution.manifest.v2+json
Copied [registry] docker.io/library/hello-world:latest => [oci-layout] .
Digest: sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4

# 2. current non-verbose output
$ oras cp docker.io/library/hello-world:latest --platform linux/amd64 --to-oci-layout .
Copied [registry] docker.io/library/hello-world:latest => [oci-layout] .
Digest: sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4

If we merging --debug output into --verbose, below is a sample output of oras cp

# 3. verbose output with http-level debug log merged 
$ oras cp docker.io/library/hello-world:latest --platform linux/amd64 --to-oci-layout . --verbose
DEBU[0000] Request #0
> Request URL: "https://registry-1.docker.io/v2/library/hello-world/manifests/latest"
> Request method: "GET"
> 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": "oras/1.0.0"
DEBU[0000] Response #0
< Response Status: "401 Unauthorized"
< Response headers:
   "Date": "Tue, 04 Apr 2023 14:54:11 GMT"
   "Content-Length": "162"
   "Content-Type": "application/json"
   "Docker-Distribution-Api-Version": "registry/2.0"
   "Www-Authenticate": "Bearer realm=\"https://auth.docker.io/token\",service=\"registry.docker.io\",scope=\"repository:library/hello-world:pull\""
   "Strict-Transport-Security": "max-age=31536000"
   "Docker-Ratelimit-Source": "4.194.235.164"
DEBU[0000] Request #1
> Request URL: "https://auth.docker.io/token?scope=repository%3Alibrary%2Fhello-world%3Apull&service=registry.docker.io"
> Request method: "GET"
> Request headers:
   "Authorization": "*****"
   "User-Agent": "oras/1.0.0"
DEBU[0001] Response #1
< Response Status: "200 OK"
< Response headers:
   "Strict-Transport-Security": "max-age=31536000"
   "Content-Type": "application/json; charset=utf-8"
   "X-Trace-Id": "d210210defd082d168a3aca247949d51"
   "Date": "Tue, 04 Apr 2023 14:54:12 GMT"
DEBU[0001] Request #2
> Request URL: "https://registry-1.docker.io/v2/library/hello-world/manifests/latest"
> Request method: "GET"
> 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": "oras/1.0.0"
DEBU[0002] Response #2
< Response Status: "200 OK"
< Response headers:
   "Content-Length": "2561"
   "Docker-Ratelimit-Source": "4.194.235.164"
   "Content-Type": "application/vnd.docker.distribution.manifest.list.v2+json"
   "Docker-Content-Digest": "sha256:ffb13da98453e0f04d33a6eee5bb8e46ee50d08ebe17735fc0779d0349e889e9"
   "Docker-Distribution-Api-Version": "registry/2.0"
   "Etag": "\"sha256:ffb13da98453e0f04d33a6eee5bb8e46ee50d08ebe17735fc0779d0349e889e9\""
   "Date": "Tue, 04 Apr 2023 14:54:13 GMT"
   "Strict-Transport-Security": "max-age=31536000"
DEBU[0002] Request #3
> Request URL: "https://registry-1.docker.io/v2/library/hello-world/manifests/sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4"
> Request method: "GET"
> Request headers:
   "Accept": "application/vnd.docker.distribution.manifest.v2+json"
   "Authorization": "*****"
   "User-Agent": "oras/1.0.0"
DEBU[0002] Response #3
< Response Status: "200 OK"
< Response headers:
   "Strict-Transport-Security": "max-age=31536000"
   "Content-Type": "application/vnd.docker.distribution.manifest.v2+json"
   "Etag": "\"sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4\""
   "Docker-Content-Digest": "sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4"
   "Docker-Ratelimit-Source": "4.194.235.164"
   "Content-Length": "525"
   "Docker-Distribution-Api-Version": "registry/2.0"
   "Date": "Tue, 04 Apr 2023 14:54:13 GMT"
Copying 2db29710123e application/vnd.docker.image.rootfs.diff.tar.gzip
DEBU[0002] Request #4
> Request URL: "https://registry-1.docker.io/v2/library/hello-world/blobs/sha256:2db29710123e3e53a794f2694094b9b4338aa9ee5c40b930cb8063a1be392c54"
> Request method: "GET"
> Request headers:
   "User-Agent": "oras/1.0.0"
   "Authorization": "*****"
Copying feb5d9fea6a5 application/vnd.docker.container.image.v1+json
DEBU[0002] Request #5
> Request URL: "https://registry-1.docker.io/v2/library/hello-world/blobs/sha256:feb5d9fea6a5e9606aa995e879d862b825965ba48de054caab5ef356dc6b3412"
> Request method: "GET"
> Request headers:
   "Authorization": "*****"
   "User-Agent": "oras/1.0.0"
DEBU[0002] Response #4
< Response Status: "307 Temporary Redirect"
< Response headers:
   "Content-Type": "application/octet-stream"
   "Docker-Distribution-Api-Version": "registry/2.0"
   "Location": "https://production.cloudflare.docker.com/registry-v2/docker/registry/v2/blobs/sha256/2d/2db29710123e3e53a794f2694094b9b4338aa9ee5c40b930cb8063a1be392c54/data?verify=1680623053-dDHeR5t2Wjeas6YoFr8vgYoDNUk%3D"
   "Date": "Tue, 04 Apr 2023 14:54:13 GMT"
   "Content-Length": "0"
   "Strict-Transport-Security": "max-age=31536000"
DEBU[0002] Request #6
> Request URL: "https://production.cloudflare.docker.com/registry-v2/docker/registry/v2/blobs/sha256/2d/2db29710123e3e53a794f2694094b9b4338aa9ee5c40b930cb8063a1be392c54/data?verify=1680623053-dDHeR5t2Wjeas6YoFr8vgYoDNUk%3D"
> Request method: "GET"
> Request headers:
   "User-Agent": "oras/1.0.0"
   "Referer": "https://registry-1.docker.io/v2/library/hello-world/blobs/sha256:2db29710123e3e53a794f2694094b9b4338aa9ee5c40b930cb8063a1be392c54"
DEBU[0002] Response #6
< Response Status: "200 OK"
< Response headers:
   "Accept-Ranges": "bytes"
   "Age": "494480"
   "Etag": "\"369642d9a78b61be2aedfde4c4c84942\""
   "X-Amz-Request-Id": "83HFYH2V5007ZFJ6"
   "X-Amz-Version-Id": "prWfK2mfxjtaZBxAhjSd0EdAkFdnnxdK"
   "Server": "cloudflare"
   "Content-Type": "application/octet-stream"
   "Content-Length": "2479"
   "Cf-Cache-Status": "HIT"
   "X-Amz-Id-2": "VIQXDecRsDZjUd+fXy3H/hJl+4F8MVhrra/LbOUFhVaitqV/xgkRl6ipmTgePX53szSYD6dKvd0="
   "Date": "Tue, 04 Apr 2023 14:54:13 GMT"
   "Cache-Control": "public, max-age=14400"
   "Expires": "Tue, 04 Apr 2023 18:54:13 GMT"
   "Last-Modified": "Thu, 23 Sep 2021 23:48:07 GMT"
   "Cf-Ray": "7b2a62a8cb9c3f61-SIN"
   "Vary": "Accept-Encoding"
Copied  2db29710123e application/vnd.docker.image.rootfs.diff.tar.gzip
DEBU[0003] Response #5
< Response Status: "307 Temporary Redirect"
< Response headers:
   "Strict-Transport-Security": "max-age=31536000"
   "Content-Type": "application/octet-stream"
   "Docker-Distribution-Api-Version": "registry/2.0"
   "Location": "https://production.cloudflare.docker.com/registry-v2/docker/registry/v2/blobs/sha256/fe/feb5d9fea6a5e9606aa995e879d862b825965ba48de054caab5ef356dc6b3412/data?verify=1680623053-pt9TcWniEcaOA93ju%2FUTYZuU2nE%3D"
   "Date": "Tue, 04 Apr 2023 14:54:13 GMT"
   "Content-Length": "0"
DEBU[0003] Request #7
> Request URL: "https://production.cloudflare.docker.com/registry-v2/docker/registry/v2/blobs/sha256/fe/feb5d9fea6a5e9606aa995e879d862b825965ba48de054caab5ef356dc6b3412/data?verify=1680623053-pt9TcWniEcaOA93ju%2FUTYZuU2nE%3D"
> Request method: "GET"
> Request headers:
   "User-Agent": "oras/1.0.0"
   "Referer": "https://registry-1.docker.io/v2/library/hello-world/blobs/sha256:feb5d9fea6a5e9606aa995e879d862b825965ba48de054caab5ef356dc6b3412"
DEBU[0003] Response #7
< Response Status: "200 OK"
< Response headers:
   "Content-Type": "application/octet-stream"
   "Cf-Ray": "7b2a62a9fcf13f61-SIN"
   "Server": "cloudflare"
   "Content-Length": "1469"
   "Expires": "Tue, 04 Apr 2023 18:54:14 GMT"
   "X-Amz-Id-2": "dJ2bddHtdMvuRYCj06t9Vo1CFIqHQZPSCDOb61ylvGMRsqZ6qDiT5KzQUfm4Rqg/WdDY+IilF4k="
   "X-Amz-Request-Id": "X26GXGMTG5BNB4AX"
   "Date": "Tue, 04 Apr 2023 14:54:14 GMT"
   "Vary": "Accept-Encoding"
   "Cf-Cache-Status": "HIT"
   "Accept-Ranges": "bytes"
   "Age": "494481"
   "Cache-Control": "public, max-age=14400"
   "Etag": "\"d1b67b7af6742e1a64318eb61e454780\""
   "Last-Modified": "Thu, 23 Sep 2021 23:48:10 GMT"
   "X-Amz-Version-Id": "yGfrzOpWboZdXB5GlkWaLOLg3aEGyNWg"
Copied  feb5d9fea6a5 application/vnd.docker.container.image.v1+json
Copying f54a58bc1aac application/vnd.docker.distribution.manifest.v2+json
Copied  f54a58bc1aac application/vnd.docker.distribution.manifest.v2+json
Copied [registry] docker.io/library/hello-world:latest => [oci-layout] .
Digest: sha256:f54a58bc1aac5ea1a25d796ae155dc228b3f0e11d046ae276b39c4bf2f13d8c4

So basically, if --debug logs are merged into --verbose and we don't have another flag like --detailed, oras user will get output 3 or 2, with or without --verbose set respectively. But they won't be able to get output 1.

[toddysm]

We got this scenario completely wrong (see #916) Output 2 is very misleading from user point of view. The default should be output 1.

[ridhoq]

Hey folks, I wanted to chime in on this thread as I was recently trying to use oras to troubleshoot an issue. I ended up not getting the output that I needed and tried to use crane instead and found it to be more helpful. Here is an example I saw from crane using the same artifact that @qweeah showed in the earlier comment.

Crane output

➜  ~ crane pull --verbose docker.io/library/hello-world:latest --platform linux/amd64 out.tar
2024/02/16 01:35:17 --> GET https://index.docker.io/v2/
2024/02/16 01:35:17 GET /v2/ HTTP/1.1
Host: index.docker.io
User-Agent: crane/v0.16.1 go-containerregistry/v0.16.1
Accept-Encoding: gzip


2024/02/16 01:35:17 <-- 401 https://index.docker.io/v2/ (242.862141ms)
2024/02/16 01:35:17 HTTP/1.1 401 Unauthorized
Content-Length: 87
Content-Type: application/json
Date: Fri, 16 Feb 2024 01:35:17 GMT
Docker-Distribution-Api-Version: registry/2.0
Strict-Transport-Security: max-age=31536000
Www-Authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io"

{"errors":[{"code":"UNAUTHORIZED","message":"authentication required","detail":null}]}

2024/02/16 01:35:17 --> GET https://auth.docker.io/token?scope=repository%3Alibrary%2Fhello-world%3Apull&service=registry.docker.io [body redacted: basic token response contains credentials]
2024/02/16 01:35:17 GET /token?scope=repository%3Alibrary%2Fhello-world%3Apull&service=registry.docker.io HTTP/1.1
Host: auth.docker.io
User-Agent: crane/v0.16.1 go-containerregistry/v0.16.1
Accept-Encoding: gzip


2024/02/16 01:35:17 <-- 200 https://auth.docker.io/token?scope=repository%3Alibrary%2Fhello-world%3Apull&service=registry.docker.io (245.003684ms) [body redacted: basic token response contains credentials]
2024/02/16 01:35:17 HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json
Date: Fri, 16 Feb 2024 01:35:17 GMT
Strict-Transport-Security: max-age=31536000


2024/02/16 01:35:17 --> GET https://index.docker.io/v2/library/hello-world/manifests/latest
2024/02/16 01:35:17 GET /v2/library/hello-world/manifests/latest HTTP/1.1
Host: index.docker.io
User-Agent: crane/v0.16.1 go-containerregistry/v0.16.1
Accept: application/vnd.docker.distribution.manifest.v1+json,application/vnd.docker.distribution.manifest.v1+prettyjws,application/vnd.docker.distribution.manifest.v2+json,application/vnd.oci.image.manifest.v1+json,application/vnd.docker.distribution.manifest.list.v2+json,application/vnd.oci.image.index.v1+json
Authorization: <redacted>
Accept-Encoding: gzip


2024/02/16 01:35:17 <-- 200 https://index.docker.io/v2/library/hello-world/manifests/latest (127.026832ms)
2024/02/16 01:35:17 HTTP/1.1 200 OK
Content-Length: 9125
Content-Type: application/vnd.oci.image.index.v1+json
Date: Fri, 16 Feb 2024 01:35:17 GMT
Docker-Content-Digest: sha256:d000bc569937abbe195e20322a0bde6b2922d805332fd6d8a68b19f524b7d21d
Docker-Distribution-Api-Version: registry/2.0
Docker-Ratelimit-Source: 4.154.44.191
Etag: "sha256:d000bc569937abbe195e20322a0bde6b2922d805332fd6d8a68b19f524b7d21d"
Strict-Transport-Security: max-age=31536000

{"manifests":[{"annotations":{"org.opencontainers.image.revision":"3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee","org.opencontainers.image.source":"https:\/\/github.com\/docker-library\/hello-world.git#3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee:amd64\/hello-world","org.opencontainers.image.url":"https:\/\/hub.docker.com\/_\/hello-world","org.opencontainers.image.version":"linux"},"digest":"sha256:e2fc4e5012d16e7fe466f5291c476431beaa1f9b90a5c2125b493ed28e2aba57","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"amd64","os":"linux"},"size":861},{"annotations":{"vnd.docker.reference.digest":"sha256:e2fc4e5012d16e7fe466f5291c476431beaa1f9b90a5c2125b493ed28e2aba57","vnd.docker.reference.type":"attestation-manifest"},"digest":"sha256:579b3724a7b189f6dca599a46f16d801a43d5def185de0b7bcd5fb9d1e312c27","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"unknown","os":"unknown"},"size":837},{"annotations":{"org.opencontainers.image.revision":"3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee","org.opencontainers.image.source":"https:\/\/github.com\/docker-library\/hello-world.git#3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee:arm32v5\/hello-world","org.opencontainers.image.url":"https:\/\/hub.docker.com\/_\/hello-world","org.opencontainers.image.version":"linux"},"digest":"sha256:c2d891e5c2fb4c723efb72b064be3351189f62222bd3681ce7e57f2a1527362c","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"arm","os":"linux","variant":"v5"},"size":863},{"annotations":{"vnd.docker.reference.digest":"sha256:c2d891e5c2fb4c723efb72b064be3351189f62222bd3681ce7e57f2a1527362c","vnd.docker.reference.type":"attestation-manifest"},"digest":"sha256:6901d6a88eee6e90f0baa62b020bb61c4f13194cbcd9bf568ab66e8cc3f940dd","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"unknown","os":"unknown"},"size":566},{"annotations":{"org.opencontainers.image.revision":"3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee","org.opencontainers.image.source":"https:\/\/github.com\/docker-library\/hello-world.git#3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee:arm32v7\/hello-world","org.opencontainers.image.url":"https:\/\/hub.docker.com\/_\/hello-world","org.opencontainers.image.version":"linux"},"digest":"sha256:20aea1c63c90d5e117db787c9fe1a8cd0ad98bedb5fd711273ffe05c084ff18a","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"arm","os":"linux","variant":"v7"},"size":863},{"annotations":{"vnd.docker.reference.digest":"sha256:20aea1c63c90d5e117db787c9fe1a8cd0ad98bedb5fd711273ffe05c084ff18a","vnd.docker.reference.type":"attestation-manifest"},"digest":"sha256:70304c314d8a61ba1b36518624bb00bfff8d4b6016153792042de43f0453ca61","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"unknown","os":"unknown"},"size":837},{"annotations":{"org.opencontainers.image.revision":"3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee","org.opencontainers.image.source":"https:\/\/github.com\/docker-library\/hello-world.git#3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee:arm64v8\/hello-world","org.opencontainers.image.url":"https:\/\/hub.docker.com\/_\/hello-world","org.opencontainers.image.version":"linux"},"digest":"sha256:2d4e459f4ecb5329407ae3e47cbc107a2fbace221354ca75960af4c047b3cb13","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"arm64","os":"linux","variant":"v8"},"size":863},{"annotations":{"vnd.docker.reference.digest":"sha256:2d4e459f4ecb5329407ae3e47cbc107a2fbace221354ca75960af4c047b3cb13","vnd.docker.reference.type":"attestation-manifest"},"digest":"sha256:1f11fbd1720fcae3e402fc3eecb7d57c67023d2d1e11becc99ad9c7fe97d65ca","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"unknown","os":"unknown"},"size":837},{"annotations":{"org.opencontainers.image.revision":"3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee","org.opencontainers.image.source":"https:\/\/github.com\/docker-library\/hello-world.git#3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee:i386\/hello-world","org.opencontainers.image.url":"https:\/\/hub.docker.com\/_\/hello-world","org.opencontainers.image.version":"linux"},"digest":"sha256:dbbd3cf666311ad526fad9d1746177469268f32fd91b371df2ebd1c84eb22f23","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"386","os":"linux"},"size":860},{"annotations":{"vnd.docker.reference.digest":"sha256:dbbd3cf666311ad526fad9d1746177469268f32fd91b371df2ebd1c84eb22f23","vnd.docker.reference.type":"attestation-manifest"},"digest":"sha256:18b1c92de36d42c75440c6fd6b25605cc91709d176faaccca8afe58b317bc33a","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"unknown","os":"unknown"},"size":566},{"annotations":{"org.opencontainers.image.revision":"3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee","org.opencontainers.image.source":"https:\/\/github.com\/docker-library\/hello-world.git#3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee:mips64le\/hello-world","org.opencontainers.image.url":"https:\/\/hub.docker.com\/_\/hello-world","org.opencontainers.image.version":"linux"},"digest":"sha256:c19784034d46da48550487c5c44639f5f92d48be7b9baf4d67b5377a454d92af","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"mips64le","os":"linux"},"size":864},{"annotations":{"vnd.docker.reference.digest":"sha256:c19784034d46da48550487c5c44639f5f92d48be7b9baf4d67b5377a454d92af","vnd.docker.reference.type":"attestation-manifest"},"digest":"sha256:951bcd144ddccd1ee902dc180b435faabaaa6a8747e70cbc893f2dca16badb94","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"unknown","os":"unknown"},"size":566},{"annotations":{"org.opencontainers.image.revision":"3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee","org.opencontainers.image.source":"https:\/\/github.com\/docker-library\/hello-world.git#3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee:ppc64le\/hello-world","org.opencontainers.image.url":"https:\/\/hub.docker.com\/_\/hello-world","org.opencontainers.image.version":"linux"},"digest":"sha256:f0c95f1ebb50c9b0b3e3416fb9dd4d1d197386a076c464cceea3d1f94c321b8f","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"ppc64le","os":"linux"},"size":863},{"annotations":{"vnd.docker.reference.digest":"sha256:f0c95f1ebb50c9b0b3e3416fb9dd4d1d197386a076c464cceea3d1f94c321b8f","vnd.docker.reference.type":"attestation-manifest"},"digest":"sha256:838d191bca398e46cddebc48e816da83b0389d4ed2d64f408d618521b8fd1a57","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"unknown","os":"unknown"},"size":837},{"annotations":{"org.opencontainers.image.revision":"3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee","org.opencontainers.image.source":"https:\/\/github.com\/docker-library\/hello-world.git#3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee:riscv64\/hello-world","org.opencontainers.image.url":"https:\/\/hub.docker.com\/_\/hello-world","org.opencontainers.image.version":"linux"},"digest":"sha256:8d064a6fc27fd5e97fa8225994a1addd872396236367745bea30c92d6c032fa3","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"riscv64","os":"linux"},"size":863},{"annotations":{"vnd.docker.reference.digest":"sha256:8d064a6fc27fd5e97fa8225994a1addd872396236367745bea30c92d6c032fa3","vnd.docker.reference.type":"attestation-manifest"},"digest":"sha256:48147407c4594e45b7c3f0be1019bb0f44d78d7f037ce63e0e3da75b256f849e","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"unknown","os":"unknown"},"size":837},{"annotations":{"org.opencontainers.image.revision":"3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee","org.opencontainers.image.source":"https:\/\/github.com\/docker-library\/hello-world.git#3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee:s390x\/hello-world","org.opencontainers.image.url":"https:\/\/hub.docker.com\/_\/hello-world","org.opencontainers.image.version":"linux"},"digest":"sha256:65f4b0d1802589b418bb6774d85de3d1a11d5bd971ee73cb8569504d928bb5d9","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"s390x","os":"linux"},"size":861},{"annotations":{"vnd.docker.reference.digest":"sha256:65f4b0d1802589b418bb6774d85de3d1a11d5bd971ee73cb8569504d928bb5d9","vnd.docker.reference.type":"attestation-manifest"},"digest":"sha256:50f420e8710676da03668e446f1f51097b745e3e2c9807b018e569d26d4f65f7","mediaType":"application\/vnd.oci.image.manifest.v1+json","platform":{"architecture":"unknown","os":"unknown"},"size":837},{"digest":"sha256:245fe15fbb8f72b1988e35debf9172dedde4ec794de307633c5fb38c96ded61a","mediaType":"application\/vnd.docker.distribution.manifest.v2+json","platform":{"architecture":"amd64","os":"windows","os.version":"10.0.20348.2322"},"size":946},{"digest":"sha256:088bdbea94d5c8fe3eb9f3cec836c3f7ea82923e7d0d3a4f1146ef0f860f5a93","mediaType":"application\/vnd.docker.distribution.manifest.v2+json","platform":{"architecture":"amd64","os":"windows","os.version":"10.0.17763.5458"},"size":946}],"mediaType":"application\/vnd.oci.image.index.v1+json","schemaVersion":2}
2024/02/16 01:35:17 --> GET https://index.docker.io/v2/library/hello-world/manifests/sha256:e2fc4e5012d16e7fe466f5291c476431beaa1f9b90a5c2125b493ed28e2aba57
2024/02/16 01:35:17 GET /v2/library/hello-world/manifests/sha256:e2fc4e5012d16e7fe466f5291c476431beaa1f9b90a5c2125b493ed28e2aba57 HTTP/1.1
Host: index.docker.io
User-Agent: crane/v0.16.1 go-containerregistry/v0.16.1
Accept: application/vnd.oci.image.manifest.v1+json
Authorization: <redacted>
Accept-Encoding: gzip


2024/02/16 01:35:18 <-- 200 https://index.docker.io/v2/library/hello-world/manifests/sha256:e2fc4e5012d16e7fe466f5291c476431beaa1f9b90a5c2125b493ed28e2aba57 (102.724948ms)
2024/02/16 01:35:18 HTTP/1.1 200 OK
Content-Length: 861
Content-Type: application/vnd.oci.image.manifest.v1+json
Date: Fri, 16 Feb 2024 01:35:18 GMT
Docker-Content-Digest: sha256:e2fc4e5012d16e7fe466f5291c476431beaa1f9b90a5c2125b493ed28e2aba57
Docker-Distribution-Api-Version: registry/2.0
Docker-Ratelimit-Source: 4.154.44.191
Etag: "sha256:e2fc4e5012d16e7fe466f5291c476431beaa1f9b90a5c2125b493ed28e2aba57"
Strict-Transport-Security: max-age=31536000

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:d2c94e258dcb3c5ac2798d32e1249e42ef01cba4841c2234249495f87264ac5a",
    "size": 581
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:c1ec31eb59444d78df06a974d155e597c894ab4cda84f08294145e845394988e",
      "size": 2459
    }
  ],
  "annotations": {
    "org.opencontainers.image.revision": "3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee",
    "org.opencontainers.image.source": "https://github.com/docker-library/hello-world.git#3fb6ebca4163bf5b9cc496ac3e8f11cb1e754aee:amd64/hello-world",
    "org.opencontainers.image.url": "https://hub.docker.com/_/hello-world",
    "org.opencontainers.image.version": "linux"
  }
}
2024/02/16 01:35:18 --> GET https://index.docker.io/v2/library/hello-world/blobs/sha256:d2c94e258dcb3c5ac2798d32e1249e42ef01cba4841c2234249495f87264ac5a
2024/02/16 01:35:18 GET /v2/library/hello-world/blobs/sha256:d2c94e258dcb3c5ac2798d32e1249e42ef01cba4841c2234249495f87264ac5a HTTP/1.1
Host: index.docker.io
User-Agent: crane/v0.16.1 go-containerregistry/v0.16.1
Authorization: <redacted>
Accept-Encoding: gzip


2024/02/16 01:35:18 <-- 307 https://index.docker.io/v2/library/hello-world/blobs/sha256:d2c94e258dcb3c5ac2798d32e1249e42ef01cba4841c2234249495f87264ac5a (77.487644ms)
2024/02/16 01:35:18 HTTP/1.1 307 Temporary Redirect
Content-Type: application/octet-stream
Date: Fri, 16 Feb 2024 01:35:18 GMT
Docker-Distribution-Api-Version: registry/2.0
Location: https://production.cloudflare.docker.com/registry-v2/docker/registry/v2/blobs/sha256/d2/d2c94e258dcb3c5ac2798d32e1249e42ef01cba4841c2234249495f87264ac5a/data?verify=1708050318-Na%2FWhsTaVW6OL7VwlVbNyaQ8RqU%3D
Strict-Transport-Security: max-age=31536000
Content-Length: 0


2024/02/16 01:35:18 --> GET https://production.cloudflare.docker.com/registry-v2/docker/registry/v2/blobs/sha256/d2/d2c94e258dcb3c5ac2798d32e1249e42ef01cba4841c2234249495f87264ac5a/data?verify=1708050318-Na%2FWhsTaVW6OL7VwlVbNyaQ8RqU%3D
2024/02/16 01:35:18 GET /registry-v2/docker/registry/v2/blobs/sha256/d2/d2c94e258dcb3c5ac2798d32e1249e42ef01cba4841c2234249495f87264ac5a/data?verify=1708050318-Na%2FWhsTaVW6OL7VwlVbNyaQ8RqU%3D HTTP/1.1
Host: production.cloudflare.docker.com
User-Agent: crane/v0.16.1 go-containerregistry/v0.16.1
Referer: https://index.docker.io/v2/library/hello-world/blobs/sha256:d2c94e258dcb3c5ac2798d32e1249e42ef01cba4841c2234249495f87264ac5a
Accept-Encoding: gzip


2024/02/16 01:35:18 <-- 200 https://production.cloudflare.docker.com/registry-v2/docker/registry/v2/blobs/sha256/d2/d2c94e258dcb3c5ac2798d32e1249e42ef01cba4841c2234249495f87264ac5a/data?verify=1708050318-Na%2FWhsTaVW6OL7VwlVbNyaQ8RqU%3D (45.60931ms)
2024/02/16 01:35:18 HTTP/2.0 200 OK
Content-Length: 581
Accept-Ranges: bytes
Age: 701068
Cache-Control: public, max-age=14400
Cf-Cache-Status: HIT
Cf-Ray: 85620d9a7b62c4dc-SEA
Content-Type: application/octet-stream
Date: Fri, 16 Feb 2024 01:35:18 GMT
Etag: "3c8c78c9abef42432b7099e7ca8fcbcb"
Expires: Fri, 16 Feb 2024 05:35:18 GMT
Last-Modified: Fri, 15 Dec 2023 22:04:48 GMT
Server: cloudflare
Vary: Accept-Encoding
X-Amz-Id-2: sBuOmaswHMWv+P3ETZzy92fg5gNo3csl8DsU9XOaokjTOOnlMHFkZ3uUagy+wm2jEzozZms+ukA=
X-Amz-Request-Id: DPZ4CE800C9AG7YW
X-Amz-Server-Side-Encryption: AES256
X-Amz-Version-Id: vgiSvWq3dRJV3u4maLEuGHchio6CGs5J

{"architecture":"amd64","config":{"Env":["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"],"Cmd":["/hello"],"WorkingDir":"/","ArgsEscaped":true,"OnBuild":null},"created":"2023-05-02T16:49:27Z","history":[{"created":"2023-05-02T16:49:27Z","created_by":"COPY hello / # buildkit","comment":"buildkit.dockerfile.v0"},{"created":"2023-05-02T16:49:27Z","created_by":"CMD [\"/hello\"]","comment":"buildkit.dockerfile.v0","empty_layer":true}],"os":"linux","rootfs":{"type":"layers","diff_ids":["sha256:ac28800ec8bb38d5c35b49d45a6ac4777544941199075dff8c4eb63e093aa81e"]}}
2024/02/16 01:35:18 --> GET https://index.docker.io/v2/library/hello-world/blobs/sha256:c1ec31eb59444d78df06a974d155e597c894ab4cda84f08294145e845394988e [body redacted: omitting binary blobs from logs]
2024/02/16 01:35:18 GET /v2/library/hello-world/blobs/sha256:c1ec31eb59444d78df06a974d155e597c894ab4cda84f08294145e845394988e HTTP/1.1
Host: index.docker.io
User-Agent: crane/v0.16.1 go-containerregistry/v0.16.1
Authorization: <redacted>
Accept-Encoding: gzip


2024/02/16 01:35:18 <-- 307 https://index.docker.io/v2/library/hello-world/blobs/sha256:c1ec31eb59444d78df06a974d155e597c894ab4cda84f08294145e845394988e (75.776011ms) [body redacted: omitting binary blobs from logs]
2024/02/16 01:35:18 HTTP/1.1 307 Temporary Redirect
Content-Type: application/octet-stream
Date: Fri, 16 Feb 2024 01:35:18 GMT
Docker-Distribution-Api-Version: registry/2.0
Location: https://production.cloudflare.docker.com/registry-v2/docker/registry/v2/blobs/sha256/c1/c1ec31eb59444d78df06a974d155e597c894ab4cda84f08294145e845394988e/data?verify=1708050318-4aJh9si48GZeN18sm%2F%2B8RvpoOuI%3D
Strict-Transport-Security: max-age=31536000
Content-Length: 0


2024/02/16 01:35:18 --> GET https://production.cloudflare.docker.com/registry-v2/docker/registry/v2/blobs/sha256/c1/c1ec31eb59444d78df06a974d155e597c894ab4cda84f08294145e845394988e/data?verify=1708050318-4aJh9si48GZeN18sm%2F%2B8RvpoOuI%3D [body redacted: omitting binary blobs from logs]
2024/02/16 01:35:18 GET /registry-v2/docker/registry/v2/blobs/sha256/c1/c1ec31eb59444d78df06a974d155e597c894ab4cda84f08294145e845394988e/data?verify=1708050318-4aJh9si48GZeN18sm%2F%2B8RvpoOuI%3D HTTP/1.1
Host: production.cloudflare.docker.com
User-Agent: crane/v0.16.1 go-containerregistry/v0.16.1
Referer: https://index.docker.io/v2/library/hello-world/blobs/sha256:c1ec31eb59444d78df06a974d155e597c894ab4cda84f08294145e845394988e
Accept-Encoding: gzip


2024/02/16 01:35:18 <-- 200 https://production.cloudflare.docker.com/registry-v2/docker/registry/v2/blobs/sha256/c1/c1ec31eb59444d78df06a974d155e597c894ab4cda84f08294145e845394988e/data?verify=1708050318-4aJh9si48GZeN18sm%2F%2B8RvpoOuI%3D (21.779934ms) [body redacted: omitting binary blobs from logs]
2024/02/16 01:35:18 HTTP/2.0 200 OK
Content-Length: 2459
Accept-Ranges: bytes
Age: 514295
Cache-Control: public, max-age=14400
Cf-Cache-Status: HIT
Cf-Ray: 85620d9b1c13c4dc-SEA
Content-Type: application/octet-stream
Date: Fri, 16 Feb 2024 01:35:18 GMT
Etag: "46c29c74076f746673d9545077069e2d"
Expires: Fri, 16 Feb 2024 05:35:18 GMT
Last-Modified: Fri, 15 Dec 2023 22:04:48 GMT
Server: cloudflare
Vary: Accept-Encoding
X-Amz-Id-2: Z/V+foGJHSVGd7bqZj01BYtoNY6Pklbea6yNyLH8b8sgJ3W94lGg2qrXAKVCC/yA6GgNUOaWMEY=
X-Amz-Request-Id: B6GFWWJ5CY6ER70Q
X-Amz-Server-Side-Encryption: AES256
X-Amz-Version-Id: a1HWMiAg5v.1SNDB1J8slO1jiWfqyCr0

Feedback

• Having newlines separate the output of each request/response is much easier to read
• The first line of each request/response is informative and makes it easy to understand the context of the subsequent output. For example, 2024/02/16 01:35:17 --> GET https://index.docker.io/v2/library/hello-world/manifests/latest and 2024/02/16 01:35:17 <-- 200 https://index.docker.io/v2/library/hello-world/manifests/latest (127.026832ms). The oras output does not show the timestamp of each request.
• The crane output is presented in order which makes it easy to follow what happen. The oras output may be presented out of order which means you may have to scroll back and forth to see the request and response.
• The crane output also shows the body of the response when relevant, such as manifest or token responses. While it may be a bit noisy, it is desirable to have in a verbose context
• As discussed above, it wasn't clear to me that oras --debug would be equivalent to crane --verbose. At first, I attempted to use oras --verbose and saw that it didn't have the request and responses, so I moved to crane. It wasn't until I found this issue that I realized oras actually had this capability. So I think it may make sense to either consolidate these options or allow for different levels of verbosity.

If I have time, I may submit PR to propose some of the changes in the feedback. Let me know what your thoughts are.

[sajayantony]

I’ve been proposing to drop ORAS debug from basics scenarios and enhance all to —verbose scenario. Debug IMHO should be for ORAS lib or CLI developers not for registry or target debugging. Feel free to PR this @ridhoq.

[TerryHowe]

It would be convenient if debug logging was routed to stderr so if a user is parsing output, they don't have to sort though that.

[TerryHowe]

Related #1483