pd-ctl: add GC state inspection commands

client/clients/gc/client.go

@@ -286,11 +286,14 @@ func (b *GlobalGCBarrierInfo) isExpiredImpl(now time.Time) bool {
 //nolint:revive
 type GCState struct {
 	// The ID of the keyspace this GC state belongs to.
-	KeyspaceID    uint32
-	TxnSafePoint  uint64
-	GCSafePoint   uint64
-	hasGCBarriers bool
-	gcBarriers    []*GCBarrierInfo
+	KeyspaceID uint32
+	// IsKeyspaceLevelGC reports whether this state belongs to an independent
+	// keyspace-level GC scope.
+	IsKeyspaceLevelGC bool
+	TxnSafePoint      uint64
+	GCSafePoint       uint64
+	hasGCBarriers     bool
+	gcBarriers        []*GCBarrierInfo
 }
 
 // NewGCStateWithoutGCBarriers creates a GCState instance without GC barriers info.

client/gc_client.go

@@ -334,15 +334,18 @@ func pbToGCState(pb *pdpb.GCState, reqStartTime time.Time, excludeGCBarriers boo
 	if pb.KeyspaceScope != nil {
 		keyspaceID = pb.KeyspaceScope.KeyspaceId
 	}
+	var state gc.GCState
 	if excludeGCBarriers {
-		return gc.NewGCStateWithoutGCBarriers(keyspaceID, pb.GetTxnSafePoint(), pb.GetGcSafePoint())
-	}
-
-	gcBarriers := make([]*gc.GCBarrierInfo, 0, len(pb.GetGcBarriers()))
-	for _, b := range pb.GetGcBarriers() {
-		gcBarriers = append(gcBarriers, pbToGCBarrierInfo(b, reqStartTime))
+		state = gc.NewGCStateWithoutGCBarriers(keyspaceID, pb.GetTxnSafePoint(), pb.GetGcSafePoint())
+	} else {
+		gcBarriers := make([]*gc.GCBarrierInfo, 0, len(pb.GetGcBarriers()))
+		for _, b := range pb.GetGcBarriers() {
+			gcBarriers = append(gcBarriers, pbToGCBarrierInfo(b, reqStartTime))
+		}
+		state = gc.NewGCStateWithGCBarriers(keyspaceID, pb.GetTxnSafePoint(), pb.GetGcSafePoint(), gcBarriers)
 	}
-	return gc.NewGCStateWithGCBarriers(keyspaceID, pb.GetTxnSafePoint(), pb.GetGcSafePoint(), gcBarriers)
+	state.IsKeyspaceLevelGC = pb.GetIsKeyspaceLevelGc()
+	return state
 }
 
 // SetGlobalGCBarrier sets (creates or updates) a global GC barrier.

client/gc_client_test.go

@@ -0,0 +1,71 @@
+// Copyright 2026 TiKV Project 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
+//
+//     http://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 pd
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/pingcap/kvproto/pkg/pdpb"
+)
+
+func TestPBToGCStatePreservesKeyspaceLevelGC(t *testing.T) {
+	requestStart := time.Unix(100, 0)
+	for _, testCase := range []struct {
+		name              string
+		isKeyspaceLevelGC bool
+		excludeBarriers   bool
+	}{
+		{name: "keyspace-level-with-barriers", isKeyspaceLevelGC: true},
+		{
+			name:              "keyspace-level-without-barriers",
+			isKeyspaceLevelGC: true,
+			excludeBarriers:   true,
+		},
+		{name: "unified-with-barriers", isKeyspaceLevelGC: false},
+		{
+			name:              "unified-without-barriers",
+			isKeyspaceLevelGC: false,
+			excludeBarriers:   true,
+		},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			pbState := &pdpb.GCState{
+				KeyspaceScope:     &pdpb.KeyspaceScope{KeyspaceId: 42},
+				IsKeyspaceLevelGc: testCase.isKeyspaceLevelGC,
+				TxnSafePoint:      100,
+				GcSafePoint:       90,
+				GcBarriers: []*pdpb.GCBarrierInfo{
+					{BarrierId: "backup", BarrierTs: 95, TtlSeconds: 60},
+				},
+			}
+
+			state := pbToGCState(
+				pbState,
+				requestStart,
+				testCase.excludeBarriers,
+			)
+			require.Equal(t, testCase.isKeyspaceLevelGC,
+				state.IsKeyspaceLevelGC)
+			require.Equal(t, uint32(42), state.KeyspaceID)
+			require.Equal(t, uint64(100), state.TxnSafePoint)
+			require.Equal(t, uint64(90), state.GCSafePoint)
+			require.Equal(t, !testCase.excludeBarriers,
+				state.HasGCBarriers())
+		})
+	}
+}

