Implement Named Error Objects System for Image Customizer (#324)

This PR implements a comprehensive named error objects system for the
Image Customizer to improve error telemetry and provide organized error
messages for users.

## Key Changes

**Named Error Objects Pattern**
- Replaced centralized error categories and codes with locally-defined
named error objects
- Each error is defined in the file where it's used with descriptive
names like `ErrCannotSetUidOnExistingUser`
- Error objects follow the pattern:
`NewImageCustomizerError("Module:ErrorType", "error message")`

**Error Message Transformation**
Updated all error handling to use proper wrapping patterns:
```go
// Before
return fmt.Errorf("cannot set UID (%d) on a user (%s) that already exists", *user.UID, user.Name)

// After  
var ErrCannotSetUidOnExistingUser = NewImageCustomizerError("Users:SetUidOnExistingUser", "cannot set UID on a user that already exists")
return fmt.Errorf("%w (UID='%d', user='%s')", ErrCannotSetUidOnExistingUser, *user.UID, user.Name)
```

**Telemetry Integration**
- Simplified telemetry to only record `error.name` in span attributes
- The deepest ImageCustomizerError in the error chain is used for the
error name in the span

**Test Compatibility**
- Updated error object messages to align with existing test expectations
- Ensured error messages match patterns expected by
`assert.ErrorContains()` calls

**Comprehensive Coverage**
The system now covers all leaf errors across the entire
imagecustomizerlib package, including:
- Image processing and format conversion errors
- Input/output validation errors  
- OS customization errors (packages, services, users, groups, etc.)
- Verity and security feature errors
- Environment and configuration validation errors

The system maintains full functionality while providing better error
categorization for telemetry and more descriptive error messages for end
users.

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.

---------

Co-authored-by: Adit Jha <[email protected]>
Co-authored-by: Adit Jha <[email protected]>

Author: Copilot

toolkit/scripts/telemetry_hopper/telemetry_hopper.py

@@ -1,6 +1,7 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 
+import json
 import os
 import logging
 import grpc
@@ -159,12 +160,22 @@ def _create_spans(self, request) -> List[SpanData]:
 def extract_attribute_value(value_proto: Any) -> Optional[Any]:
     """Extract value from protobuf AnyValue."""
     value_case = value_proto.WhichOneof("value")
+
     value_mapping = {
         "string_value": value_proto.string_value,
         "int_value": value_proto.int_value,
         "double_value": value_proto.double_value,
         "bool_value": value_proto.bool_value,
     }
+
+    if value_case == "array_value":
+        array_values = []
+        for item in value_proto.array_value.values:
+            item_value = extract_attribute_value(item)
+            if item_value is not None:
+                array_values.append(item_value)
+        return json.dumps(array_values)
+
     return value_mapping.get(value_case)
 
 

toolkit/tools/internal/userutils/userutils.go

@@ -71,12 +71,7 @@ func userExistsHelper(name string, installChroot safechroot.ChrootInterface, gro
 		_, stderr, err := shell.Execute("id", typeFlag, name)
 		if err != nil {
 			if !strings.Contains(stderr, "no such user") {
-				typeStr := "user"
-				if group {
-					typeStr = "group"
-				}
-
-				return fmt.Errorf("failed to check if %s exists (%s):\n%w", typeStr, name, err)
+				return err
 			}
 
 			userExists = false

toolkit/tools/pkg/imagecustomizerlib/artifactsinputoutput.go

@@ -27,6 +27,29 @@ import (
 	"golang.org/x/sys/unix"
 )
 
+var (
+	// Artifact handling errors
+	ErrArtifactImageConnection              = NewImageCustomizerError("Artifacts:ImageConnection", "failed to connect to image file to output artifacts")
+	ErrArtifactESPPartitionMount            = NewImageCustomizerError("Artifacts:ESPPartitionMount", "failed to mount ESP partition")
+	ErrArtifactUKIDirectoryRead             = NewImageCustomizerError("Artifacts:UKIDirectoryRead", "failed to read UKI directory")
+	ErrArtifactBinaryCopy                   = NewImageCustomizerError("Artifacts:BinaryCopy", "failed to copy binary")
+	ErrArtifactRootHashDump                 = NewImageCustomizerError("Artifacts:RootHashDump", "failed to dump root hash")
+	ErrArtifactInjectFilesYamlWrite         = NewImageCustomizerError("Artifacts:InjectFilesYamlWrite", "failed to write inject-files.yaml")
+	ErrArtifactInjectFilesYamlMarshal       = NewImageCustomizerError("Artifacts:InjectFilesYamlMarshal", "failed to marshal inject files metadata")
+	ErrArtifactInvalidInjectFilesConfig     = NewImageCustomizerError("Artifacts:InvalidInjectFilesConfig", "invalid inject files config")
+	ErrArtifactInjectFilesPathResolution    = NewImageCustomizerError("Artifacts:InjectFilesPathResolution", "failed to get absolute path of inject-files.yaml")
+	ErrArtifactInjectFilesImageConnection   = NewImageCustomizerError("Artifacts:InjectFilesImageConnection", "failed to connect to image file to inject files")
+	ErrArtifactInjectFilesPartitionMount    = NewImageCustomizerError("Artifacts:InjectFilesPartitionMount", "failed to mount partition for file injection")
+	ErrArtifactPartitionUnmount             = NewImageCustomizerError("Artifacts:PartitionUnmount", "failed to cleanly unmount partition")
+	ErrArtifactCosiImageConversion          = NewImageCustomizerError("Artifacts:CosiImageConversion", "failed to convert customized raw image to cosi output format")
+	ErrArtifactOutputImageConversion        = NewImageCustomizerError("Artifacts:OutputImageConversion", "failed to convert customized raw image to output format")
+	ErrArtifactImageConnectionForExtraction = NewImageCustomizerError("Artifacts:ImageConnectionForExtraction", "failed to connect to image")
+	ErrArtifactImageConnectionClose         = NewImageCustomizerError("Artifacts:ImageConnectionClose", "failed to cleanly close image connection")
+	ErrArtifactReleaseFileRead              = NewImageCustomizerError("Artifacts:ReleaseFileRead", "failed to read release file")
+	ErrArtifactImageUuidNotFound            = NewImageCustomizerError("Artifacts:ImageUuidNotFound", "IMAGE_UUID not found in release file")
+	ErrArtifactImageUuidParse               = NewImageCustomizerError("Artifacts:ImageUuidParse", "failed to parse IMAGE_UUID")
+)
+
 const (
 	ShimDir        = "EFI/BOOT"
 	SystemdBootDir = "EFI/systemd"
@@ -46,7 +69,7 @@ func outputArtifacts(ctx context.Context, items []imagecustomizerapi.OutputArtif
 
 	loopback, err := safeloopback.NewLoopback(buildImage)
 	if err != nil {
-		return fmt.Errorf("failed to connect to image file to output artifacts:\n%w", err)
+		return fmt.Errorf("%w:\n%w", ErrArtifactImageConnection, err)
 	}
 	defer loopback.Close()
 
@@ -69,7 +92,7 @@ func outputArtifacts(ctx context.Context, items []imagecustomizerapi.OutputArtif
 	systemBootPartitionMount, err := safemount.NewMount(systemBootPartition.Path,
 		systemBootPartitionTmpDir, systemBootPartition.FileSystemType, unix.MS_RDONLY, "", true)
 	if err != nil {
-		return fmt.Errorf("failed to mount esp partition (%s):\n%w", systemBootPartition.Path, err)
+		return fmt.Errorf("%w (partition='%s'):\n%w", ErrArtifactESPPartitionMount, systemBootPartition.Path, err)
 	}
 	defer systemBootPartitionMount.Close()
 
@@ -94,7 +117,7 @@ func outputArtifacts(ctx context.Context, items []imagecustomizerapi.OutputArtif
 		ukiDir := filepath.Join(systemBootPartitionTmpDir, UkiOutputDir)
 		dirEntries, err := os.ReadDir(ukiDir)
 		if err != nil {
-			return fmt.Errorf("failed to read UKI directory (%s):\n%w", ukiDir, err)
+			return fmt.Errorf("%w (directory='%s'):\n%w", ErrArtifactUKIDirectoryRead, ukiDir, err)
 		}
 
 		for _, entry := range dirEntries {
@@ -103,7 +126,7 @@ func outputArtifacts(ctx context.Context, items []imagecustomizerapi.OutputArtif
 				destPath := filepath.Join(outputDir, entry.Name())
 				err := file.Copy(srcPath, destPath)
 				if err != nil {
-					return fmt.Errorf("failed to copy binary from (%s) to (%s):\n%w", srcPath, destPath, err)
+					return fmt.Errorf("%w (source='%s', destination='%s'):\n%w", ErrArtifactBinaryCopy, srcPath, destPath, err)
 				}
 
 				signedName := replaceSuffix(entry.Name(), ".efi", ".signed.efi")
@@ -126,7 +149,7 @@ func outputArtifacts(ctx context.Context, items []imagecustomizerapi.OutputArtif
 		destPath := filepath.Join(outputDir, bootConfig.bootBinary)
 		err := file.Copy(srcPath, destPath)
 		if err != nil {
-			return fmt.Errorf("failed to copy binary from (%s) to (%s):\n%w", srcPath, destPath, err)
+			return fmt.Errorf("%w (source='%s', destination='%s'):\n%w", ErrArtifactBinaryCopy, srcPath, destPath, err)
 		}
 
 		signedPath := "./" + replaceSuffix(bootConfig.bootBinary, ".efi", ".signed.efi")
@@ -145,7 +168,7 @@ func outputArtifacts(ctx context.Context, items []imagecustomizerapi.OutputArtif
 		destPath := filepath.Join(outputDir, bootConfig.systemdBootBinary)
 		err := file.Copy(srcPath, destPath)
 		if err != nil {
-			return fmt.Errorf("failed to copy binary from (%s) to (%s):\n%w", srcPath, destPath, err)
+			return fmt.Errorf("%w (source='%s', destination='%s'):\n%w", ErrArtifactBinaryCopy, srcPath, destPath, err)
 		}
 
 		signedPath := "./" + replaceSuffix(bootConfig.systemdBootBinary, ".efi", ".signed.efi")
@@ -169,7 +192,7 @@ func outputArtifacts(ctx context.Context, items []imagecustomizerapi.OutputArtif
 			destPath := filepath.Join(outputDir, unsignedHashFile)
 			err = file.Write(verity.rootHash, destPath)
 			if err != nil {
-				return fmt.Errorf("failed to dump root hash for (%s) to (%s):\n%w", verity.name, destPath, err)
+				return fmt.Errorf("%w (name='%s', path='%s'):\n%w", ErrArtifactRootHashDump, verity.name, destPath, err)
 			}
 
 			signedHashFile := replaceSuffix(unsignedHashFile, ".hash", ".hash.sig")
@@ -185,7 +208,7 @@ func outputArtifacts(ctx context.Context, items []imagecustomizerapi.OutputArtif
 
 	err = writeInjectFilesYaml(outputArtifactsMetadata, outputDir)
 	if err != nil {
-		return fmt.Errorf("failed to write inject-files.yaml:\n%w", err)
+		return fmt.Errorf("%w (outputDir='%s'):\n%w", ErrArtifactInjectFilesYamlWrite, outputDir, err)
 	}
 
 	err = systemBootPartitionMount.CleanClose()
@@ -216,12 +239,12 @@ func writeInjectFilesYaml(metadata []imagecustomizerapi.InjectArtifactMetadata,
 
 	yamlBytes, err := yaml.Marshal(&yamlStruct)
 	if err != nil {
-		return fmt.Errorf("failed to marshal inject files metadata: %w", err)
+		return fmt.Errorf("%w:\n%w", ErrArtifactInjectFilesYamlMarshal, err)
 	}
 
 	outputFilePath := filepath.Join(outputDir, "inject-files.yaml")
 	if err := os.WriteFile(outputFilePath, yamlBytes, 0o644); err != nil {
-		return fmt.Errorf("failed to write inject-files.yaml: %w", err)
+		return fmt.Errorf("%w (file='%s'):\n%w", ErrArtifactInjectFilesYamlWrite, outputFilePath, err)
 	}
 
 	return nil
@@ -237,14 +260,14 @@ func InjectFilesWithConfigFile(ctx context.Context, buildDir string, configFile
 	}
 
 	if err := injectConfig.IsValid(); err != nil {
-		return fmt.Errorf("invalid inject files config: %w", err)
+		return fmt.Errorf("%w:\n%w", ErrArtifactInvalidInjectFilesConfig, err)
 	}
 
 	baseConfigPath, _ := filepath.Split(configFile)
 
 	absBaseConfigPath, err := filepath.Abs(baseConfigPath)
 	if err != nil {
-		return fmt.Errorf("failed to get absolute path of inject-files.yaml:\n%w", err)
+		return fmt.Errorf("%w (path='%s'):\n%w", ErrArtifactInjectFilesPathResolution, baseConfigPath, err)
 	}
 
 	err = InjectFiles(ctx, buildDir, absBaseConfigPath, inputImageFile, injectConfig.InjectFiles,
@@ -286,7 +309,7 @@ func InjectFiles(ctx context.Context, buildDir string, baseConfigPath string, in
 
 	loopback, err := safeloopback.NewLoopback(rawImageFile)
 	if err != nil {
-		return fmt.Errorf("failed to connect to image file to inject files:\n%w", err)
+		return fmt.Errorf("%w:\n%w", ErrArtifactInjectFilesImageConnection, err)
 	}
 	defer loopback.Close()
 
@@ -310,7 +333,7 @@ func InjectFiles(ctx context.Context, buildDir string, baseConfigPath string, in
 
 			mount, err := safemount.NewMount(partition.Path, partitionsToMountpoints[partitionKey], partition.FileSystemType, 0, "", true)
 			if err != nil {
-				return fmt.Errorf("failed to mount partition (%s):\n%w", partition.Path, err)
+				return fmt.Errorf("%w (partition='%s'):\n%w", ErrArtifactInjectFilesPartitionMount, partition.Path, err)
 			}
 			defer mount.Close()
 
@@ -321,13 +344,13 @@ func InjectFiles(ctx context.Context, buildDir string, baseConfigPath string, in
 		destPath := filepath.Join(partitionsToMountpoints[partitionKey], item.Destination)
 		err := file.Copy(srcPath, destPath)
 		if err != nil {
-			return fmt.Errorf("failed to copy binary from (%s) to (%s):\n%w", srcPath, destPath, err)
+			return fmt.Errorf("%w (source='%s', destination='%s'):\n%w", ErrArtifactBinaryCopy, srcPath, destPath, err)
 		}
 	}
 
 	for _, m := range mountedPartitions {
 		if err := m.CleanClose(); err != nil {
-			return fmt.Errorf("failed to cleanly unmount (%s):\n%w", m.Target(), err)
+			return fmt.Errorf("%w (target='%s'):\n%w", ErrArtifactPartitionUnmount, m.Target(), err)
 		}
 	}
 
@@ -345,12 +368,12 @@ func InjectFiles(ctx context.Context, buildDir string, baseConfigPath string, in
 		err = convertToCosi(buildDirAbs, rawImageFile, outputImageFile, partUuidToFstabEntry,
 			baseImageVerityMetadata, osRelease, osPackages, imageUuid, imageUuidStr, cosiBootMetadata)
 		if err != nil {
-			return fmt.Errorf("failed to convert customized raw image to cosi output format:\n%w", err)
+			return fmt.Errorf("%w (output='%s'):\n%w", ErrArtifactCosiImageConversion, outputImageFile, err)
 		}
 	} else {
 		err = ConvertImageFile(rawImageFile, outputImageFile, detectedImageFormat)
 		if err != nil {
-			return fmt.Errorf("failed to convert customized raw image to output format:\n%w", err)
+			return fmt.Errorf("%w (output='%s', format='%s'):\n%w", ErrArtifactOutputImageConversion, outputImageFile, detectedImageFormat, err)
 		}
 	}
 
@@ -367,7 +390,7 @@ func prepareImageConversionData(ctx context.Context, rawImageFile string, buildD
 	imageConnection, partUuidToFstabEntry, baseImageVerityMetadata, _, err := connectToExistingImage(ctx,
 		rawImageFile, buildDir, chrootDir, true, true, false)
 	if err != nil {
-		return nil, nil, "", nil, [randomization.UuidSize]byte{}, "", nil, fmt.Errorf("failed to connect to image:\n%w", err)
+		return nil, nil, "", nil, [randomization.UuidSize]byte{}, "", nil, fmt.Errorf("%w:\n%w", ErrArtifactImageConnectionForExtraction, err)
 	}
 	defer imageConnection.Close()
 
@@ -387,7 +410,7 @@ func prepareImageConversionData(ctx context.Context, rawImageFile string, buildD
 	}
 
 	if err := imageConnection.CleanClose(); err != nil {
-		return nil, nil, "", nil, [randomization.UuidSize]byte{}, "", nil, fmt.Errorf("failed to cleanly close image connection:\n%w", err)
+		return nil, nil, "", nil, [randomization.UuidSize]byte{}, "", nil, fmt.Errorf("%w:\n%w", ErrArtifactImageConnectionClose, err)
 	}
 
 	return partUuidToFstabEntry, baseImageVerityMetadata, osRelease, osPackages, imageUuid, imageUuidStr, cosiBootMetadata, nil
@@ -399,22 +422,22 @@ func extractImageUUID(imageConnection *imageconnection.ImageConnection) ([random
 	releasePath := filepath.Join(imageConnection.Chroot().RootDir(), ImageCustomizerReleasePath)
 	data, err := file.Read(releasePath)
 	if err != nil {
-		return emptyUuid, "", fmt.Errorf("failed to read %s:\n%w", releasePath, err)
+		return emptyUuid, "", fmt.Errorf("%w (path='%s'):\n%w", ErrArtifactReleaseFileRead, releasePath, err)
 	}
 
 	lines := strings.Split(string(data), "\n")
 	line, found := sliceutils.FindValueFunc(lines, func(line string) bool {
 		return strings.HasPrefix(line, "IMAGE_UUID=")
 	})
 	if !found {
-		return emptyUuid, "", fmt.Errorf("IMAGE_UUID not found in %s", releasePath)
+		return emptyUuid, "", fmt.Errorf("%w (path='%s')", ErrArtifactImageUuidNotFound, releasePath)
 	}
 
 	uuidStr := strings.Trim(strings.TrimPrefix(line, "IMAGE_UUID="), `"`)
 
 	parsed, err := randomization.ParseUuidString(uuidStr)
 	if err != nil {
-		return emptyUuid, "", fmt.Errorf("failed to parse IMAGE_UUID (%s):\n%w", uuidStr, err)
+		return emptyUuid, "", fmt.Errorf("%w (IMAGE_UUID='%s'):\n%w", ErrArtifactImageUuidParse, uuidStr, err)
 	}
 
 	return parsed, uuidStr, nil

toolkit/tools/pkg/imagecustomizerlib/bootcustomizer.go

@@ -11,6 +11,11 @@ import (
 	"github.com/microsoft/azurelinux/toolkit/tools/internal/safechroot"
 )
 
+var (
+	// Boot customization errors
+	ErrBootGrubMkconfigGeneration = NewImageCustomizerError("Boot:GrubMkconfigGeneration", "failed to generate grub.cfg via grub2-mkconfig")
+)
+
 type BootCustomizer struct {
 	// The contents of the /boot/grub2/grub.cfg file.
 	grubCfgContent string
@@ -208,7 +213,7 @@ func (b *BootCustomizer) WriteToFile(imageChroot safechroot.ChrootInterface) err
 		// Update /boot/grub2/grub.cfg file.
 		err = installutils.CallGrubMkconfig(imageChroot)
 		if err != nil {
-			return fmt.Errorf("failed to generate grub.cfg via grub2-mkconfig:\n%w", err)
+			return fmt.Errorf("%w:\n%w", ErrBootGrubMkconfigGeneration, err)
 		}
 	} else {
 		// Update grub.cfg file.

toolkit/tools/pkg/imagecustomizerlib/checkfilesystem.go

@@ -15,6 +15,13 @@ import (
 	"go.opentelemetry.io/otel"
 )
 
+var (
+	// Filesystem check errors
+	ErrFilesystemE2fsckCheck    = NewImageCustomizerError("FilesystemCheck:E2fsck", "failed to check filesystem with e2fsck")
+	ErrFilesystemXfsRepairCheck = NewImageCustomizerError("FilesystemCheck:XfsRepair", "failed to check filesystem with xfs_repair")
+	ErrFilesystemFsckCheck      = NewImageCustomizerError("FilesystemCheck:Fsck", "failed to check filesystem with fsck")
+)
+
 func checkFileSystems(ctx context.Context, rawImageFile string) error {
 	logger.Log.Infof("Checking for file system errors")
 
@@ -108,21 +115,20 @@ func checkFileSystem(fileSystemType string, path string) error {
 		// Add -f flag to force check to run even if the journal is marked as clean.
 		err := shell.ExecuteLive(true /*squashErrors*/, "e2fsck", "-fn", path)
 		if err != nil {
-			return fmt.Errorf("failed to check (%s) with e2fsck:\n%w", path, err)
-
+			return fmt.Errorf("%w (path='%s'):\n%w", ErrFilesystemE2fsckCheck, path, err)
 		}
 
 	case "xfs":
 		// The fsck.xfs tool doesn't do anything. So, call xfs_repair instead.
 		err := shell.ExecuteLive(true /*squashErrors*/, "xfs_repair", "-n", path)
 		if err != nil {
-			return fmt.Errorf("failed to check (%s) with xfs_repair:\n%w", path, err)
+			return fmt.Errorf("%w (path='%s'):\n%w", ErrFilesystemXfsRepairCheck, path, err)
 		}
 
 	default:
 		err := shell.ExecuteLive(true /*squashErrors*/, "fsck", "-n", path)
 		if err != nil {
-			return fmt.Errorf("failed to check (%s) with fsck:\n%w", path, err)
+			return fmt.Errorf("%w (path='%s'):\n%w", ErrFilesystemFsckCheck, path, err)
 		}
 	}