gh-154090: Store profiling mode in binary files

InternalDocs/profiling_binary_format.md

@@ -82,15 +82,18 @@ with a single seek to `file_size - 32`, without first reading the header.
 | | | | reserved) |
 | 12 | 8 | uint64 | Start timestamp (microseconds) |
 | 20 | 8 | uint64 | Sample interval (microseconds) |
-| 28 | 4 | uint32 | Total sample count |
-| 32 | 4 | uint32 | Thread count |
-| 36 | 8 | uint64 | String table offset |
-| 44 | 8 | uint64 | Frame table offset |
-| 52 | 4 | uint32 | Compression type (0=none, 1=zstd) |
-| 56 | 8 | bytes | Reserved (zero-filled)  |
+| 28 | 8 | uint64 | Total sample count |
+| 36 | 4 | uint32 | Thread count |
+| 40 | 8 | uint64 | String table offset |
+| 48 | 8 | uint64 | Frame table offset |
+| 56 | 4 | uint32 | Compression type (0=none, 1=zstd) |
+| 60 | 4 | uint32 | Profiling mode plus one (0=unknown) |
 +--------+------+---------+----------------------------------------+
 ```
 
+Profiling modes use their `_remote_debugging.PROFILING_MODE_*` value plus one,
+leaving zero available for binaries written before this field was defined.
+
 The magic number `0x54414348` ("TACH" for Tachyon) identifies the file format
 and also serves as an **endianness marker**. When read on a system with
 different byte order than the writer, it appears as `0x48434154`. The reader
@@ -530,11 +533,10 @@ one write() call (or feeds through the compression stream).
 
 ## Future Considerations
 
-The format reserves space for future extensions. The 12 reserved bytes in
-the header could hold additional metadata. The 16-byte checksum field in
-the footer is currently unused. The version field allows incompatible
-changes with graceful rejection. New compression types could be added
-(compression_type > 1).
+The Python-version field retains one reserved byte. The 16-byte checksum
+field in the footer is currently unused. The version field allows
+incompatible changes with graceful rejection. New compression types could
+be added (compression_type > 1).
 
 Any changes that alter the meaning of existing fields or the parsing logic
 should increment the version number to prevent older readers from

Lib/profiling/sampling/binary_collector.py

@@ -49,14 +49,15 @@ class BinaryCollector(Collector):
  """
 
  def __init__(self, filename, sample_interval_usec, *, skip_idle=False,
- compression='auto'):
+ compression='auto', mode=None):
  """Create a new binary collector.
 
  Args:
  filename: Path to output binary file
  sample_interval_usec: Sampling interval in microseconds
  skip_idle: If True, skip idle threads (not used in binary format)
  compression: 'auto', 'zstd', 'none', or int (0=none, 1=zstd)
+ mode: Profiling mode, or None if unknown
  """
  self.filename = filename
  self.sample_interval_usec = sample_interval_usec
@@ -65,7 +66,9 @@ def __init__(self, filename, sample_interval_usec, *, skip_idle=False,
  compression_type = _resolve_compression(compression)
  start_time_us = int(time.monotonic() * 1_000_000)
  self._writer = _remote_debugging.BinaryWriter(
- filename, sample_interval_usec, start_time_us, compression=compression_type
+ filename, sample_interval_usec, start_time_us,
+ compression=compression_type,
+ mode=-1 if mode is None else mode,
  )
 
  def collect(self, stack_frames, timestamp_us=None):

Lib/profiling/sampling/binary_reader.py

@@ -50,6 +50,7 @@ def get_info(self):
  - string_count: Number of unique strings
  - frame_count: Number of unique frames
  - compression: Compression type used
+ - mode: Profiling mode, or None if not recorded
  """
  if self._reader is None:
  raise RuntimeError("Reader not open. Use as context manager.")
@@ -119,12 +120,14 @@ def convert_binary_to_format(input_file, output_file, output_format,
  elif output_format == 'gecko':
  collector = GeckoCollector(interval)
  elif output_format == "jsonl":
- collector = JsonlCollector(interval)
+ collector = JsonlCollector(interval, mode=info.get("mode"))
  else:
  raise ValueError(f"Unknown output format: {output_format}")
 
  # Replay samples through collector
  count = reader.replay_samples(collector, progress_callback)
+ if hasattr(collector, "set_mode"):
+ collector.set_mode(info.get("mode"))
 
  # Export to target format
  collector.export(output_file)

Lib/profiling/sampling/cli.py

@@ -661,15 +661,16 @@ def _create_collector(format_type, sample_interval_usec, skip_idle, opcodes=Fals
  return collector_class(
  sample_interval_usec,
  baseline_binary_path=diff_baseline,
- skip_idle=skip_idle
+ skip_idle=skip_idle,
+ mode=mode,
  )
 
  # Binary format requires output file and compression
  if format_type == "binary":
  if output_file is None:
  raise ValueError("Binary format requires an output file")
  return collector_class(output_file, sample_interval_usec, skip_idle=skip_idle,
- compression=compression)
+ compression=compression, mode=mode)
 
  # Gecko format never skips idle (it needs both GIL and CPU data)
  # and is the only format that uses opcodes for interval markers
@@ -760,6 +761,7 @@ def _replay_with_reader(args, reader):
 
  collector = _create_collector(
  args.format, interval, skip_idle=False,
+ mode=info.get("mode"),
  diff_baseline=args.diff_baseline
  )
 
@@ -776,6 +778,8 @@ def progress_callback(current, total):
  )
 
  count = reader.replay_samples(collector, progress_callback)
+ if hasattr(collector, "set_mode"):
+ collector.set_mode(info.get("mode"))
  print()
 
  if args.format == "pstats":
@@ -789,7 +793,8 @@ def progress_callback(current, total):
  sort_mode = _sort_to_mode(sort_choice)
  collector.print_stats(
  sort_mode, limit, not args.no_summary,
- PROFILING_MODE_WALL
+ info.get("mode") if info.get("mode") is not None
+ else PROFILING_MODE_WALL
  )
  else:
  filename = (

Lib/profiling/sampling/stack_collector.py

@@ -142,6 +142,9 @@ def set_stats(self, sample_interval_usec, duration_sec, sample_rate,
  "mode": mode
  }
 
+ def set_mode(self, mode):
+ self.stats["mode"] = mode
+
  def export(self, filename):
  flamegraph_data = self._convert_to_flamegraph_format()
 
@@ -482,13 +485,15 @@ def _create_flamegraph_html(self, data):
 class DiffFlamegraphCollector(FlamegraphCollector):
  """Differential flamegraph collector that compares against a baseline binary profile."""
 
- def __init__(self, sample_interval_usec, *, baseline_binary_path, skip_idle=False):
+ def __init__(self, sample_interval_usec, *, baseline_binary_path,
+ skip_idle=False, mode=None):
  super().__init__(sample_interval_usec, skip_idle=skip_idle)
  if not os.path.exists(baseline_binary_path):
  raise ValueError(f"Baseline file not found: {baseline_binary_path}")
  self.baseline_binary_path = baseline_binary_path
  self._baseline_collector = None
  self._elided_paths = set()
+ self.mode = mode
 
  def _load_baseline(self):
  """Load baseline profile from binary file."""
@@ -497,6 +502,16 @@ def _load_baseline(self):
  with BinaryReader(self.baseline_binary_path) as reader:
  info = reader.get_info()
 
+ baseline_mode = info.get("mode")
+ if (
+ baseline_mode is not None
+ and self.mode is not None
+ and baseline_mode != self.mode
+ ):
+ raise ValueError(
+ "Baseline profiling mode does not match current mode"
+ )
+
  baseline_collector = FlamegraphCollector(
  sample_interval_usec=info['sample_interval_us'],
  skip_idle=self.skip_idle

Lib/test/test_profiling/test_sampling_profiler/test_binary_format.py

@@ -25,6 +25,7 @@
  )
  from profiling.sampling.binary_collector import BinaryCollector
  from profiling.sampling.binary_reader import BinaryReader, convert_binary_to_format
+ from profiling.sampling.constants import PROFILING_MODE_CPU
  from profiling.sampling.gecko_collector import GeckoCollector
 
  ZSTD_AVAILABLE = _remote_debugging.zstd_available()
@@ -151,19 +152,23 @@ def tearDown(self):
  if os.path.exists(f):
  os.unlink(f)
 
- def create_binary_file(self, samples, interval=1000, compression="none"):
+ def create_binary_file(self, samples, interval=1000, compression="none",
+ mode=None):
  """Create a test binary file and track it for cleanup."""
- filename, _ = self.write_binary_file(samples, interval, compression)
+ filename, _ = self.write_binary_file(
+ samples, interval, compression, mode
+ )
  return filename
 
- def write_binary_file(self, samples, interval=1000, compression="none"):
+ def write_binary_file(self, samples, interval=1000, compression="none",
+ mode=None):
  """Like create_binary_file but also returns the writer collector."""
  with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
  filename = f.name
  self.temp_files.append(filename)
 
  collector = BinaryCollector(
- filename, interval, compression=compression
+ filename, interval, compression=compression, mode=mode
  )
  for sample in samples:
  collector.collect(sample)
@@ -516,6 +521,16 @@ def test_sample_interval_preserved(self):
  info = reader.get_info()
  self.assertEqual(info["sample_interval_us"], interval)
 
+ def test_profiling_mode_preserved(self):
+ filename = self.create_binary_file([], mode=PROFILING_MODE_CPU)
+ with BinaryReader(filename) as reader:
+ self.assertEqual(reader.get_info()["mode"], PROFILING_MODE_CPU)
+
+ def test_missing_profiling_mode_is_unknown(self):
+ filename = self.create_binary_file([])
+ with BinaryReader(filename) as reader:
+ self.assertIsNone(reader.get_info()["mode"])
+
  def test_threads_interleaved_samples(self):
  """Multiple threads with interleaved varying samples."""
  samples = []
@@ -1583,8 +1598,10 @@ def test_timestamp_preservation_with_rle(self):
 class TestBinaryReplayToJsonl(BinaryFormatTestBase):
  """Tests for binary -> JSONL replay via convert_binary_to_format."""
 
- def _replay_to_jsonl(self, samples, interval=1000):
- bin_path = self.create_binary_file(samples, interval=interval)
+ def _replay_to_jsonl(self, samples, interval=1000, mode=None):
+ bin_path = self.create_binary_file(
+ samples, interval=interval, mode=mode
+ )
  with tempfile.NamedTemporaryFile(suffix=".jsonl", delete=False) as f:
  jsonl_path = f.name
  self.temp_files.append(jsonl_path)
@@ -1614,6 +1631,16 @@ def test_binary_replay_to_jsonl_basic(self):
  self.assertEqual(len(frame_defs), 1)
  self.assertEqual(frame_defs[0]["line"], 99)
 
+ def test_binary_replay_to_jsonl_preserves_mode(self):
+ frame = make_frame("hot.py", 99, "hot_func")
+ records = self._replay_to_jsonl(
+ [[make_interpreter(0, [make_thread(1, [frame])])]],
+ mode=PROFILING_MODE_CPU,
+ )
+
+ meta = next(record for record in records if record["type"] == "meta")
+ self.assertEqual(meta["mode"], "cpu")
+
  def test_binary_replay_to_jsonl_rle_weight_propagation(self):
  """RLE-batched identical samples land as a single agg entry with the right total."""
  frame = make_frame("rle.py", 42, "rle_func")

Lib/test/test_profiling/test_sampling_profiler/test_cli.py

@@ -23,11 +23,13 @@
  requires_remote_subprocess_debugging,
 )
 
+from profiling.sampling.binary_reader import BinaryReader
 from profiling.sampling.cli import (
  FORMAT_EXTENSIONS,
  _create_collector,
  _generate_output_filename,
  _handle_output,
+ _replay_with_reader,
  main,
 )
 from profiling.sampling.constants import (
@@ -963,6 +965,39 @@ def test_cli_replay_reader_errors_exit_cleanly(self):
  "Error: Unsupported format version 2",
  )
 
+ def test_cli_replay_propagates_recorded_mode(self):
+ reader = mock.MagicMock()
+ reader.get_info.return_value = {
+ "sample_interval_us": 1000,
+ "sample_count": 0,
+ "compression_type": 0,
+ "mode": PROFILING_MODE_CPU,
+ }
+ reader.replay_samples.return_value = 0
+ collector = mock.MagicMock()
+ collector.export.return_value = True
+ args = SimpleNamespace(
+ format="diff_flamegraph",
+ input_file="current.bin",
+ diff_baseline="baseline.bin",
+ outfile="diff.html",
+ browser=False,
+ )
+
+ with mock.patch(
+ "profiling.sampling.cli._create_collector",
+ return_value=collector,
+ ) as create_collector:
+ _replay_with_reader(args, reader)
+
+ create_collector.assert_called_once_with(
+ "diff_flamegraph",
+ 1000,
+ skip_idle=False,
+ mode=PROFILING_MODE_CPU,
+ diff_baseline="baseline.bin",
+ )
+
  def test_cli_jsonl_format_mutually_exclusive_with_pstats(self):
  """--jsonl and --pstats cannot be combined (mutually exclusive group)."""
  with (
@@ -1005,6 +1040,23 @@ def test_cli_jsonl_create_collector_propagates_mode(self):
  meta = next(r for r in records if r["type"] == "meta")
  self.assertEqual(meta["mode"], "cpu")
 
+ def test_cli_binary_create_collector_propagates_mode(self):
+ with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
+ binary_path = f.name
+ self.addCleanup(os.unlink, binary_path)
+ collector = _create_collector(
+ "binary",
+ sample_interval_usec=1000,
+ skip_idle=True,
+ mode=PROFILING_MODE_CPU,
+ output_file=binary_path,
+ compression="none",
+ )
+ collector.export(None)
+
+ with BinaryReader(binary_path) as reader:
+ self.assertEqual(reader.get_info()["mode"], PROFILING_MODE_CPU)
+
  def test_cli_jsonl_rejects_opcodes_combination(self):
  """--opcodes is incompatible with --jsonl per opcodes_compatible_formats."""
  test_args = [

Lib/test/test_profiling/test_sampling_profiler/test_collectors.py

@@ -1530,6 +1530,28 @@ def test_diff_flamegraph_changed_functions(self):
  self.assertAlmostEqual(cold_node["diff"], -1.0)
  self.assertAlmostEqual(cold_node["diff_pct"], -50.0)
 
+ def test_diff_flamegraph_rejects_mismatched_profiling_modes(self):
+ from profiling.sampling.binary_collector import BinaryCollector
+ from profiling.sampling.stack_collector import DiffFlamegraphCollector
+
+ bin_file = tempfile.NamedTemporaryFile(suffix=".bin", delete=False)
+ self.addCleanup(close_and_unlink, bin_file)
+ writer = BinaryCollector(
+ bin_file.name,
+ sample_interval_usec=1000,
+ compression="none",
+ mode=PROFILING_MODE_CPU,
+ )
+ writer.export(None)
+
+ diff = DiffFlamegraphCollector(
+ 1000,
+ baseline_binary_path=bin_file.name,
+ mode=PROFILING_MODE_WALL,
+ )
+ with self.assertRaisesRegex(ValueError, "profiling mode"):
+ diff._convert_to_flamegraph_format()
+
  def test_diff_flamegraph_scale_factor(self):
  """Scale factor adjusts when sample counts differ."""
  baseline_frames = [

Misc/NEWS.d/next/Library/2026-07-19-14-00-00.gh-issue-154090.q2kH1b.rst

@@ -0,0 +1,2 @@
+Record the profiling mode in Tachyon binary profiles and reject differential
+comparisons whose known modes do not match.