base,sstable/block: dump block data on checksum mismatch errors

When Pebble encounters a bad checksum error, it is fatal and typically
impossible to get more information about what went wrong. This change
attaches the raw block data to the checksum mismatch error so it can be
extracted into DataCorruptionInfo and logged as a hex dump.

A new transparent wrapper error type CorruptBlockData carries the raw
block bytes without affecting Error() output, Sentry reporting, or wire
encoding. ValidateChecksum attaches the block data on checksum failure.
reportCorruption extracts the data into DataCorruptionInfo, and
MakeLoggingEventListener logs it as hex.

Co-Authored-By: roachdev-claude <roachdev-claude-bot@cockroachlabs.com>

Author: RaduBerinde

event.go

@@ -5,6 +5,7 @@
 package pebble
 
 import (
+	"encoding/hex"
 	"fmt"
 	"strings"
 	"sync"
@@ -63,6 +64,9 @@ type DataCorruptionInfo struct {
 	// Details of the error. See cockroachdb/error for how to format with or
 	// without redaction.
 	Details error
+	// CorruptedBlockData contains raw data of the corrupted block. Nil if not
+	// applicable.
+	CorruptedBlockData []byte
 }
 
 func (i DataCorruptionInfo) String() string {
@@ -78,6 +82,39 @@ func (i DataCorruptionInfo) SafeFormat(w redact.SafePrinter, _ rune) {
 	w.Printf("; bounds: %s; details: %+v", i.Bounds.String(), i.Details)
 }
 
+// FormatBlockDataAsHex formats the corrupted block data as a hex dump with 64
+// bytes per line grouped into 8-byte groups, up to 256 KiB. Returns empty
+// string if no block data is available.
+func (i DataCorruptionInfo) FormatBlockDataAsHex() string {
+	data := i.CorruptedBlockData
+	if len(data) == 0 {
+		return ""
+	}
+	const maxSize = 256 << 10 // 256 KiB
+	truncated := len(data) > maxSize
+	if truncated {
+		data = data[:maxSize]
+	}
+	const bytesPerLine = 64
+	var buf strings.Builder
+	for j := 0; j < len(data); j += bytesPerLine {
+		end := min(j+bytesPerLine, len(data))
+		line := data[j:end]
+		fmt.Fprintf(&buf, "%6d  ", j)
+		for k := 0; k < len(line); k += 8 {
+			if k > 0 {
+				buf.WriteByte(' ')
+			}
+			buf.WriteString(hex.EncodeToString(line[k:min(k+8, len(line))]))
+		}
+		buf.WriteByte('\n')
+	}
+	if truncated {
+		fmt.Fprintf(&buf, "... (truncated from %d bytes)\n", len(i.CorruptedBlockData))
+	}
+	return buf.String()
+}
+
 // LevelInfo contains info pertaining to a particular level.
 type LevelInfo struct {
 	Level  int
@@ -1147,6 +1184,9 @@ func MakeLoggingEventListener(logger Logger) EventListener {
 		},
 		DataCorruption: func(info DataCorruptionInfo) {
 			logger.Errorf("%s", info)
+			if s := info.FormatBlockDataAsHex(); s != "" {
+				logger.Errorf("corrupted block data (hex):\n%s", s)
+			}
 		},
 		CompactionBegin: func(info CompactionInfo) {
 			logger.Infof("%s", info)
@@ -1421,11 +1461,12 @@ func (d *DB) reportCorruption(meta base.ObjectInfo, err error) error {
 		err = errors.WithHintf(err, "path: %s", redact.Safe(path))
 	}
 	info := DataCorruptionInfo{
-		Path:     path,
-		IsRemote: objMeta.IsRemote(),
-		Locator:  objMeta.Remote.Locator,
-		Bounds:   meta.UserKeyBounds(),
-		Details:  err,
+		Path:               path,
+		IsRemote:           objMeta.IsRemote(),
+		Locator:            objMeta.Remote.Locator,
+		Bounds:             meta.UserKeyBounds(),
+		Details:            err,
+		CorruptedBlockData: base.ExtractCorruptBlockData(err),
 	}
 	d.opts.EventListener.DataCorruption(info)
 	// We don't use errors.Join() because that also annotates with this stack

event_test.go

@@ -0,0 +1,33 @@
+// Copyright 2026 The LevelDB-Go and Pebble Authors. All rights reserved. Use
+// of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
+
+package pebble
+
+import (
+	"encoding/hex"
+	"strings"
+	"testing"
+
+	"github.com/cockroachdb/datadriven"
+)
+
+func TestFormatBlockDataAsHex(t *testing.T) {
+	datadriven.RunTest(t, "testdata/format_block_data_as_hex", func(t *testing.T, td *datadriven.TestData) string {
+		switch td.Cmd {
+		case "format":
+			input := strings.ReplaceAll(td.Input, "\n", "")
+			input = strings.ReplaceAll(input, " ", "")
+			data, err := hex.DecodeString(input)
+			if err != nil {
+				t.Fatalf("invalid hex input: %v", err)
+			}
+			info := DataCorruptionInfo{CorruptedBlockData: data}
+			return info.FormatBlockDataAsHex()
+
+		default:
+			t.Fatalf("unknown command: %s", td.Cmd)
+			return ""
+		}
+	})
+}

internal/base/error.go

@@ -5,6 +5,8 @@
 package base
 
 import (
+	"slices"
+
 	"github.com/cockroachdb/errors"
 	"github.com/cockroachdb/pebble/internal/invariants"
 )
@@ -35,6 +37,34 @@ func CorruptionErrorf(format string, args ...interface{}) error {
 	return errors.Mark(errors.Newf(format, args...), ErrCorruption)
 }
 
+// CorruptBlockData is a wrapper error type that carries the raw block data
+// associated with a corruption error. It wraps the cause error transparently
+// (Error() delegates to cause), does not implement SafeDetailer, and is not
+// registered with the error encoding system, ensuring the raw data does not
+// leak to Sentry or over the wire.
+type CorruptBlockData struct {
+	cause error
+	Data  []byte
+}
+
+func (e *CorruptBlockData) Error() string { return e.cause.Error() }
+func (e *CorruptBlockData) Unwrap() error { return e.cause }
+
+// AttachCorruptBlockData wraps an error with a copy of the raw block data.
+func AttachCorruptBlockData(err error, data []byte) error {
+	return &CorruptBlockData{cause: err, Data: slices.Clone(data)}
+}
+
+// ExtractCorruptBlockData extracts the raw block data from the error chain, if
+// present.
+func ExtractCorruptBlockData(err error) []byte {
+	var e *CorruptBlockData
+	if errors.As(err, &e) {
+		return e.Data
+	}
+	return nil
+}
+
 // AssertionFailedf creates an assertion error and panics in invariants.Enabled
 // builds. It should only be used when it indicates a bug.
 func AssertionFailedf(format string, args ...interface{}) error {

internal/base/error_test.go

@@ -0,0 +1,30 @@
+// Copyright 2026 The LevelDB-Go and Pebble Authors. All rights reserved. Use
+// of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
+
+package base
+
+import (
+	"testing"
+
+	"github.com/cockroachdb/errors"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCorruptBlockData(t *testing.T) {
+	data := []byte("test block data")
+	inner := errors.New("inner error")
+	err := AttachCorruptBlockData(inner, data)
+	// Wrap further.
+	err = errors.Wrap(err, "outer")
+	err = errors.WithStack(err)
+
+	got := ExtractCorruptBlockData(err)
+	require.Equal(t, data, got)
+
+	// Original error message is preserved.
+	require.Contains(t, err.Error(), "inner error")
+
+	// No data when not attached.
+	require.Nil(t, ExtractCorruptBlockData(errors.New("plain")))
+}

sstable/block/block.go

@@ -197,6 +197,7 @@ func ValidateChecksum(checksumType ChecksumType, b []byte, bh Handle) error {
 			err = errors.WithSafeDetails(err, ". bit flip found: byte index %d. got: 0x%x. want: 0x%x.",
 				errors.Safe(indexFound), errors.Safe(data[indexFound]), errors.Safe(data[indexFound]^(1<<bitFound)))
 		}
+		err = base.AttachCorruptBlockData(err, b)
 		return err
 	}
 	return nil

testdata/format_block_data_as_hex

@@ -0,0 +1,16 @@
+# 100 bytes (0x00..0x63): one full 64-byte line + a partial second line.
+format
+000102030405060708090a0b0c0d0e0f
+101112131415161718191a1b1c1d1e1f
+202122232425262728292a2b2c2d2e2f
+303132333435363738393a3b3c3d3e3f
+404142434445464748494a4b4c4d4e4f
+505152535455565758595a5b5c5d5e5f
+60616263
+----
+     0  0001020304050607 08090a0b0c0d0e0f 1011121314151617 18191a1b1c1d1e1f 2021222324252627 28292a2b2c2d2e2f 3031323334353637 38393a3b3c3d3e3f
+    64  4041424344454647 48494a4b4c4d4e4f 5051525354555657 58595a5b5c5d5e5f 60616263
+
+# Empty block: no output.
+format
+----