history: allow disabling build history

client/client_control_test.go

@@ -54,6 +54,37 @@ func testClientCustomGRPCOpts(t *testing.T, sb integration.Sandbox) {
 	require.Contains(t, interceptedMethods, "/moby.buildkit.v1.Control/Solve")
 }
 
+func testBuildHistoryDisabled(t *testing.T, sb integration.Sandbox) {
+	c, err := New(sb.Context(), sb.Address())
+	require.NoError(t, err)
+	defer c.Close()
+
+	successRef := identity.NewID()
+	successDef, err := llb.Scratch().File(llb.Mkfile("file", 0o644, nil)).Marshal(sb.Context())
+	require.NoError(t, err)
+	_, err = c.Solve(sb.Context(), successDef, SolveOpt{Ref: successRef}, nil)
+	require.NoError(t, err)
+	requireNoBuildHistory(t, c, sb, successRef)
+
+	failureRef := identity.NewID()
+	failureDef, err := llb.Scratch().File(llb.Rm("missing")).Marshal(sb.Context())
+	require.NoError(t, err)
+	_, err = c.Solve(sb.Context(), failureDef, SolveOpt{Ref: failureRef}, nil)
+	require.Error(t, err)
+	requireNoBuildHistory(t, c, sb, failureRef)
+}
+
+func requireNoBuildHistory(t *testing.T, c *Client, sb integration.Sandbox, ref string) {
+	t.Helper()
+	history, err := c.ControlClient().ListenBuildHistory(sb.Context(), &controlapi.BuildHistoryRequest{
+		Ref:       ref,
+		EarlyExit: true,
+	})
+	require.NoError(t, err)
+	_, err = history.Recv()
+	require.ErrorIs(t, err, io.EOF)
+}
+
 func testListenBuildHistoryExcludesSoftDeletedRecords(t *testing.T, sb integration.Sandbox) {
 	c, err := New(sb.Context(), sb.Address())
 	require.NoError(t, err)
@@ -128,3 +159,9 @@ func testListenBuildHistoryExcludesSoftDeletedRecords(t *testing.T, sb integrati
 		}
 	}
 }
+
+type historyDisabled struct{}
+
+func (*historyDisabled) UpdateConfigFile(in string) (string, func() error) {
+	return in + "\n\n[history]\n  maxEntries = 0\n", nil
+}

client/client_test.go

