Add debug documentation for pull mode

This change adds information to debug how the SOCI snapshotter pulls an
image.

Signed-off-by: Kern Walster <walster@amazon.com>

Author: Kern--

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -34,3 +34,7 @@ body:
   - type: textarea
     attributes:
       label: Any additional context or information about the bug
+      description: |
+        If this is an issue with lazy loading, please indicate how the snapshotter pulled the image. See [Determining how an image was pulled](../../docs/debug.md#determining-how-an-image-was-pulled) in the debugging doc for more information.
+    validations:
+      required: false

docs/debug.md

@@ -12,6 +12,11 @@ This document outlines where to find/access logs and metrics for the snapshotter
     - [Metrics Emitted](#metrics-emitted)
 - [Common Scenarios](#common-scenarios)
   - [Pulling an Image](#pulling-an-image)
+    - [Determining How an Image Was Pulled](#determining-how-an-image-was-pulled)
+      - [Explicit Index Digest](#explicit-index-digest)
+      - [SOCI Index Manifest v2 via SOCI-Enabled Images](#soci-index-manifest-v2-via-soci-enabled-images)
+      - [SOCI Index Manifest v1 via The Referrers API](#soci-index-manifest-v1-via-the-referrers-api)
+      - [Ahead of Time Without a SOCI Index](#ahead-of-time-without-a-soci-index)
     - [No lazy-loading](#no-lazy-loading)
     - [Pull Taking An Abnormal Amount Of Time](#pull-taking-an-abnormal-amount-of-time)
     - [Background Fetching](#background-fetching)
@@ -103,6 +108,57 @@ While pulling, the image manifest, config, and layers without zTOCs' are fetched
 
 Below are a list of common error paths that may occur in this phase:
 
+### Determining How an Image Was Pulled
+
+The SOCI snapshotter can pull an image using one of four modes:
+1) Lazily using an explicitly provided SOCI index digest
+2) Lazily using a SOCI index manifest v2 via SOCI-enabled images
+3) Lazily using a SOCI index manifest v1 via the Referrers API
+4) Ahead of time without a SOCI index
+
+Determining which of these mode was used is often a good first step for debugging image pull issues.
+
+When the SOCI snapshotter starts to pull an image, it will emit a set of debug logs to indicate which modes were tried and which was ultimately used.
+
+#### Explicit Index Digest
+If the SOCI snapshotter finds an explicit index digest, it will use it and log the following message:
+```
+using provided soci index digest
+```
+
+#### SOCI Index Manifest v2 via SOCI-Enabled Images
+If an explicit index digest was not provided. The SOCI snapshotter will try to use a SOCI-enabled image.
+
+If `pull_modes.soci_v2.enabled` is `false`, the snapshotter will log:
+```
+soci v2 is disabled
+```
+
+Otherwise, if it find that the image is SOCI-enabled, it will log:
+```
+using soci v2 index annotation
+```
+
+#### SOCI Index Manifest v1 via The Referrers API
+If the image is not SOCI-enabled, the SOCI snapshotter will try to use the referrers API.
+
+If `pull_modes.soci_v1.enabled` is `false` (it is false by default), the SOCI snapshotter will log:
+```
+soci v1 is disabled
+```
+
+Otherwise, if it finds a SOCI index via the referrers API, it will log:
+```
+using soci v1 index via referrers API
+```
+
+#### Ahead of Time Without a SOCI Index
+If none of the above apply, the SOCI snapshotter will pull the image ahead of time and log:
+
+```
+deferring to container runtime
+```
+
 ### No lazy-loading
 
 If you notice that all layers are being fetched for an image or that `FUSE` mounts are not being created for layers with a zTOC than that means that remote mounting has failed for those layers.

fs/fs.go

@@ -474,8 +474,12 @@ func (fs *filesystem) findSociIndexDesc(ctx context.Context, imageManifestDigest
 	if fs.pullModes.SOCIv2.Enable {
 		log.G(ctx).Debug("checking for soci v2 index annotation")
 		desc, err := findSociIndexDescAnnotation(ctx, imgDigest, remoteStore)
-		if err == nil || !errors.Is(err, errdefs.ErrNotFound) {
-			return desc, err
+		if err == nil {
+			log.G(ctx).Debug("using soci v2 index annotation")
+			return desc, nil
+		}
+		if !errors.Is(err, errdefs.ErrNotFound) {
+			return ocispec.Descriptor{}, err
 		}
 		log.G(ctx).Debug("soci v2 index annotation not found")
 	} else {
@@ -486,8 +490,12 @@ func (fs *filesystem) findSociIndexDesc(ctx context.Context, imageManifestDigest
 	if fs.pullModes.SOCIv1.Enable {
 		log.G(ctx).Debug("checking for soci v1 index via referrers API")
 		desc, err := findSociIndexDescReferrer(ctx, imgDigest, remoteStore)
-		if err == nil || !errors.Is(err, ErrNoReferrers) {
-			return desc, err
+		if err == nil {
+			log.G(ctx).Debug("using soci v1 index via referrers API")
+			return desc, nil
+		}
+		if !errors.Is(err, ErrNoReferrers) {
+			return ocispec.Descriptor{}, err
 		}
 		log.G(ctx).Debug("soci v1 referrers not found")
 	} else {