Flamegraph
diff --git a/Lib/profiling/sampling/heatmap_collector.py b/Lib/profiling/sampling/heatmap_collector.py
index ea1beec70d39f8..5c36d78f5535e7 100644
--- a/Lib/profiling/sampling/heatmap_collector.py
+++ b/Lib/profiling/sampling/heatmap_collector.py
@@ -20,6 +20,7 @@
from .collector import normalize_location, extract_lineno
from .opcode_utils import get_opcode_info, format_opcode
from .stack_collector import StackTraceCollector
+from .module_utils import extract_module_name, get_python_path_info
# ============================================================================
@@ -49,126 +50,6 @@ class TreeNode:
children: Dict[str, 'TreeNode'] = field(default_factory=dict)
-# ============================================================================
-# Module Path Analysis
-# ============================================================================
-
-def get_python_path_info():
- """Get information about Python installation paths for module extraction.
-
- Returns:
- dict: Dictionary containing stdlib path, site-packages paths, and sys.path entries.
- """
- info = {
- 'stdlib': None,
- 'site_packages': [],
- 'sys_path': []
- }
-
- # Get standard library path from os module location
- try:
- if hasattr(os, '__file__') and os.__file__:
- info['stdlib'] = Path(os.__file__).parent
- except (AttributeError, OSError):
- pass # Silently continue if we can't determine stdlib path
-
- # Get site-packages directories
- site_packages = []
- try:
- site_packages.extend(Path(p) for p in site.getsitepackages())
- except (AttributeError, OSError):
- pass # Continue without site packages if unavailable
-
- # Get user site-packages
- try:
- user_site = site.getusersitepackages()
- if user_site and Path(user_site).exists():
- site_packages.append(Path(user_site))
- except (AttributeError, OSError):
- pass # Continue without user site packages
-
- info['site_packages'] = site_packages
- info['sys_path'] = [Path(p) for p in sys.path if p]
-
- return info
-
-
-def extract_module_name(filename, path_info):
- """Extract Python module name and type from file path.
-
- Args:
- filename: Path to the Python file
- path_info: Dictionary from get_python_path_info()
-
- Returns:
- tuple: (module_name, module_type) where module_type is one of:
- 'stdlib', 'site-packages', 'project', or 'other'
- """
- if not filename:
- return ('unknown', 'other')
-
- try:
- file_path = Path(filename)
- except (ValueError, OSError):
- return (str(filename), 'other')
-
- # Check if it's in stdlib
- if path_info['stdlib'] and _is_subpath(file_path, path_info['stdlib']):
- try:
- rel_path = file_path.relative_to(path_info['stdlib'])
- return (_path_to_module(rel_path), 'stdlib')
- except ValueError:
- pass
-
- # Check site-packages
- for site_pkg in path_info['site_packages']:
- if _is_subpath(file_path, site_pkg):
- try:
- rel_path = file_path.relative_to(site_pkg)
- return (_path_to_module(rel_path), 'site-packages')
- except ValueError:
- continue
-
- # Check other sys.path entries (project files)
- if not str(file_path).startswith(('<', '[')): # Skip special files
- for path_entry in path_info['sys_path']:
- if _is_subpath(file_path, path_entry):
- try:
- rel_path = file_path.relative_to(path_entry)
- return (_path_to_module(rel_path), 'project')
- except ValueError:
- continue
-
- # Fallback: just use the filename
- return (_path_to_module(file_path), 'other')
-
-
-def _is_subpath(file_path, parent_path):
- try:
- file_path.relative_to(parent_path)
- return True
- except (ValueError, OSError):
- return False
-
-
-def _path_to_module(path):
- if isinstance(path, str):
- path = Path(path)
-
- # Remove .py extension
- if path.suffix == '.py':
- path = path.with_suffix('')
-
- # Convert path separators to dots
- parts = path.parts
-
- # Handle __init__ files - they represent the package itself
- if parts and parts[-1] == '__init__':
- parts = parts[:-1]
-
- return '.'.join(parts) if parts else path.stem
-
-
# ============================================================================
# Helper Classes
# ============================================================================
diff --git a/Lib/profiling/sampling/module_utils.py b/Lib/profiling/sampling/module_utils.py
new file mode 100644
index 00000000000000..6d838d411902af
--- /dev/null
+++ b/Lib/profiling/sampling/module_utils.py
@@ -0,0 +1,122 @@
+"""Utilities for extracting module names from file paths."""
+
+import os
+import site
+import sys
+from pathlib import Path
+
+
+def get_python_path_info():
+ """Get information about Python's search paths.
+
+ Returns:
+ dict: Dictionary containing stdlib path, site-packages paths, and sys.path entries.
+ """
+ info = {
+ 'stdlib': None,
+ 'site_packages': [],
+ 'sys_path': []
+ }
+
+ # Get standard library path from os module location
+ try:
+ if hasattr(os, '__file__') and os.__file__:
+ info['stdlib'] = Path(os.__file__).parent
+ except (AttributeError, OSError):
+ pass # Silently continue if we can't determine stdlib path
+
+ # Get site-packages directories
+ site_packages = []
+ try:
+ site_packages.extend(Path(p) for p in site.getsitepackages())
+ except (AttributeError, OSError):
+ pass # Continue without site packages if unavailable
+
+ # Get user site-packages
+ try:
+ user_site = site.getusersitepackages()
+ if user_site and Path(user_site).exists():
+ site_packages.append(Path(user_site))
+ except (AttributeError, OSError):
+ pass # Continue without user site packages
+
+ info['site_packages'] = site_packages
+ info['sys_path'] = [Path(p) for p in sys.path if p]
+
+ return info
+
+
+def extract_module_name(filename, path_info):
+ """Extract Python module name and type from file path.
+
+ Args:
+ filename: Path to the Python file
+ path_info: Dictionary from get_python_path_info()
+
+ Returns:
+ tuple: (module_name, module_type) where module_type is one of:
+ 'stdlib', 'site-packages', 'project', or 'other'
+ """
+ if not filename:
+ return ('unknown', 'other')
+
+ try:
+ file_path = Path(filename)
+ except (ValueError, OSError):
+ return (str(filename), 'other')
+
+ # Check if it's in stdlib
+ if path_info['stdlib'] and _is_subpath(file_path, path_info['stdlib']):
+ try:
+ rel_path = file_path.relative_to(path_info['stdlib'])
+ return (_path_to_module(rel_path), 'stdlib')
+ except ValueError:
+ pass
+
+ # Check site-packages
+ for site_pkg in path_info['site_packages']:
+ if _is_subpath(file_path, site_pkg):
+ try:
+ rel_path = file_path.relative_to(site_pkg)
+ return (_path_to_module(rel_path), 'site-packages')
+ except ValueError:
+ continue
+
+ # Check other sys.path entries (project files)
+ if not str(file_path).startswith(('<', '[')): # Skip special files
+ for path_entry in path_info['sys_path']:
+ if _is_subpath(file_path, path_entry):
+ try:
+ rel_path = file_path.relative_to(path_entry)
+ return (_path_to_module(rel_path), 'project')
+ except ValueError:
+ continue
+
+ # Fallback: just use the filename
+ return (_path_to_module(file_path), 'other')
+
+
+def _is_subpath(file_path, parent_path):
+ try:
+ file_path.relative_to(parent_path)
+ return True
+ except (ValueError, OSError):
+ return False
+
+
+def _path_to_module(path):
+ if isinstance(path, str):
+ path = Path(path)
+
+ # Remove .py extension
+ if path.suffix == '.py':
+ path = path.with_suffix('')
+
+ # Convert path separators to dots
+ parts = path.parts
+
+ # Handle __init__ files - they represent the package itself
+ if parts and parts[-1] == '__init__':
+ parts = parts[:-1]
+
+ return '.'.join(parts) if parts else path.stem
diff --git a/Lib/profiling/sampling/stack_collector.py b/Lib/profiling/sampling/stack_collector.py
index 31102d3eb0ffa6..9dffead1777fc1 100644
--- a/Lib/profiling/sampling/stack_collector.py
+++ b/Lib/profiling/sampling/stack_collector.py
@@ -12,6 +12,7 @@
from .collector import Collector, extract_lineno
from .opcode_utils import get_opcode_mapping
from .string_table import StringTable
+from .module_utils import extract_module_name, get_python_path_info
class StackTraceCollector(Collector):
@@ -72,6 +73,7 @@ def __init__(self, *args, **kwargs):
self._sample_count = 0 # Track actual number of samples (not thread traces)
self._func_intern = {}
self._string_table = StringTable()
+ self._module_cache = {}
self._all_threads = set()
# Thread status statistics (similar to LiveStatsCollector)
@@ -182,6 +184,24 @@ def _format_function_name(func):
return f"{funcname} ({filename}:{lineno})"
+ @staticmethod
+ @functools.lru_cache(maxsize=None)
+ def _format_module_name(func, module_name):
+ filename, lineno, funcname = func
+
+ # Special frames like
and should not show file:line
+ if filename == "~" and lineno == 0:
+ return funcname
+
+ return f"{funcname} ({module_name}:{lineno})"
+
+ def _get_module_name(self, filename, path_info):
+ module_name = self._module_cache.get(filename)
+ if module_name is None:
+ module_name, _ = extract_module_name(filename, path_info)
+ self._module_cache[filename] = module_name
+ return module_name
+
def _convert_to_flamegraph_format(self):
if self._total_samples == 0:
return {
@@ -192,7 +212,7 @@ def _convert_to_flamegraph_format(self):
"strings": self._string_table.get_strings()
}
- def convert_children(children, min_samples):
+ def convert_children(children, min_samples, path_info):
out = []
for func, node in children.items():
samples = node["samples"]
@@ -202,13 +222,19 @@ def convert_children(children, min_samples):
# Intern all string components for maximum efficiency
filename_idx = self._string_table.intern(func[0])
funcname_idx = self._string_table.intern(func[2])
+ module_name = self._get_module_name(func[0], path_info)
+
+ module_idx = self._string_table.intern(module_name)
name_idx = self._string_table.intern(self._format_function_name(func))
+ label_idx = self._string_table.intern(self._format_module_name(func, module_name))
child_entry = {
"name": name_idx,
+ "label": label_idx,
"value": samples,
"children": [],
"filename": filename_idx,
+ "module": module_idx,
"lineno": func[1],
"funcname": funcname_idx,
"threads": sorted(list(node.get("threads", set()))),
@@ -227,7 +253,7 @@ def convert_children(children, min_samples):
# Recurse
child_entry["children"] = convert_children(
- node["children"], min_samples
+ node["children"], min_samples, path_info
)
out.append(child_entry)
@@ -238,8 +264,9 @@ def convert_children(children, min_samples):
# Filter out very small functions (less than 0.1% of total samples)
total_samples = self._total_samples
min_samples = max(1, int(total_samples * 0.001))
+ path_info = get_python_path_info()
- root_children = convert_children(self._root["children"], min_samples)
+ root_children = convert_children(self._root["children"], min_samples, path_info)
if not root_children:
return {
"name": self._string_table.intern("No significant data"),
diff --git a/Lib/test/test_profiling/test_sampling_profiler/test_collectors.py b/Lib/test/test_profiling/test_sampling_profiler/test_collectors.py
index 86fb9d4c05b3bc..d087e157f2dfea 100644
--- a/Lib/test/test_profiling/test_sampling_profiler/test_collectors.py
+++ b/Lib/test/test_profiling/test_sampling_profiler/test_collectors.py
@@ -435,7 +435,7 @@ def test_flamegraph_collector_basic(self):
strings = data.get("strings", [])
name = resolve_name(data, strings)
self.assertTrue(name.startswith("Program Root: "))
- self.assertIn("func2 (file.py:20)", name) # formatted name
+ self.assertIn("func2 (file.py:20)", name)
children = data.get("children", [])
self.assertEqual(len(children), 1)
child = children[0]