Improve logging in DockerApi

This commit introduces a new constructor in `DockerApi`
that accepts `DockerLogger` as a parameter.

The `DockerLogger` is a pretty simple callback interface used to
provide DockerApi output logging.

See gh-43460

Signed-off-by: Dmytro Nosan <[email protected]>

Author: nosan

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/build/Builder.java

@@ -21,6 +21,7 @@
 import java.util.function.Consumer;
 
 import org.springframework.boot.buildpack.platform.docker.DockerApi;
+import org.springframework.boot.buildpack.platform.docker.DockerLogger;
 import org.springframework.boot.buildpack.platform.docker.TotalProgressEvent;
 import org.springframework.boot.buildpack.platform.docker.TotalProgressPullListener;
 import org.springframework.boot.buildpack.platform.docker.TotalProgressPushListener;
@@ -89,6 +90,19 @@ public Builder(BuildLog log, DockerConfiguration dockerConfiguration) {
 				dockerConfiguration);
 	}
 
+	/**
+	 * Create a new builder instance.
+	 * @param buildLog a logger used to record {@link Builder} output
+	 * @param dockerLogger a logger used to record {@link DockerApi} output
+	 * @param dockerConfiguration the docker configuration
+	 * @since 3.5.0
+	 */
+	public Builder(BuildLog buildLog, DockerLogger dockerLogger, DockerConfiguration dockerConfiguration) {
+		this(buildLog,
+				new DockerApi((dockerConfiguration != null) ? dockerConfiguration.getHost() : null, dockerLogger),
+				dockerConfiguration);
+	}
+
 	Builder(BuildLog log, DockerApi docker, DockerConfiguration dockerConfiguration) {
 		Assert.notNull(log, "'log' must not be null");
 		this.log = log;

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/DockerApi.java

@@ -87,7 +87,7 @@ public class DockerApi {
 	 * Create a new {@link DockerApi} instance.
 	 */
 	public DockerApi() {
-		this(HttpTransport.create(null));
+		this(HttpTransport.create(null), DockerLogger.toSystemOut());
 	}
 
 	/**
@@ -96,21 +96,34 @@ public DockerApi() {
 	 * @since 2.4.0
 	 */
 	public DockerApi(DockerHostConfiguration dockerHost) {
-		this(HttpTransport.create(dockerHost));
+		this(HttpTransport.create(dockerHost), DockerLogger.toSystemOut());
+	}
+
+	/**
+	 * Create a new {@link DockerApi} instance.
+	 * @param dockerHost the Docker daemon host information
+	 * @param logger a logger used to record output
+	 * @since 3.5.0
+	 */
+	public DockerApi(DockerHostConfiguration dockerHost, DockerLogger logger) {
+		this(HttpTransport.create(dockerHost), logger);
 	}
 
 	/**
 	 * Create a new {@link DockerApi} instance backed by a specific {@link HttpTransport}
 	 * implementation.
 	 * @param http the http implementation
+	 * @param logger a logger used to record output
 	 */
-	DockerApi(HttpTransport http) {
+	DockerApi(HttpTransport http, DockerLogger logger) {
+		Assert.notNull(http, "'http' must not be null");
+		Assert.notNull(logger, "'logger' must not be null");
 		this.http = http;
 		this.jsonStream = new JsonStream(SharedObjectMapper.get());
 		this.image = new ImageApi();
 		this.container = new ContainerApi();
 		this.volume = new VolumeApi();
-		this.system = new SystemApi();
+		this.system = new SystemApi(logger);
 	}
 
 	private HttpTransport http() {
@@ -485,7 +498,10 @@ public void delete(VolumeName name, boolean force) throws IOException {
 	 */
 	class SystemApi {
 
-		SystemApi() {
+		private final DockerLogger logger;
+
+		SystemApi(DockerLogger logger) {
+			this.logger = logger;
 		}
 
 		/**
@@ -502,6 +518,7 @@ ApiVersion getApiVersion() {
 					}
 				}
 				catch (Exception ex) {
+					this.logger.log("Warning: Failed to determine Docker API version: " + ex.getMessage());
 					// fall through to return default value
 				}
 				return UNKNOWN_API_VERSION;

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/DockerLogger.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2012-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.buildpack.platform.docker;
+
+import java.io.PrintStream;
+
+/**
+ * Callback interface used to provide {@link DockerApi} output logging.
+ *
+ * @author Dmytro Nosan
+ * @since 3.5.0
+ * @see #toSystemOut()
+ */
+public interface DockerLogger {
+
+	/**
+	 * Logs a given message.
+	 * @param message the message to log
+	 */
+	void log(String message);
+
+	/**
+	 * Factory method that returns a {@link DockerLogger} the outputs to
+	 * {@link System#out}.
+	 * @return {@link DockerLogger} instance that logs to system out
+	 */
+	static DockerLogger toSystemOut() {
+		return to(System.out);
+	}
+
+	/**
+	 * Factory method that returns a {@link DockerLogger} the outputs to a given
+	 * {@link PrintStream}.
+	 * @param out the print stream used to output the log
+	 * @return {@link DockerLogger} instance that logs to the given print stream
+	 */
+	static DockerLogger to(PrintStream out) {
+		return new PrintStreamDockerLogger(out);
+	}
+
+}

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/PrintStreamDockerLogger.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2012-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.buildpack.platform.docker;
+
+import java.io.PrintStream;
+
+import org.springframework.util.Assert;
+
+/**
+ * {@link DockerLogger} implementation that prints output to a {@link PrintStream}.
+ *
+ * @author Dmytro Nosan
+ */
+class PrintStreamDockerLogger implements DockerLogger {
+
+	private final PrintStream stream;
+
+	PrintStreamDockerLogger(PrintStream stream) {
+		Assert.notNull(stream, "'stream' must not be null");
+		this.stream = stream;
+	}
+
+	@Override
+	public void log(String message) {
+		this.stream.println(message);
+	}
+
+}

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/test/java/org/springframework/boot/buildpack/platform/docker/DockerApiTests.java

@@ -59,6 +59,8 @@
 import org.springframework.boot.buildpack.platform.io.IOConsumer;
 import org.springframework.boot.buildpack.platform.io.Owner;
 import org.springframework.boot.buildpack.platform.io.TarArchive;
+import org.springframework.boot.testsupport.system.CapturedOutput;
+import org.springframework.boot.testsupport.system.OutputCaptureExtension;
 import org.springframework.util.LinkedMultiValueMap;
 import org.springframework.util.MultiValueMap;
 
@@ -82,7 +84,7 @@
  * @author Rafael Ceccone
  * @author Moritz Halbritter
  */
-@ExtendWith(MockitoExtension.class)
+@ExtendWith({ MockitoExtension.class, OutputCaptureExtension.class })
 class DockerApiTests {
 
 	private static final String API_URL = "/v" + DockerApi.API_VERSION;
@@ -108,7 +110,7 @@ class DockerApiTests {
 
 	@BeforeEach
 	void setup() {
-		this.dockerApi = new DockerApi(this.http);
+		this.dockerApi = new DockerApi(this.http, DockerLogger.toSystemOut());
 	}
 
 	private HttpTransport http() {
@@ -732,9 +734,10 @@ void getApiVersionWithNoVersionHeaderReturnsUnknownVersion() throws Exception {
 		}
 
 		@Test
-		void getApiVersionWithExceptionReturnsUnknownVersion() throws Exception {
+		void getApiVersionWithExceptionReturnsUnknownVersion(CapturedOutput output) throws Exception {
 			given(http().head(eq(new URI(PING_URL)))).willThrow(new IOException("simulated error"));
 			assertThat(this.api.getApiVersion()).isEqualTo(DockerApi.UNKNOWN_API_VERSION);
+			assertThat(output).contains("Warning: Failed to determine Docker API version: simulated error");
 		}
 
 	}

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/test/java/org/springframework/boot/buildpack/platform/docker/DockerLoggerTests.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2012-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.buildpack.platform.docker;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import org.springframework.boot.testsupport.system.CapturedOutput;
+import org.springframework.boot.testsupport.system.OutputCaptureExtension;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Tests for {@link DockerLogger}.
+ *
+ * @author Dmytro nosan
+ */
+@ExtendWith(OutputCaptureExtension.class)
+class DockerLoggerTests {
+
+	@Test
+	void toSystemOutPrintsToSystemOut(CapturedOutput output) {
+		DockerLogger logger = DockerLogger.toSystemOut();
+		logger.log("Hello world");
+		assertThat(output.getErr()).isEmpty();
+		assertThat(output.getOut()).contains("Hello world");
+	}
+
+	@Test
+	void toPrintsToOutput(CapturedOutput output) {
+		DockerLogger logger = DockerLogger.to(System.err);
+		logger.log("Hello world");
+		assertThat(output.getOut()).isEmpty();
+		assertThat(output.getErr()).contains("Hello world");
+	}
+
+}

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/test/java/org/springframework/boot/buildpack/platform/docker/PrintStreamDockerLoggerTests.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2012-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.buildpack.platform.docker;
+
+import java.io.ByteArrayOutputStream;
+import java.io.PrintStream;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Tests for {@link PrintStreamDockerLogger}.
+ *
+ * @author Dmytro Nosan
+ */
+class PrintStreamDockerLoggerTests {
+
+	@Test
+	void printsExpectedOutput() {
+		TestPrintStream stream = new TestPrintStream();
+		PrintStreamDockerLogger logger = new PrintStreamDockerLogger(stream);
+		logger.log("Some message");
+		logger.log("Some message1");
+		assertThat(stream.toString()).isEqualTo(String.format("Some message%nSome message1%n"));
+	}
+
+	static class TestPrintStream extends PrintStream {
+
+		TestPrintStream() {
+			super(new ByteArrayOutputStream());
+		}
+
+		@Override
+		public String toString() {
+			return this.out.toString();
+		}
+
+	}
+
+}

spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/BuildImageMojo.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2024 the original author or authors.
+ * Copyright 2012-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -40,6 +40,7 @@
 import org.springframework.boot.buildpack.platform.build.Builder;
 import org.springframework.boot.buildpack.platform.build.Creator;
 import org.springframework.boot.buildpack.platform.build.PullPolicy;
+import org.springframework.boot.buildpack.platform.docker.DockerLogger;
 import org.springframework.boot.buildpack.platform.docker.TotalProgressEvent;
 import org.springframework.boot.buildpack.platform.docker.configuration.DockerConfiguration;
 import org.springframework.boot.buildpack.platform.io.Owner;
@@ -265,7 +266,8 @@ private void buildImage() throws MojoExecutionException {
 			DockerConfiguration dockerConfiguration = (this.docker != null)
 					? this.docker.asDockerConfiguration(request.isPublish())
 					: new Docker().asDockerConfiguration(request.isPublish());
-			Builder builder = new Builder(new MojoBuildLog(this::getLog), dockerConfiguration);
+			Builder builder = new Builder(new MojoBuildLog(this::getLog), new MojoDockerLogger(this::getLog),
+					dockerConfiguration);
 			builder.build(request);
 		}
 		catch (IOException ex) {
@@ -364,6 +366,21 @@ private BuildRequest customizeCreator(BuildRequest request) {
 		return request;
 	}
 
+	private static class MojoDockerLogger implements DockerLogger {
+
+		private final Supplier<Log> log;
+
+		MojoDockerLogger(Supplier<Log> log) {
+			this.log = log;
+		}
+
+		@Override
+		public void log(String message) {
+			this.log.get().info(message);
+		}
+
+	}
+
 	/**
 	 * {@link BuildLog} backed by Mojo logging.
 	 */