Split the GC summary into ratio and count tables

With Ractor GC data, the comparison GC summary was over 250 characters
wide.

This commit splits it into a GC time ratios table and a GC counts
table. The "ratio" and "worker sum" labels move out of the column
headers and into the table titles. Columns with no data in any row are
hidden and listed under the table.

global/iter is now shown as a count instead of a ratio. It's a GC
count, and the legend says the ratios are GC time.

Author: eightbitraptor

README.md

@@ -411,15 +411,21 @@ Ractor's own object space. The JSON output records the scope as
 `gc_scope: "ractor-local-workload"`, `gc_stat_scope: "ractor-local"`, and
 `gc_measure_total_time_scope: "ractor-local"`, plus the target's `gc_config`.
 
-The summary table adds these columns:
-
-* `(worker sum)` columns add the Ractor-local counters of the sampled
-  workers of each iteration. `GCs/iter` is the sum of `minor/iter`,
+The text summary shows GC data in separate tables after the timing table.
+A single-executable report has one `GC summary` table. A comparison report
+has a `GC time ratios` table (base/comparison) and a `GC counts` table
+(base → comparison). A table hides a column that has no data in any row and
+lists the hidden columns below the table. A ratio column has no data when it
+is `N/A` in every row; a `0.000` ratio stays visible. Any other column has no
+data when it is zero or `N/A` in every row.
+
+* Tables marked `worker sum` add the Ractor-local counters and GC times of
+  the sampled workers of each iteration. `GCs/iter` is the sum of `minor/iter`,
   `major/iter`, and `global/iter`; a global cycle counts under `global` on
   the Ractor that initiated it, not under `major`. Single-executable reports
   also show `GC ms/worker`, which divides each iteration's worker-sum GC
   time by its sampled worker count, then averages.
-* `controller compacts/iter*` shows the main Ractor's
+* `compacts*` shows the main Ractor's
   `GC.stat(:compact_count)` delta. Every global compacting cycle increments
   it in every object space, so it is not summed across workers.
 

lib/benchmark_runner.rb

@@ -59,7 +59,7 @@ def write_csv(output_path, ruby_descriptions, table)
     end
 
     # Build output text string with metadata, table, and legend
-    def build_output_text(ruby_descriptions, table, format, bench_failures, include_rss: false, include_gc: false, include_pvalue: false, gc_table: nil, gc_format: nil, sections: nil, ruby_bench_revision: nil)
+    def build_output_text(ruby_descriptions, table, format, bench_failures, include_rss: false, include_gc: false, include_pvalue: false, gc_tables: nil, sections: nil, ruby_bench_revision: nil)
       base_name, *other_names = ruby_descriptions.keys
 
       output_str = +""
