history: make sure build record is finalized before exporting

Signed-off-by: CrazyMax <[email protected]>

Author: crazy-max

commands/history/export.go

@@ -20,10 +20,11 @@ import (
 )
 
 type exportOptions struct {
-	builder string
-	refs    []string
-	output  string
-	all     bool
+	builder  string
+	refs     []string
+	output   string
+	all      bool
+	finalize bool
 }
 
 func runExport(ctx context.Context, dockerCli command.Cli, opts exportOptions) error {
@@ -62,6 +63,25 @@ func runExport(ctx context.Context, dockerCli command.Cli, opts exportOptions) e
 			return errors.Errorf("no record found for ref %q", ref)
 		}
 
+		if opts.finalize {
+			var finalize bool
+			for _, rec := range recs {
+				if rec.Trace == nil {
+					finalize = true
+					break
+				}
+			}
+			if finalize {
+				recs, err = queryRecords(ctx, ref, nodes, &queryOptions{
+					CompletedOnly: true,
+					Finalize:      true,
+				})
+				if err != nil {
+					return err
+				}
+			}
+		}
+
 		if ref == "" {
 			slices.SortFunc(recs, func(a, b historyRecord) int {
 				return b.CreatedAt.AsTime().Compare(a.CreatedAt.AsTime())
@@ -154,7 +174,8 @@ func exportCmd(dockerCli command.Cli, rootOpts RootOptions) *cobra.Command {
 
 	flags := cmd.Flags()
 	flags.StringVarP(&options.output, "output", "o", "", "Output file path")
-	flags.BoolVar(&options.all, "all", false, "Export all records for the builder")
+	flags.BoolVar(&options.all, "all", false, "Export all build records for the builder")
+	flags.BoolVar(&options.finalize, "finalize", false, "Ensure build records are finalized before exporting")
 
 	return cmd
 }

commands/history/trace.go

@@ -17,7 +17,6 @@ import (
 	"github.com/docker/buildx/util/otelutil"
 	"github.com/docker/buildx/util/otelutil/jaeger"
 	"github.com/docker/cli/cli/command"
-	controlapi "github.com/moby/buildkit/api/services/control"
 	"github.com/opencontainers/go-digest"
 	ocispecs "github.com/opencontainers/image-spec/specs-go/v1"
 	"github.com/pkg/browser"
@@ -57,20 +56,9 @@ func loadTrace(ctx context.Context, ref string, nodes []builder.Node) (string, [
 		// build is complete but no trace yet. try to finalize the trace
 		time.Sleep(1 * time.Second) // give some extra time for last parts of trace to be written
 
-		c, err := rec.node.Driver.Client(ctx)
-		if err != nil {
-			return "", nil, err
-		}
-		_, err = c.ControlClient().UpdateBuildHistory(ctx, &controlapi.UpdateBuildHistoryRequest{
-			Ref:      rec.Ref,
-			Finalize: true,
-		})
-		if err != nil {
-			return "", nil, err
-		}
-
 		recs, err := queryRecords(ctx, rec.Ref, []builder.Node{*rec.node}, &queryOptions{
 			CompletedOnly: true,
+			Finalize:      true,
 		})
 		if err != nil {
 			return "", nil, err

commands/history/utils.go

@@ -116,6 +116,7 @@ type historyRecord struct {
 type queryOptions struct {
 	CompletedOnly bool
 	Filters       []string
+	Finalize      bool
 }
 
 func queryRecords(ctx context.Context, ref string, nodes []builder.Node, opts *queryOptions) ([]historyRecord, error) {
@@ -163,6 +164,15 @@ func queryRecords(ctx context.Context, ref string, nodes []builder.Node, opts *q
 				filters = []string{strings.TrimSuffix(sb.String(), "\n")}
 			}
 
+			if opts.Finalize {
+				if _, err := c.ControlClient().UpdateBuildHistory(ctx, &controlapi.UpdateBuildHistoryRequest{
+					Ref:      ref,
+					Finalize: true,
+				}); err != nil {
+					return err
+				}
+			}
+
 			serv, err := c.ControlClient().ListenBuildHistory(ctx, &controlapi.BuildHistoryRequest{
 				EarlyExit: true,
 				Ref:       ref,

docs/reference/buildx_history_export.md

@@ -5,12 +5,13 @@ Export a build into Docker Desktop bundle
 
 ### Options
 
-| Name                                   | Type     | Default | Description                              |
-|:---------------------------------------|:---------|:--------|:-----------------------------------------|
-| [`--all`](#all)                        | `bool`   |         | Export all records for the builder       |
-| [`--builder`](#builder)                | `string` |         | Override the configured builder instance |
-| [`-D`](#debug), [`--debug`](#debug)    | `bool`   |         | Enable debug logging                     |
-| [`-o`](#output), [`--output`](#output) | `string` |         | Output file path                         |
+| Name                                   | Type     | Default | Description                                         |
+|:---------------------------------------|:---------|:--------|:----------------------------------------------------|
+| [`--all`](#all)                        | `bool`   |         | Export all build records for the builder            |
+| [`--builder`](#builder)                | `string` |         | Override the configured builder instance            |
+| [`-D`](#debug), [`--debug`](#debug)    | `bool`   |         | Enable debug logging                                |
+| [`--finalize`](#finalize)              | `bool`   |         | Ensure build records are finalized before exporting |
+| [`-o`](#output), [`--output`](#output) | `string` |         | Output file path                                    |
 
 
 <!---MARKER_GEN_END-->
@@ -23,59 +24,68 @@ Desktop or shared across environments.
 
 ## Examples
 
-### <a name="output"></a> Export a single build to a custom file (--output)
+### <a name="all"></a> Export all build records to a file (--all)
+
+Use the `--all` flag and redirect the output:
 
 ```console
-docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output mybuild.dockerbuild
+docker buildx history export --all > all-builds.dockerbuild
 ```
 
-You can find build IDs by running:
+Or use the `--output` flag:
 
 ```console
-docker buildx history ls
+docker buildx history export --all -o all-builds.dockerbuild
 ```
 
-### <a name="o"></a> Export multiple builds to individual `.dockerbuild` files (-o)
-
-To export two builds to separate files:
+### <a name="builder"></a> Use a specific builder instance (--builder)
 
 ```console
-# Using build IDs
-docker buildx history export qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3 -o multi.dockerbuild
-
-# Or using relative offsets
-docker buildx history export ^1 ^2 -o multi.dockerbuild
+docker buildx history export --builder builder0 ^1 -o builder0-build.dockerbuild
 ```
 
-Or use shell redirection:
+### <a name="debug"></a> Enable debug logging (--debug)
 
 ```console
-docker buildx history export ^1 > mybuild.dockerbuild
-docker buildx history export ^2 > backend-build.dockerbuild
+docker buildx history export --debug qu2gsuo8ejqrwdfii23xkkckt -o debug-build.dockerbuild
 ```
 
-### <a name="all"></a> Export all build records to a file (--all)
+### <a name="finalize"></a> Ensure build records are finalized before exporting (--finalize)
 
-Use the `--all` flag and redirect the output:
+Clients can report their own traces concurrently and not all traces may be
+finalized when a build is completed. Use the `--finalize` flag to ensure all
+traces are finalized before exporting. It should only be used if you are sure
+that the build is completed.
 
 ```console
-docker buildx history export --all > all-builds.dockerbuild
+docker buildx history export --finalize qu2gsuo8ejqrwdfii23xkkckt -o finalized-build.dockerbuild
 ```
 
-Or use the `--output` flag:
+### <a name="output"></a> Export a single build to a custom file (--output)
 
 ```console
-docker buildx history export --all -o all-builds.dockerbuild
+docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output mybuild.dockerbuild
 ```
 
-### <a name="builder"></a> Use a specific builder instance (--builder)
+You can find build IDs by running:
 
 ```console
-docker buildx history export --builder builder0 ^1 -o builder0-build.dockerbuild
+docker buildx history ls
 ```
 
-### <a name="debug"></a> Enable debug logging (--debug)
+To export two builds to separate files:
 
 ```console
-docker buildx history export --debug qu2gsuo8ejqrwdfii23xkkckt -o debug-build.dockerbuild
-```
+# Using build IDs
+docker buildx history export qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3 -o multi.dockerbuild
+
+# Or using relative offsets
+docker buildx history export ^1 ^2 -o multi.dockerbuild
+```
+
+Or use shell redirection:
+
+```console
+docker buildx history export ^1 > mybuild.dockerbuild
+docker buildx history export ^2 > backend-build.dockerbuild
+```