pkg/storage/endpoint/cluster_id_test.go

@@ -30,6 +30,7 @@ func TestMain(m *testing.M) {
 }
 
 func TestInitClusterID(t *testing.T) {
+	t.Cleanup(keypath.ResetClusterID)
 	re := require.New(t)
 	_, client, clean := etcdutil.NewTestEtcdCluster(t, 1, nil)
 	defer clean()

tests/integrations/client/client_test.go

@@ -2771,9 +2771,16 @@ func (s *clientStatefulTestSuite) TestGetAllKeyspaceGCStates() {
 	re.NoError(err)
 	res, err = cli.GetAllKeyspacesGCStates(ctx, gc.ExcludeGCBarriers(false), gc.ExcludeGlobalGCBarriers(false))
 	re.NoError(err)
-	state, ok = res.GCStates[2]
+	state1, ok := res.GCStates[1]
 	re.True(ok)
-	gcBarriers, err = state.GetGCBarriers()
+	re.True(state1.IsKeyspaceLevelGC)
+	state2, ok := res.GCStates[2]
+	re.True(ok)
+	re.True(state2.IsKeyspaceLevelGC)
+	state3, ok := res.GCStates[3]
+	re.True(ok)
+	re.False(state3.IsKeyspaceLevelGC)
+	gcBarriers, err = state2.GetGCBarriers()
 	re.NoError(err)
 	re.Equal("b4", gcBarriers[0].BarrierID)
 	re.Equal(uint64(14), gcBarriers[0].BarrierTS)

tools/pd-ctl/README.md

@@ -10,3 +10,73 @@
 ## Usage
 
 The details about how to use `pd-ctl` can be found in [PD Control User Guide](https://docs.pingcap.com/tidb/dev/pd-control).
+
+## GC state troubleshooting
+
+Use `gc-state` to inspect the safe points and barriers that can block GC. The
+command is read-only and emits deterministic JSON for scripts and diffs.
+
+Inspect one keyspace by its decimal ID:
+
+```bash
+pd-ctl gc-state keyspace 42
+```
+
+```json
+{
+  "requested_keyspace_id": 42,
+  "effective_keyspace_id": 4294967295,
+  "is_keyspace_level_gc": false,
+  "txn_safe_point": 465000000000000000,
+  "gc_safe_point": 464900000000000000,
+  "gc_barriers": []
+}
+```
+
+The response contains both `requested_keyspace_id` and
+`effective_keyspace_id`. They are equal for keyspace-level GC. A keyspace that
+uses unified GC returns `4294967295`, the NullKeyspace ID, as its effective
+scope. The response contains local `gc_barriers` only.
+
+Inspect cluster-wide state when the local barriers do not explain the
+effective safe point:
+
+```bash
+pd-ctl gc-state global
+```
+
+```json
+{
+  "global_gc_barriers": []
+}
+```
+
+The global response does not contain per-keyspace safe points or local
+barriers. Its current field is `global_gc_barriers`; other cluster-wide GC
+state can be added to the same object in the future.
+
+Inspect every active GC scope together with cluster-wide state:
+
+```bash
+pd-ctl gc-state all
+```
+
+```json
+{
+  "gc_states": [
+    {
+      "keyspace_id": 42,
+      "is_keyspace_level_gc": true,
+      "txn_safe_point": 465000000000000000,
+      "gc_safe_point": 464900000000000000,
+      "gc_barriers": []
+    }
+  ],
+  "global_gc_barriers": []
+}
+```
+
+The combined response sorts `gc_states` by `keyspace_id` and reports
+cluster-wide barriers once in the top-level `global_gc_barriers` array.
+Barrier TTLs use remaining seconds, and `9223372036854775807` means that a
+barrier never expires.