@@ -70,16 +70,23 @@ def build_output_text(ruby_descriptions, table, format, bench_failures, include_
       output_str << "ruby-bench: #{ruby_bench_revision}\n" if ruby_bench_revision
 
       output_str << "\n"
-      sections ||= [{ table: table, format: format, failures: bench_failures, include_gc: include_gc, gc_table: gc_table, gc_format: gc_format }]
-      has_gc_summary = sections.any? { |section| section[:include_gc] && section[:gc_table] }
+      sections ||= [{ table: table, format: format, failures: bench_failures, include_gc: include_gc, gc_tables: gc_tables }]
+      has_gc_summary = sections.any? { |section| section[:include_gc] && section[:gc_tables] }
       sections.each do |section|
         title = section[:title]
         output_str << "#{title}:\n" if title
         output_str << TableFormatter.new(section[:table], section[:format], section.fetch(:failures, {})).to_s + "\n"
 
-        if section[:include_gc] && section[:gc_table] && section[:gc_format]
-          output_str << (title ? "GC summary (#{title}):\n" : "GC summary:\n")
-          output_str << TableFormatter.new(section[:gc_table], section[:gc_format], {}).to_s + "\n"
+        next unless section[:include_gc] && section[:gc_tables]
+
+        section[:gc_tables].each do |gc_table|
+          qualifiers = [gc_table[:scope], title].compact
+          output_str << gc_table[:name]
+          output_str << " (#{qualifiers.join(', ')})" unless qualifiers.empty?
+          output_str << ":\n"
+          output_str << TableFormatter.new(gc_table[:rows], Array.new(gc_table[:rows].first.size, "%s"), {}).to_s
+          output_str << "Hidden columns (zero or N/A in every row): #{gc_table[:hidden].join(', ')}\n" unless gc_table[:hidden].empty?
+          output_str << "\n"
         end
       end
 
@@ -93,30 +100,30 @@ def build_output_text(ruby_descriptions, table, format, bench_failures, include_
           end
         end
         if has_gc_summary
-          output_str << "- GC summary compares #{base_name} → comparison. Ratio columns are #{base_name}/comparison; above 1 means the comparison spent less GC time.\n"
-          output_str << "- gc/iter, mark/iter, and sweep/iter ratio compare total GC (or phase) time per benchmark iteration, so they include both per-GC cost and GC frequency changes.\n"
-          output_str << "- gc/GC, mark/GC, and sweep/GC ratio divide average GC (or phase) time by the same run's GCs/iter count; they are not complete per-cycle attribution of process-wide GC.\n"
-          output_str << "- GCs/iter, major/iter, minor/iter, controller compacts/iter*, and minor GC % show #{base_name} → comparison values, not ratios. Rows with no GC activity are omitted.\n"
+          output_str << "- GC time ratios are #{base_name}/comparison; above 1 means the comparison spent less GC time.\n"
+          output_str << "- gc/iter, mark/iter, and sweep/iter compare total GC (or phase) time per benchmark iteration, so they include both per-GC cost and GC frequency changes.\n"
+          output_str << "- gc/GC, mark/GC, and sweep/GC divide average GC (or phase) time by the same run's GCs/iter count; they are not complete per-cycle attribution of process-wide GC.\n"
+          output_str << "- GC counts show #{base_name} → comparison values, not ratios. Rows with no GC activity are omitted.\n"
         end
         if include_pvalue
           output_str << "- ***: p < 0.001, **: p < 0.01, *: p < 0.05 (Welch's t-test)\n"
         end
       end
-      gc_headers = sections.filter_map { |section| section[:gc_table]&.first }.flatten
-      if gc_headers.include?('controller compacts/iter*')
+      gc_headers = sections.flat_map { |section| Array(section[:gc_tables]).flat_map { |gc_table| gc_table[:rows].first } }
+      if gc_headers.include?('compacts*')
         output_str << "GC metric notes:\n"
-        output_str << "- controller compacts/iter*: the main Ractor's GC.stat(:compact_count) delta per iteration. Every global compacting cycle increments compact_count in every object space. Do not sum it across workers.#{other_names.empty? ? '' : " Comparison tables show #{base_name} → comparison values."}\n"
+        output_str << "- compacts*: the main Ractor's GC.stat(:compact_count) delta per iteration. Every global compacting cycle increments compact_count in every object space. Do not sum it across workers.#{other_names.empty? ? '' : " Comparison tables show #{base_name} → comparison values."}\n"
       end
 
-      ractor_gc_sections = sections.select { |section| section[:gc_scope] == 'ractor-local-workload' && section[:gc_table] }
+      ractor_gc_sections = sections.select { |section| section[:gc_scope] == 'ractor-local-workload' && section[:gc_tables] }
       unless ractor_gc_sections.empty?
         modes = ractor_gc_sections.flat_map { |section| section.fetch(:ractor_gc_modes, []) }
         worker_mode = modes.include?(:worker)
         output_str << "Ractor GC scope note:\n"
-        scope_columns = +"- (worker sum) columns add Ractor-local counters across the sampled workers of each iteration"
+        scope_columns = +"- Tables marked worker sum add Ractor-local counters and GC times across the sampled workers of each iteration"
         scope_columns << (worker_mode ? "; the main Ractor performs the count-0 workload of per-worker benchmarks." : ".")
         scope_columns << " GC ms/worker divides each iteration's worker-sum GC time by its sampled worker count, then averages." if other_names.empty?
-        output_str << "#{scope_columns} Controller snapshots and per-worker heap detail are in the JSON output, not this table.\n"
+        output_str << "#{scope_columns} Controller snapshots and per-worker heap detail are in the JSON output, not these tables.\n"
         output_str << "- Ruby's Ractor-retirement GC (after a worker's stack is torn down) is not sampled."
         output_str << " Ractors created by the workload of a per-worker benchmark are not sampled." if worker_mode
         output_str << "\n"

lib/benchmark_runner/cli.rb

@@ -125,7 +125,7 @@ def run
         zjit_stats: args.zjit_stats,
         row_layout: csv_layout
       )
-      table, format, gc_table, gc_format = builder.build
+      table, format, gc_tables = builder.build
 
       output_path = BenchmarkRunner.output_path(args.out_path, out_override: args.out_override)
 
@@ -139,7 +139,7 @@ def run
 
       # Save the output in a text file that we can easily refer to
       output_sections = build_output_sections(ruby_descriptions.keys, bench_data, bench_harnesses, bench_failures)
-      output_str = BenchmarkRunner.build_output_text(ruby_descriptions, table, format, bench_failures, include_rss: args.rss, include_gc: builder.include_gc?, include_pvalue: args.pvalue, gc_table: gc_table, gc_format: gc_format, sections: output_sections, ruby_bench_revision: ruby_bench_revision)
+      output_str = BenchmarkRunner.build_output_text(ruby_descriptions, table, format, bench_failures, include_rss: args.rss, include_gc: builder.include_gc?, include_pvalue: args.pvalue, gc_tables: gc_tables, sections: output_sections, ruby_bench_revision: ruby_bench_revision)
       out_txt_path = output_path + ".txt"
       File.open(out_txt_path, "w") { |f| f.write output_str }
 
@@ -208,16 +208,15 @@ def build_output_section(executable_names, bench_data, bench_failures, harness,
         zjit_stats: args.zjit_stats,
         row_layout: layout
       )
-      table, format, gc_table, gc_format = builder.build
+      table, format, gc_tables = builder.build
 
       section = {
         title: harness,
         table: table,
         format: format,
         failures: slice_failures(bench_failures, bench_names),
         include_gc: builder.include_gc?,
-        gc_table: gc_table,
-        gc_format: gc_format,
+        gc_tables: gc_tables,
       }
       if ResultsTableBuilder.ractor_gc_data?(section_data)
         section[:gc_scope] = 'ractor-local-workload'

lib/results_table_builder.rb

@@ -42,9 +42,7 @@ def build
       table << (entry.label_cells + build_stat_cells(entry.data_key))
     end
 
-    gc_table = build_gc_summary_table
-
-    [table, format, gc_table, build_gc_summary_format(gc_table)]
+    [table, format, build_gc_tables]
   end
 
   private
@@ -122,26 +120,18 @@ def build_format
     gc_controller_compact_count_bench
   ].freeze
 