@@ -319,6 +319,12 @@ func testIntegration(t *testing.T, funcs ...func(t *testing.T, sb integration.Sa
 	tests = append(tests, diffOpTestCases()...)
 	integration.Run(t, tests, mirrors)
 
+	integration.Run(t, integration.TestFuncs(
+		testBuildHistoryDisabled,
+	), mirrors, integration.WithMatrix("history", map[string]any{
+		"disabled": &historyDisabled{},
+	}))
+
 	// the rest of the tests are meant for non-Windows, skipping on Windows.
 	integration.SkipOnPlatform(t, "windows")
 

cmd/buildkitd/config/config.go

@@ -221,7 +221,7 @@ type DNSConfig struct {
 
 type HistoryConfig struct {
 	MaxAge     Duration `toml:"maxAge"`
-	MaxEntries int64    `toml:"maxEntries"`
+	MaxEntries *int64   `toml:"maxEntries"`
 }
 
 type DockerfileFrontendConfig struct {

cmd/buildkitd/config/load_test.go

@@ -151,3 +151,30 @@ searchDomains=["example.com"]
 	require.Equal(t, []string{"example.com"}, cfg.DNS.SearchDomains)
 	require.Equal(t, []string{"edns0"}, cfg.DNS.Options)
 }
+
+func TestLoadHistoryMaxEntries(t *testing.T) {
+	tests := []struct {
+		name    string
+		toml    string
+		wantSet bool
+		want    int64
+	}{
+		{name: "unset", toml: "[history]\nmaxAge = 172800\n"},
+		{name: "disabled", toml: "[history]\nmaxEntries = 0\n", wantSet: true, want: 0},
+		{name: "configured", toml: "[history]\nmaxEntries = 12\n", wantSet: true, want: 12},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg, err := Load(bytes.NewBufferString(tc.toml))
+			require.NoError(t, err)
+			require.NotNil(t, cfg.History)
+			if tc.wantSet {
+				require.NotNil(t, cfg.History.MaxEntries)
+				require.Equal(t, tc.want, *cfg.History.MaxEntries)
+			} else {
+				require.Nil(t, cfg.History.MaxEntries)
+			}
+		})
+	}
+}

docs/buildkitd.toml.md

@@ -64,7 +64,11 @@ provenanceEnvDir = "/etc/buildkit/provenance.d"
 [history]
   # maxAge is the maximum age of history entries to keep, in seconds.
   maxAge = 172800
-  # maxEntries is the maximum number of history entries to keep.
+  # maxEntries is the maximum number of history entries to keep. When the
+  # history section is omitted, the default is 50. If only maxAge is set,
+  # all entries older than maxAge are removed.
+  # Setting this value to 0 prevents recording new build history, including
+  # active-build events. Existing records remain available until normal GC.
   maxEntries = 50
 
 [worker.oci]

solver/llbsolver/history.go

@@ -16,6 +16,7 @@ import (
 	"github.com/moby/buildkit/frontend"
 	"github.com/moby/buildkit/frontend/attestations"
 	"github.com/moby/buildkit/solver"
+	"github.com/moby/buildkit/solver/llbsolver/history"
 	"github.com/moby/buildkit/solver/llbsolver/provenance"
 	provenancetypes "github.com/moby/buildkit/solver/llbsolver/provenance/types"
 	"github.com/moby/buildkit/util/bklog"
@@ -26,6 +27,40 @@ import (
 	"google.golang.org/protobuf/types/known/timestamppb"
 )
 
+// recordBuildCompletionWithoutHistory reads an already-closed job's status
+// stream and emits the same build metrics as the history-recording path.
+func (s *Solver) recordBuildCompletionWithoutHistory(ctx context.Context, j *solver.Job, startedAt time.Time, buildErr error) {
+	ctx, cancel := context.WithTimeoutCause(ctx, 300*time.Second, errors.WithStack(context.DeadlineExceeded))
+	defer cancel()
+
+	ch := make(chan *client.SolveStatus)
+	statusErr := make(chan error, 1)
+	go func() {
+		statusErr <- j.Status(ctx, ch)
+	}()
+
+	rec := &controlapi.BuildHistoryRecord{
+		CreatedAt:   timestamppb.New(startedAt),
+		CompletedAt: timestamppb.Now(),
+	}
+	if buildErr != nil {
+		rec.Error = history.BuildErrorStatus(ctx, buildErr)
+	}
+
+	var summary history.StatusSummary
+	for st := range ch {
+		summary.Update(st)
+	}
+	if err := <-statusErr; err != nil {
+		bklog.G(ctx).Warnf("failed to read build status for metrics: %+v", err)
+	}
+	rec.NumCachedSteps = int32(summary.NumCachedSteps)
+	rec.NumCompletedSteps = int32(summary.NumCompletedSteps)
+	rec.NumTotalSteps = int32(summary.NumTotalSteps)
+	rec.NumWarnings = int32(summary.NumWarnings)
+	s.metrics.recordBuildCompletion(ctx, rec)
+}
+
 func (s *Solver) recordBuildHistory(ctx context.Context, id string, req frontend.SolveRequest, exp ExporterRequest, j *solver.Job, usage *resources.SysSampler) (func(context.Context, *Result, []exporter.DescriptorReference, error) error, error) {
 	stopTrace, err := detect.Recorder.Record(ctx)
 	if err != nil {

solver/llbsolver/history/buildhistory.go

@@ -77,11 +77,54 @@ type StatusImportResult struct {
 	NumWarnings       int
 }
 
+const (
+	statusFlagCached uint8 = 1 << iota
+	statusFlagCompleted
+)
+
+// StatusSummary contains the build-step counts used by history records and metrics.
+type StatusSummary struct {
+	NumCachedSteps    int
+	NumCompletedSteps int
+	NumTotalSteps     int
+	NumWarnings       int
+	vertices          map[digest.Digest]uint8
+}
+
+// Update incorporates one solve-status update into the summary.
+func (s *StatusSummary) Update(st *client.SolveStatus) {
+	if s.vertices == nil {
+		s.vertices = map[digest.Digest]uint8{}
+	}
+	s.NumWarnings += len(st.Warnings)
+	for _, vertex := range st.Vertexes {
+		state, ok := s.vertices[vertex.Digest]
+		if !ok {
+			s.NumTotalSteps++
+		}
+		if vertex.Cached && state&statusFlagCached == 0 {
+			s.NumCachedSteps++
+			state |= statusFlagCached
+		}
+		if vertex.Completed != nil && state&statusFlagCompleted == 0 {
+			s.NumCompletedSteps++
+			state |= statusFlagCompleted
+		}
+		s.vertices[vertex.Digest] = state
+	}
+}
+
+// Enabled reports whether new build history events and records are captured.
+func (h *Queue) Enabled() bool {
+	return h.opt.CleanConfig == nil || h.opt.CleanConfig.MaxEntries == nil || *h.opt.CleanConfig.MaxEntries != 0
+}
+
 func NewQueue(opt QueueOpt) (*Queue, error) {
 	if opt.CleanConfig == nil {
+		maxEntries := int64(50)
 		opt.CleanConfig = &config.HistoryConfig{
 			MaxAge:     config.Duration{Duration: 48 * time.Hour},
-			MaxEntries: 50,
+			MaxEntries: &maxEntries,
 		}
 	}
 	h := &Queue{
@@ -149,6 +192,19 @@ func NewQueue(opt QueueOpt) (*Queue, error) {
 	return h, nil
 }
 
+// maxEntries returns the retention floor used by GC. An unset MaxEntries in a
+// present history section and an explicit zero both return zero; Enabled keeps
+// them distinct because only an explicit zero disables recording.
+func (h *Queue) maxEntries() int64 {
+	if h.opt.CleanConfig == nil {
+		return 50
+	}
+	if h.opt.CleanConfig.MaxEntries == nil {
+		return 0
+	}
+	return *h.opt.CleanConfig.MaxEntries
+}
+
 func (h *Queue) gc() error {
 	var records []*controlapi.BuildHistoryRecord
 
@@ -173,7 +229,8 @@ func (h *Queue) gc() error {
 	}
 
 	// in order for record to get deleted by gc it exceed both maxentries and maxage criteria
-	if len(records) < int(h.opt.CleanConfig.MaxEntries) {
+	maxEntries := h.maxEntries()
+	if len(records) < int(maxEntries) {
 		return nil
 	}
 
@@ -186,7 +243,7 @@ func (h *Queue) gc() error {
 	defer h.mu.Unlock()
 
 	now := time.Now()
-	for _, r := range records[h.opt.CleanConfig.MaxEntries:] {
+	for _, r := range records[maxEntries:] {
 		if now.Add(-h.opt.CleanConfig.MaxAge.Duration).After(r.CompletedAt.AsTime()) {
 			if _, err := h.delete(r.Ref); err != nil {
 				return err
@@ -634,13 +691,21 @@ func (w *Writer) Commit(ctx context.Context) (*ocispecs.Descriptor, func(), erro
 		}, nil
 }
 
-func (h *Queue) ImportError(ctx context.Context, err error) (_ *spb.Status, _ *controlapi.Descriptor, _ func(), retErr error) {
+// BuildErrorStatus converts a build error to the status stored in history and
+// consumed by build metrics.
+func BuildErrorStatus(ctx context.Context, err error) *spb.Status {
+	if err == nil {
+		return nil
+	}
 	st, ok := grpcerrors.AsGRPCStatus(grpcerrors.ToGRPC(ctx, err))
 	if !ok {
 		st = status.New(codes.Unknown, err.Error())
 	}
+	return st.Proto()
+}
 
-	stpb := st.Proto()
+func (h *Queue) ImportError(ctx context.Context, err error) (_ *spb.Status, _ *controlapi.Descriptor, _ func(), retErr error) {
+	stpb := BuildErrorStatus(ctx, err)
 	dt, err := proto.Marshal(stpb)
 	if err != nil {
 		return nil, nil, nil, err
@@ -698,27 +763,11 @@ func (h *Queue) ImportStatus(ctx context.Context, ch chan *client.SolveStatus) (
 		}
 	}()
 
-	type vtxInfo struct {
-		cached    bool
-		completed bool
-	}
-	vtxMap := make(map[digest.Digest]*vtxInfo)
-	var numWarnings int
+	var summary StatusSummary
 
 	buf := make([]byte, 32*1024)
 	for st := range ch {
-		numWarnings += len(st.Warnings)
-		for _, vtx := range st.Vertexes {
-			if _, ok := vtxMap[vtx.Digest]; !ok {
-				vtxMap[vtx.Digest] = &vtxInfo{}
-			}
-			if vtx.Cached {
-				vtxMap[vtx.Digest].cached = true
-			}
-			if vtx.Completed != nil {
-				vtxMap[vtx.Digest].completed = true
-			}
-		}
+		summary.Update(st)
 
 		hdr := make([]byte, 4)
 		for _, pst := range st.Marshal() {
@@ -747,23 +796,12 @@ func (h *Queue) ImportStatus(ctx context.Context, ch chan *client.SolveStatus) (
 		return nil, nil, err
 	}
 
-	numCached := 0
-	numCompleted := 0
-	for _, info := range vtxMap {
-		if info.cached {
-			numCached++
-		}
-		if info.completed {
-			numCompleted++
-		}
-	}
-
 	return &StatusImportResult{
 		Descriptor:        *desc,
-		NumCachedSteps:    numCached,
-		NumCompletedSteps: numCompleted,
-		NumTotalSteps:     len(vtxMap),
-		NumWarnings:       numWarnings,
+		NumCachedSteps:    summary.NumCachedSteps,
+		NumCompletedSteps: summary.NumCompletedSteps,
+		NumTotalSteps:     summary.NumTotalSteps,
+		NumWarnings:       summary.NumWarnings,
 	}, release, nil
 }
 

solver/llbsolver/history/buildhistory_test.go

@@ -0,0 +1,59 @@
+package history
+
+import (
+	"testing"
+	"time"
+
+	"github.com/moby/buildkit/client"
+	"github.com/moby/buildkit/cmd/buildkitd/config"
+	digest "github.com/opencontainers/go-digest"
+	"github.com/stretchr/testify/require"
+)
+
+func TestQueueHistoryConfig(t *testing.T) {
+	zero := int64(0)
+	configured := int64(12)
+	tests := []struct {
+		name        string
+		q           *Queue
+		wantEnabled bool
+		wantEntries int64
+	}{
+		{name: "default config", q: &Queue{}, wantEnabled: true, wantEntries: 50},
+		{name: "age only", q: &Queue{opt: QueueOpt{CleanConfig: &config.HistoryConfig{}}}, wantEnabled: true},
+		{name: "disabled", q: &Queue{opt: QueueOpt{CleanConfig: &config.HistoryConfig{MaxEntries: &zero}}}},
+		{name: "configured", q: &Queue{opt: QueueOpt{CleanConfig: &config.HistoryConfig{MaxEntries: &configured}}}, wantEnabled: true, wantEntries: 12},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			require.Equal(t, tc.wantEnabled, tc.q.Enabled())
+			require.Equal(t, tc.wantEntries, tc.q.maxEntries())
+		})
+	}
+}
+
+func TestStatusSummary(t *testing.T) {
+	completed := time.Now()
+	first := digest.FromString("first")
+	second := digest.FromString("second")
+	var summary StatusSummary
+
+	summary.Update(&client.SolveStatus{
+		Vertexes: []*client.Vertex{
+			{Digest: first, Cached: true},
+			{Digest: second, Completed: &completed},
+		},
+		Warnings: []*client.VertexWarning{{}},
+	})
+	summary.Update(&client.SolveStatus{
+		Vertexes: []*client.Vertex{
+			{Digest: first, Cached: true, Completed: &completed},
+		},
+	})
+
+	require.Equal(t, 1, summary.NumCachedSteps)
+	require.Equal(t, 2, summary.NumCompletedSteps)
+	require.Equal(t, 2, summary.NumTotalSteps)
+	require.Equal(t, 1, summary.NumWarnings)
+}