Error Handling and Logging

Overview

The Docker CLI uses a comprehensive approach to handle errors, log messages, and provide informative feedback to users. This involves leveraging packages like debug, errors, and logs to ensure consistency and clarity.

Error Handling

Error Types

Docker CLI utilizes a custom error type called docker.Error defined in the errors package tree/master/cli/errors. This error type is used for all CLI-related errors, providing a structured way to handle and report them.

Error Propagation and Handling

Errors are propagated using the errors.Wrap function cli/errors/errors.go#L14. This function adds context to the original error, helping to track the error’s origin and simplify debugging. The errors.Wrap function provides a way to attach contextual information to the original error, making it easier to understand the error’s cause during debugging.

Example

package main
          
          import (
              "fmt"
              "github.com/docker/cli/cli/errors"
          )
          
          func main() {
              err := fmt.Errorf("some error occurred")
              wrappedErr := errors.Wrap(err, "error occurred while performing operation")
              fmt.Println(wrappedErr) // Output: error occurred while performing operation: some error occurred
          }
          

Logging

Log Levels

The Docker CLI utilizes the logs package tree/master/cli/logs for managing log levels. These levels include:

• Debug: Used for detailed information that helps in debugging.
• Info: Provides general information about the CLI’s operation.
• Warn: Used for warnings and potential issues.
• Error: Logs errors encountered during execution.
• Fatal: Used for critical errors that result in application termination.

Logging Configuration

The log level can be configured using the DOCKER_LOG_LEVEL environment variable. This allows for customization of the logging verbosity based on the needs of the user.

Example

package main
          
          import (
              "fmt"
              "github.com/docker/cli/cli/logs"
          )
          
          func main() {
              // Set log level to debug
              logs.SetLevel(logs.Debug)
          
              // Log a debug message
              logs.Debugf("Debug message: %s", "This is a debug message")
          
              // Log an error message
              logs.Errorf("Error message: %s", "This is an error message")
          }
          

Debugging

The debug package tree/master/cli/debug provides functionality for enabling and disabling debug logging. This allows developers to access detailed information during development and troubleshooting.

Example

package main
          
          import (
              "github.com/docker/cli/cli/debug"
          )
          
          func main() {
              // Enable debug logging
              debug.Enable("my-debug-module")
          
              // Log a debug message
              debug.Debugf("My debug message: %s", "This is a debug message")
          }
          

User Feedback

Error Messages

The Docker CLI aims to provide user-friendly error messages, ensuring that users can understand the problem and take appropriate action. Error messages are designed to be clear, concise, and informative, offering potential solutions or guidance for resolving the issue.

Output Formatting

Output formatting is consistent throughout the CLI, providing a cohesive and readable experience for users.

Example

Error response from daemon: Cannot start container f3606109e3b3: driver failed programming external connectivity on endpoint f3606109e3b3 for network "bridge": Error starting userland proxy: listen tcp 0.0.0.0:32769: bind: address already in use