-  def build_gc_summary_table
+  def build_gc_tables
     return nil unless @include_gc
 
-    label_columns = ["bench", *@row_layout.extra_header_columns]
-
-    if @other_names.empty?
-      return build_gc_absolute_table(label_columns)
-    end
-
-    count_suffix = ractor_gc_table? ? " (worker sum)" : ""
-
-    header = label_columns + (include_gc_comparison_name? ? ["comparison"] : [])
-    header += ["gc/iter ratio", "gc/GC ratio"] if include_gc_total_time?
-    header += ["mark/iter ratio", "sweep/iter ratio", "mark/GC ratio", "sweep/GC ratio"]
-    header << "global/iter ratio" if gc_series_present?('gc_global_count_bench')
-    header << "GCs/iter#{count_suffix}" << "major/iter#{count_suffix}" << "minor/iter#{count_suffix}"
-    header << "controller compacts/iter*" if gc_series_present?('gc_controller_compact_count_bench')
-    header << "minor GC %"
+    label_header = ["bench", *@row_layout.extra_header_columns]
+    tables = @other_names.empty? ? [build_gc_absolute_table(label_header)] : build_gc_comparison_tables(label_header)
+    tables.compact!
+    tables.empty? ? nil : tables
+  end
 
-    rows = [header]
+  def build_gc_comparison_tables(label_header)
+    label_header += ["comparison"] if include_gc_comparison_name?
+    rows = []
     gc_entries.each do |entry|
       series_by_exe = @executable_names.map do |name|
         data = bench_data_for(name, entry.data_key)
@@ -161,44 +151,118 @@ def build_gc_summary_table
       others.each_with_index do |other, i|
         next unless gc_activity?(*base.values, *other.values)
 
-        rows << gc_summary_row(gc_label_cells(entry), @other_names[i], base, other)
+        labels = gc_label_cells(entry)
+        labels << @other_names[i] if include_gc_comparison_name?
+        rows << [labels, [base, other]]
       end
     end
 
-    rows.size == 1 ? nil : rows
+    [
+      assemble_gc_table("GC time ratios", label_header, rows, gc_ratio_columns),
+      assemble_gc_table("GC counts", label_header, rows, gc_count_columns),
+    ]
   end
 
