chore(log): fix debug/verbose logging flags

cmd/compatibility/convert.go

@@ -32,8 +32,7 @@ func getCompletionCommands() []string {
 
 func getBoolFlags() []string {
 	return []string{
-		"--debug", "-D",
-		"--verbose",
+		"-D",
 		"--tls",
 		"--tlsverify",
 	}
@@ -50,7 +49,8 @@ func getStringFlags() []string {
 	}
 }
 
-// Convert transforms standalone docker-compose args into CLI plugin compliant ones
+// Convert transforms v1 args into v2 ones and is used when the binary is
+// invoked standalone, i.e. as `docker-compose`.
 func Convert(args []string) []string {
 	var rootFlags []string
 	command := []string{compose.PluginName}
@@ -67,8 +67,6 @@ func Convert(args []string) []string {
 		}
 
 		switch arg {
-		case "--verbose":
-			arg = "--debug"
 		case "-h":
 			// docker cli has deprecated -h to avoid ambiguity with -H, while docker-compose still support it
 			arg = "--help"

cmd/compatibility/convert_test.go

@@ -46,7 +46,7 @@ func Test_convert(t *testing.T) {
 		{
 			name: "compose --verbose",
 			args: []string{"--verbose"},
-			want: []string{"--debug", "compose"},
+			want: []string{"compose", "--verbose"},
 		},
 		{
 			name: "compose --version",

cmd/compose/compose.go

@@ -32,7 +32,6 @@ import (
 	"github.com/compose-spec/compose-go/v2/loader"
 	"github.com/compose-spec/compose-go/v2/types"
 	composegoutils "github.com/compose-spec/compose-go/v2/utils"
-	"github.com/docker/buildx/util/logutil"
 	dockercli "github.com/docker/cli/cli"
 	"github.com/docker/cli/cli-plugins/manager"
 	"github.com/docker/cli/cli/command"
@@ -45,7 +44,6 @@ import (
 	"github.com/docker/compose/v2/pkg/utils"
 	buildkit "github.com/moby/buildkit/util/progress/progressui"
 	"github.com/morikuni/aec"
-	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
@@ -325,17 +323,7 @@ func RunningAsStandalone() bool {
 }
 
 // RootCommand returns the compose command with its child commands
-func RootCommand(dockerCli command.Cli, backend api.Service) *cobra.Command { //nolint:gocyclo
-	// filter out useless commandConn.CloseWrite warning message that can occur
-	// when using a remote context that is unreachable: "commandConn.CloseWrite: commandconn: failed to wait: signal: killed"
-	// https://github.com/docker/cli/blob/e1f24d3c93df6752d3c27c8d61d18260f141310c/cli/connhelper/commandconn/commandconn.go#L203-L215
-	logrus.AddHook(logutil.NewFilter([]logrus.Level{
-		logrus.WarnLevel,
-	},
-		"commandConn.CloseWrite:",
-		"commandConn.CloseRead:",
-	))
-
+func RootCommand(dockerCli command.Cli, backend api.Service, debugFlagValue *bool) *cobra.Command { //nolint:gocyclo
 	opts := ProjectOptions{}
 	var (
 		ansi     string
@@ -386,9 +374,6 @@ func RootCommand(dockerCli command.Cli, backend api.Service) *cobra.Command { //
 				ansi = "never"
 				fmt.Fprint(os.Stderr, "option '--no-ansi' is DEPRECATED ! Please use '--ansi' instead.\n")
 			}
-			if verbose {
-				logrus.SetLevel(logrus.TraceLevel)
-			}
 
 			if v, ok := os.LookupEnv("COMPOSE_ANSI"); ok && !cmd.Flags().Changed("ansi") {
 				ansi = v
@@ -534,15 +519,25 @@ func RootCommand(dockerCli command.Cli, backend api.Service) *cobra.Command { //
 		completeProfileNames(dockerCli, &opts),
 	)
 
-	c.Flags().StringVar(&ansi, "ansi", "auto", `Control when to print ANSI control characters ("never"|"always"|"auto")`)
+	// persistent flags are available on all subcommands: they're global,
+	// which is _mostly_ a convenience so that `compose --verbose foo` and
+	// `compose foo --verbose` both work. (otherwise, the latter triggers a
+	// parse error from Cobra)
+	c.PersistentFlags().BoolVar(&verbose, "verbose", false, "Show debugging logging output")
+	// TODO(milas): we aren't actually using verbose for anything right now,
+	// 	it's here for compatibility but also we should start using it for more
+	// 	detailed user-facing output.
+	_ = c.PersistentFlags().MarkHidden("verbose")
+	c.PersistentFlags().BoolVar(debugFlagValue, "debug", false, "Show debugging logging output for development or troubleshooting")
+	_ = c.PersistentFlags().MarkHidden("debug")
+	c.PersistentFlags().BoolVar(&dryRun, "dry-run", false, "Execute command in dry run mode")
+	c.PersistentFlags().StringVar(&ansi, "ansi", "auto", `Control when to print ANSI control characters ("never"|"always"|"auto")`)
+
 	c.Flags().IntVar(&parallel, "parallel", -1, `Control max parallelism, -1 for unlimited`)
 	c.Flags().BoolVarP(&version, "version", "v", false, "Show the Docker Compose version information")
-	c.PersistentFlags().BoolVar(&dryRun, "dry-run", false, "Execute command in dry run mode")
-	c.Flags().MarkHidden("version") //nolint:errcheck
+	_ = c.Flags().MarkHidden("version")
 	c.Flags().BoolVar(&noAnsi, "no-ansi", false, `Do not print ANSI control characters (DEPRECATED)`)
-	c.Flags().MarkHidden("no-ansi") //nolint:errcheck
-	c.Flags().BoolVar(&verbose, "verbose", false, "Show more output")
-	c.Flags().MarkHidden("verbose") //nolint:errcheck
+	_ = c.Flags().MarkHidden("no-ansi")
 	return c
 }
 

cmd/main.go

@@ -19,12 +19,14 @@ package main
 import (
 	"os"
 
+	"github.com/docker/buildx/util/logutil"
 	dockercli "github.com/docker/cli/cli"
 	"github.com/docker/cli/cli-plugins/manager"
 	"github.com/docker/cli/cli-plugins/plugin"
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/compose/v2/cmd/cmdtrace"
 	"github.com/docker/docker/client"
+	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 
 	"github.com/docker/compose/v2/cmd/compatibility"
@@ -36,7 +38,10 @@ import (
 func pluginMain() {
 	plugin.Run(func(dockerCli command.Cli) *cobra.Command {
 		backend := compose.NewComposeService(dockerCli)
-		cmd := commands.RootCommand(dockerCli, backend)
+		// to initialize logging as early as possible, a pointer to this value
+		// is passed to the root command, which registers it as a Cobra flag.
+		var debugLogging bool
+		cmd := commands.RootCommand(dockerCli, backend, &debugLogging)
 		originalPreRun := cmd.PersistentPreRunE
 		cmd.PersistentPreRunE = func(cmd *cobra.Command, args []string) error {
 			// initialize the dockerCli instance
@@ -46,9 +51,15 @@ func pluginMain() {
 			// compose-specific initialization
 			dockerCliPostInitialize(dockerCli)
 
-			// TODO(milas): add an env var to enable logging from the
-			// OTel components for debugging purposes
-			_ = cmdtrace.Setup(cmd, dockerCli, os.Args[1:])
+			// this is the earliest logging can be configured:
+			// 	1. need the value set by the flag parsing
+			// 	2. initializing the Docker CLI via the parent PersistentPreRun
+			// 		also sets the global logrus level
+			configureLogging(debugLogging)
+
+			if err := cmdtrace.Setup(cmd, dockerCli, os.Args[1:]); err != nil {
+				logrus.Debugf("failed to enable tracing: %v", err)
+			}
 
 			if originalPreRun != nil {
 				return originalPreRun(cmd, args)
@@ -87,6 +98,21 @@ func dockerCliPostInitialize(dockerCli command.Cli) {
 	})
 }
 
+func configureLogging(debug bool) {
+	// filter out useless commandConn.CloseWrite warning message that can occur
+	// when using a remote context that is unreachable: "commandConn.CloseWrite: commandconn: failed to wait: signal: killed"
+	// https://github.com/docker/cli/blob/e1f24d3c93df6752d3c27c8d61d18260f141310c/cli/connhelper/commandconn/commandconn.go#L203-L215
+	logrus.AddHook(logutil.NewFilter([]logrus.Level{
+		logrus.WarnLevel,
+	},
+		"commandConn.CloseWrite:",
+		"commandConn.CloseRead:",
+	))
+	if debug {
+		logrus.SetLevel(logrus.TraceLevel)
+	}
+}
+
 func main() {
 	if plugin.RunningStandalone() {
 		os.Args = append([]string{"docker"}, compatibility.Convert(os.Args[1:])...)

docs/yaml/main/generate.go

@@ -36,7 +36,8 @@ func generateDocs(opts *options) error {
 		Use:               "docker",
 		DisableAutoGenTag: true,
 	}
-	cmd.AddCommand(compose.RootCommand(dockerCLI, nil))
+	var debugLogging bool
+	cmd.AddCommand(compose.RootCommand(dockerCLI, nil, &debugLogging))
 	disableFlagsInUseLine(cmd)
 
 	tool, err := clidocstool.New(clidocstool.Options{