gh-138122: Add differential flame graph

Doc/library/profiling.sampling.rst

@@ -1003,6 +1003,47 @@ at the top indicate functions that consume significant time either directly
 or through their callees.
 
 
+Differential flame graphs
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Differential flame graphs compare two profiling runs to highlight where
+performance changed. This helps identify regressions introduced by code changes
+and validate that optimizations achieved their intended effect::
+
+ # Capture baseline profile
+ python -m profiling.sampling run --binary -o baseline.bin script.py
+
+ # After modifying code, generate differential flamegraph
+ python -m profiling.sampling run --diff-flamegraph baseline.bin -o diff.html script.py
+
+The visualization draws the current profile with frame widths showing current
+time consumption, then applies color to indicate how each function changed
+relative to the baseline.
+
+**Color coding**:
+
+- **Red**: Functions consuming more time (regressions). Lighter shades indicate
+ modest increases, while darker shades show severe regressions.
+
+- **Blue**: Functions consuming less time (improvements). Lighter shades for
+ modest reductions, darker shades for significant speedups.
+
+- **Gray**: Minimal or no change.
+
+- **Purple**: New functions not present in the baseline.
+
+Frame colors indicate changes in **direct time** (time when the function was at
+the top of the stack, actively executing), not cumulative time including callees.
+Hovering over a frame shows comparison details including baseline time, current
+time, and the percentage change.
+
+Some call paths may disappear entirely between profiles. These are called
+**elided stacks** and occur when optimizations eliminate code paths or certain
+branches stop executing. If elided stacks are present, an elided toggle appears
+allowing you to switch between the main differential view and an elided-only
+view that shows just the removed paths (colored purple).
+
+
 Gecko format
 ------------
 
@@ -1488,6 +1529,10 @@ Output options
 
  Generate self-contained HTML flame graph.
 
+.. option:: --diff-flamegraph <baseline.bin>
+
+ Generate differential flamegraph comparing to a baseline binary profile.
+
 .. option:: --gecko
 
  Generate Gecko JSON format for Firefox Profiler.

Lib/profiling/sampling/_flamegraph_assets/flamegraph.css

@@ -5,6 +5,46 @@
  This file extends the shared foundation with flamegraph-specific styles.
  ========================================================================== */
 
+/* --------------------------------------------------------------------------
+ Differential Flamegraph
+ -------------------------------------------------------------------------- */
+
+:root {
+ /* Regression colors */
+ --diff-regression-deep: #d32f2f;
+ --diff-regression-medium: #e57373;
+ --diff-regression-light: #ef9a9a;
+ --diff-regression-verylight: #ffcdd2;
+
+ /* Improvement colors */
+ --diff-improvement-deep: #1976d2;
+ --diff-improvement-medium: #42a5f5;
+ --diff-improvement-light: #64b5f6;
+ --diff-improvement-verylight: #90caf9;
+
+ /* Other differential colors */
+ --diff-neutral: #bdbdbd;
+ --diff-new: #9575cd;
+ --diff-elided: #b39ddb;
+}
+
+/* Dark mode differential colors - adjusted for contrast against dark backgrounds */
+[data-theme="dark"] {
+ --diff-regression-deep: #ef5350;
+ --diff-regression-medium: #e57373;
+ --diff-regression-light: #ef9a9a;
+ --diff-regression-verylight: #ffcdd2;
+
+ --diff-improvement-deep: #42a5f5;
+ --diff-improvement-medium: #64b5f6;
+ --diff-improvement-light: #90caf9;
+ --diff-improvement-verylight: #bbdefb;
+
+ --diff-neutral: #757575;
+ --diff-new: #b39ddb;
+ --diff-elided: #ce93d8;
+}
+
 /* --------------------------------------------------------------------------
  Layout Overrides (Flamegraph-specific)
  -------------------------------------------------------------------------- */
@@ -277,7 +317,9 @@ body.resizing-sidebar {
 /* View Mode Section */
 .view-mode-section .section-content {
  display: flex;
- justify-content: center;
+ flex-direction: column;
+ gap: 10px;
+ align-items: center;
 }
 
 /* Collapsible sections */
@@ -815,6 +857,41 @@ body.resizing-sidebar {
  color: var(--accent);
 }
 
+.tooltip-diff {
+ margin-top: 12px;
+ padding-top: 12px;
+ border-top: 1px solid var(--border);
+}
+
+.tooltip-diff-title {
+ font-size: 11px;
+ font-weight: 600;
+ color: var(--accent);
+ margin-bottom: 8px;
+}
+
+.tooltip-diff-row {
+ display: grid;
+ grid-template-columns: auto 1fr;
+ gap: 4px 14px;
+ font-size: 12px;
+ margin-bottom: 4px;
+}
+
+.tooltip-diff-row.regression .tooltip-stat-value {
+ color: var(--diff-regression-deep);
+ font-weight: 700;
+}
+
+.tooltip-diff-row.improvement .tooltip-stat-value {
+ color: var(--diff-improvement-deep);
+ font-weight: 700;
+}
+
+.tooltip-diff-row.neutral .tooltip-stat-value {
+ color: var(--text-secondary);
+}
+
 .tooltip-source {
  margin-top: 10px;
  padding-top: 10px;
@@ -989,7 +1066,8 @@ body.resizing-sidebar {
  Flamegraph-Specific Toggle Override
  -------------------------------------------------------------------------- */
 
-#toggle-invert .toggle-track.on {
+#toggle-invert .toggle-track.on,
+#toggle-elided .toggle-track.on {
  background: #8e44ad;
  border-color: #8e44ad;
  box-shadow: 0 0 8px rgba(142, 68, 173, 0.3);