-  def build_gc_absolute_table(label_columns)
-    ractor = ractor_gc_table?
-    count_suffix = ractor ? " (worker sum)" : ""
-
-    header = label_columns + ["GC ms/iter#{count_suffix}"]
-    header << "GC ms/worker" if ractor
-    header += ["mark ms/iter#{count_suffix}", "sweep ms/iter#{count_suffix}", "GCs/iter#{count_suffix}", "major/iter#{count_suffix}", "minor/iter#{count_suffix}"]
-    header << "global/iter#{count_suffix}" if gc_series_present?('gc_global_count_bench')
-    header << "controller compacts/iter*" if gc_series_present?('gc_controller_compact_count_bench')
+  def gc_ratio_columns
+    columns = []
+    if include_gc_total_time?
+      columns << ["gc/iter", ->(base, other) { ratio_cell(gc_ratio(base[:total], other[:total])) }]
+      columns << ["gc/GC", ->(base, other) { ratio_cell(per_gc_ratio(base, other, :total)) }]
+    end
+    columns << ["mark/iter", ->(base, other) { ratio_cell(gc_ratio(base[:mark], other[:mark])) }]
+    columns << ["sweep/iter", ->(base, other) { ratio_cell(gc_ratio(base[:sweep], other[:sweep])) }]
+    columns << ["mark/GC", ->(base, other) { ratio_cell(per_gc_ratio(base, other, :mark)) }]
+    columns << ["sweep/GC", ->(base, other) { ratio_cell(per_gc_ratio(base, other, :sweep)) }]
+    columns
+  end
 
-    rows = [header]
+  def gc_count_columns
+    columns = [
+      ["GCs/iter", ->(base, other) { count_cell(base[:count], other[:count]) }],
+      ["major/iter", ->(base, other) { count_cell(base[:major], other[:major]) }],
+      ["minor/iter", ->(base, other) { count_cell(base[:minor], other[:minor]) }],
+    ]
+    if gc_series_present?('gc_global_count_bench')
+      columns << ["global/iter", ->(base, other) { count_cell(base[:global], other[:global]) }]
+    end
+    if gc_series_present?('gc_controller_compact_count_bench')
+      columns << ["compacts*", ->(base, other) { count_cell(base[:compact], other[:compact]) }]
+    end
+    columns << ["minor GC %", ->(base, other) { minor_percent_cell(base, other) }]
+    columns
+  end
 
-    gc_entries.each do |entry|
+  def build_gc_absolute_table(label_header)
+    rows = gc_entries.filter_map do |entry|
       data = bench_data_for(@base_name, entry.data_key)
-      next unless GC_SERIES_KEYS.any? { |key| data.key?(key) }
+      [gc_label_cells(entry), [data]] if GC_SERIES_KEYS.any? { |key| data.key?(key) }
+    end
+    assemble_gc_table("GC summary", label_header, rows, gc_absolute_columns)
+  end
 
-      cells = [format_gc_series_mean_precise(data['gc_total_time_bench'])]
-      cells << gc_ms_per_worker_cell(data['gc_total_time_bench'], data['gc_worker_samples']) if ractor
-      cells += [
-        format_gc_series_mean_precise(data['gc_marking_time_bench']),
-        format_gc_series_mean_precise(data['gc_sweeping_time_bench']),
-        format_gc_series_mean(gc_count_series(data)),
-        format_gc_series_mean(data['gc_major_count_bench']),
-        format_gc_series_mean(data['gc_minor_count_bench']),
-      ]
-      cells << format_gc_series_mean(data['gc_global_count_bench']) if gc_series_present?('gc_global_count_bench')
-      cells << format_gc_series_mean(data['gc_controller_compact_count_bench']) if gc_series_present?('gc_controller_compact_count_bench')
-      rows << gc_label_cells(entry) + cells
+  def gc_absolute_columns
+    columns = [["GC ms/iter", ->(data) { mean_cell(data['gc_total_time_bench'], precise: true) }]]
+    columns << ["GC ms/worker", ->(data) { ms_per_worker_cell(data) }] if ractor_gc_table?
+    columns += [
+      ["mark ms/iter", ->(data) { mean_cell(data['gc_marking_time_bench'], precise: true) }],
+      ["sweep ms/iter", ->(data) { mean_cell(data['gc_sweeping_time_bench'], precise: true) }],
+      ["GCs/iter", ->(data) { mean_cell(gc_count_series(data)) }],
+      ["major/iter", ->(data) { mean_cell(data['gc_major_count_bench']) }],
+      ["minor/iter", ->(data) { mean_cell(data['gc_minor_count_bench']) }],
+    ]
+    if gc_series_present?('gc_global_count_bench')
+      columns << ["global/iter", ->(data) { mean_cell(data['gc_global_count_bench']) }]
+    end
+    if gc_series_present?('gc_controller_compact_count_bench')
+      columns << ["compacts*", ->(data) { mean_cell(data['gc_controller_compact_count_bench']) }]
     end
+    columns
+  end
+
+  def assemble_gc_table(name, label_header, rows, columns)
+    return nil if rows.empty?
 
-    rows.size == 1 ? nil : rows
+    cells = rows.map { |(_labels, args)| columns.map { |(_header, cell)| cell.call(*args) } }
+    shown = columns.each_index.select { |i| cells.any? { |row_cells| row_cells[i][1] } }
+
+    body = rows.each_with_index.map { |(labels, _args), r| labels + shown.map { |i| cells[r][i][0] } }
+    {
+      name: name,
+      scope: ractor_gc_table? ? "worker sum" : nil,
+      rows: [label_header + shown.map { |i| columns[i][0] }] + body,
+      hidden: (columns.each_index.to_a - shown).map { |i| columns[i][0] },
+    }
+  end
+
+  def ratio_cell(text)
+    [text, text != "N/A"]
+  end
+
+  def count_cell(base, other)
+    [gc_count_cell(base, other), mean_positive?(base) || mean_positive?(other)]
+  end
+
+  def minor_percent_cell(base, other)
+    data = [gc_minor_percent(base[:minor], base[:count]), gc_minor_percent(other[:minor], other[:count])].any? { |pct| pct&.positive? }
+    [gc_minor_percent_cell(base, other), data]
+  end
+
+  def mean_cell(values, precise: false)
+    text = precise ? format_gc_series_mean_precise(values) : format_gc_series_mean(values)
+    [text, mean_positive?(values)]
+  end
+
+  def ms_per_worker_cell(data)
+    text = gc_ms_per_worker_cell(data['gc_total_time_bench'], data['gc_worker_samples'])
+    [text, text != "N/A" && mean_positive?(data['gc_total_time_bench'])]
+  end
+
+  def mean_positive?(values)
+    numeric_series?(values) && mean(values) > 0.0
+  end
+
+  def per_gc_ratio(base, other, key)
+    scalar_ratio(gc_time_per_gc(base[key], base[:count]), gc_time_per_gc(other[key], other[:count]))
   end
 
   def gc_series_present?(key)
@@ -233,12 +297,6 @@ def include_gc_total_time?
     end
   end
 
-  def build_gc_summary_format(gc_table)
-    return nil unless gc_table
-
-    Array.new(gc_table.first.size, "%s")
-  end
-
   def build_stat_cells(bench_name)
     t0s = extract_first_iteration_times(bench_name)
     times_no_warmup = extract_benchmark_times(bench_name)
@@ -316,26 +374,6 @@ def include_gc_comparison_name?
     @other_names.size > 1
   end
 
-  def gc_summary_row(label_cells, name, base, other)
-    row = label_cells
-    row << name if include_gc_comparison_name?
-    if include_gc_total_time?
-      row << gc_ratio(base[:total], other[:total])
-      row << scalar_ratio(gc_time_per_gc(base[:total], base[:count]), gc_time_per_gc(other[:total], other[:count]))
-    end
-    row << gc_ratio(base[:mark], other[:mark])
-    row << gc_ratio(base[:sweep], other[:sweep])
-    row << scalar_ratio(gc_time_per_gc(base[:mark], base[:count]), gc_time_per_gc(other[:mark], other[:count]))
-    row << scalar_ratio(gc_time_per_gc(base[:sweep], base[:count]), gc_time_per_gc(other[:sweep], other[:count]))
-    row << gc_ratio(base[:global], other[:global]) if gc_series_present?('gc_global_count_bench')
-    row << gc_count_cell(base[:count], other[:count])
-    row << gc_count_cell(base[:major], other[:major])
-    row << gc_count_cell(base[:minor], other[:minor])
-    row << gc_count_cell(base[:compact], other[:compact]) if gc_series_present?('gc_controller_compact_count_bench')
-    row << gc_minor_percent_cell(base, other)
-    row
-  end
-
   def numeric_series?(values)
     values.is_a?(Array) && !values.empty? && values.all? { |v| v.is_a?(Numeric) }
   end