Tools/Scripts/analyze-ftime-trace - external/github.com/WebKit/webkit - Git at Google

 #!/usr/bin/env python3
 #
 # Copyright (C) 2026 Apple Inc. All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions
 # are met:
 # 1. Redistributions of source code must retain the above copyright
 #    notice, this list of conditions and the following disclaimer.
 # 2. Redistributions in binary form must reproduce the above copyright
 #    notice, this list of conditions and the following disclaimer in the
 #    documentation and/or other materials provided with the distribution.
 #
 # THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
 # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 # THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 # PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
 # BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
 # THE POSSIBILITY OF SUCH DAMAGE.

 """Analyze -ftime-trace JSON files from a WebKit build.

 Companion to ClangBuildAnalyzer (CBA). Both tools consume the same -ftime-trace
 JSON files. This script overlaps with CBA in several areas but adds exclusive
 (self) time analysis for headers, which CBA does not provide.

 Comparison with ClangBuildAnalyzer
 ----------------------------------
 Matching sections (numbers align closely):
   --slowest-tu   <->  CBA "Files that took longest to parse/codegen"
   --templates    <->  CBA "Templates that took longest to instantiate"
   --summary      <->  CBA "Time summary"

 Differences:
   - Template sets: this script counts all instantiations; CBA filters by a
     minimum duration threshold, so our totals run higher for high-frequency /
     low-cost templates.
   - Functions: this script sums both CodeGen Function and OptFunction events;
     CBA uses CodeGen Function only.

 Unique to this script (not in CBA):
   - Exclusive (self) header parse time: the default mode computes both
     inclusive and exclusive time per header, revealing where parse time is
     actually spent vs. merely transited through an include chain. This is the
     primary reason the script exists.
   - --trace-header: drill into the include nesting of a specific header in a
     single TU.
   - --filter: restrict header output to names matching a substring.

 Unique to CBA (not replicated here):
   - Include-chain visualisation ("included via: ...") showing the N most
     common paths through which an expensive header is pulled in.
   - Binary format capture file (faster repeated analysis).

 Implementation note -- event ordering
 --------------------------------------
 clang's -ftime-trace JSON does NOT guarantee events are sorted by timestamp.
 Source events use begin/end pairs (ph: "b" / "e") that nest as a stack, but
 the pairs can appear in arbitrary order in the array. This script sorts Source
 events by timestamp before processing to reconstruct the correct nesting. An
 earlier version of this script did not sort, which produced incorrect exclusive
 times (every header appeared to have inclusive == exclusive).

 Usage:
     analyze-ftime-trace <trace-dir> [options]

 The trace directory should contain .json files produced by clang's -ftime-trace
 flag (searched recursively), typically found at:
     WebKitBuild/WebCore.build/Release/WebCore.build/Objects-normal/arm64e/
 or for CMake builds:
     WebKitBuild/cmake-mac/Release/Source/WebCore/CMakeFiles/WebCore.dir/

 Examples:
     # Show top 30 headers by exclusive (self) parse time
     analyze-ftime-trace <dir>

     # Show top 50 headers
     analyze-ftime-trace <dir> --top 50

     # Filter to headers matching a pattern
     analyze-ftime-trace <dir> --filter RenderStyle

     # Show template instantiation hotspots
     analyze-ftime-trace <dir> --templates

     # Show functions that took longest to compile
     analyze-ftime-trace <dir> --functions

     # Show TUs that took longest to compile
     analyze-ftime-trace <dir> --slowest-tu

     # Show detailed nesting for a specific header in one TU
     analyze-ftime-trace <dir> --trace-header StyleComputedStyleBase+GettersInlines.h --tu UnifiedSource500

     # Show overall build time breakdown
     analyze-ftime-trace <dir> --summary

     # Show top event categories (ParseClass, InstantiateFunction, etc.)
     analyze-ftime-trace <dir> --categories
 """

 import argparse
 import json
 import glob
 import os
 import re
 import sys


 def load_trace(path):
     """Load a -ftime-trace JSON file, returning its event list."""
     with open(path) as f:
         data = json.load(f)
     events = data if isinstance(data, list) else data.get("traceEvents", [])
     # Guard against non-ftime-trace JSON files that happen to be lists.
     if events and not isinstance(events[0], dict):
         return []
     return events


 def compute_header_times(trace_dir, header_filter=None):
     """Compute inclusive and exclusive (self) time per header across all TUs.

     Returns (inclusive, exclusive, tu_count) dicts keyed by header basename.
     Times are in microseconds.
     """
     files = sorted(glob.glob(os.path.join(trace_dir, "**", "*.json"), recursive=True))

     inclusive = {}
     exclusive = {}
     tu_count = {}

     for f in files:
         try:
             events = load_trace(f)
         except Exception:
             continue

         # Source events use begin/end pairs (ph: b/e) that nest as a stack.
         # IMPORTANT: Events in the JSON are NOT necessarily sorted by timestamp.
         # We must sort Source events by timestamp for correct stack-based nesting.
         source_events = sorted(
             [e for e in events if e.get("name") == "Source"],
             key=lambda e: e["ts"],
         )

         stack = []  # (ts_begin, header_basename, child_time_accum)

         for evt in source_events:
             ph = evt.get("ph")

             if ph == "b":
                 detail = evt.get("args", {}).get("detail", "")
                 basename = detail.rsplit("/", 1)[-1] if "/" in detail else detail
                 stack.append((evt["ts"], basename, 0))
             elif ph == "e" and stack:
                 ts_begin, basename, child_time = stack.pop()
                 dur = evt["ts"] - ts_begin
                 excl = dur - child_time

                 if header_filter is None or header_filter in basename:
                     inclusive[basename] = inclusive.get(basename, 0) + dur
                     exclusive[basename] = exclusive.get(basename, 0) + excl
                     tu_count[basename] = tu_count.get(basename, 0) + 1

                 if stack:
                     p_ts, p_name, p_child = stack[-1]
                     stack[-1] = (p_ts, p_name, p_child + dur)

     return inclusive, exclusive, tu_count


 def print_header_table(inclusive, exclusive, tu_count, top_n=30):
     """Print a formatted table of header parse times."""
     fmt_header = f"{'Header':<65} {'Inclusive':>10} {'Exclusive':>10} {'TUs':>6} {'Excl/TU':>10}"
     fmt_units = f"{'':65s} {'(min)':>10} {'(min)':>10} {'':>6} {'(ms)':>10}"
     sep = "-" * 105

     print(fmt_header)
     print(fmt_units)
     print(sep)

     for h in sorted(exclusive.keys(), key=lambda x: -exclusive[x])[:top_n]:
         inc_min = inclusive.get(h, 0) / 60_000_000
         exc_min = exclusive.get(h, 0) / 60_000_000
         tus = tu_count.get(h, 0)
         per_tu_ms = exclusive.get(h, 0) / tus / 1000 if tus else 0
         print(f"{h:<65} {inc_min:>10.1f} {exc_min:>10.1f} {tus:>6} {per_tu_ms:>10.1f}")

     print(sep)
     total_exc = sum(exclusive.values()) / 60_000_000
     total_inc = sum(inclusive.values()) / 60_000_000
     print(f"{'Total (all matched headers)':<65} {total_inc:>10.1f} {total_exc:>10.1f}")


 def print_summary(trace_dir):
     """Print overall build time breakdown."""
     files = sorted(glob.glob(os.path.join(trace_dir, "**", "*.json"), recursive=True))

     totals = {}
     tu_count = 0

     for f in files:
         try:
             events = load_trace(f)
         except Exception:
             continue
         tu_count += 1
         for evt in events:
             name = evt.get("name", "")
             dur = evt.get("dur", 0)
             if name.startswith("Total ") or name in ("ExecuteCompiler", "Frontend", "Backend", "Optimizer"):
                 totals[name] = totals.get(name, 0) + dur

     print(f"Translation units: {tu_count}")
     print()
     print(f"{'Category':<55} {'Cumulative':>12}")
     print(f"{'':55s} {'(min)':>12}")
     print("-" * 70)
     for name in sorted(totals.keys(), key=lambda x: -totals[x])[:30]:
         print(f"{name:<55} {totals[name] / 60_000_000:>12.1f}")


 def print_categories(trace_dir, top_n=30):
     """Print top event categories by cumulative time."""
     files = sorted(glob.glob(os.path.join(trace_dir, "**", "*.json"), recursive=True))

     totals = {}

     for f in files:
         try:
             events = load_trace(f)
         except Exception:
             continue
         for evt in events:
             name = evt.get("name", "")
             dur = evt.get("dur", 0)
             if name.startswith("Total ") and dur > 0:
                 totals[name] = totals.get(name, 0) + dur

     print(f"{'Category':<65} {'Cumulative':>12}")
     print(f"{'':65s} {'(min)':>12}")
     print("-" * 80)
     for name in sorted(totals.keys(), key=lambda x: -totals[x])[:top_n]:
         print(f"{name:<65} {totals[name] / 60_000_000:>12.1f}")


 def trace_header_in_tu(trace_dir, header_name, tu_name):
     """Show detailed nesting for a specific header in a specific TU."""
     # Try flat path first, then search recursively for CMake-style layouts.
     tu_path = os.path.join(trace_dir, tu_name + ".json")
     if not os.path.exists(tu_path):
         matches = glob.glob(os.path.join(trace_dir, "**", tu_name + ".json"), recursive=True)
         if not matches:
             print(f"Error: {tu_name}.json not found under {trace_dir}", file=sys.stderr)
             sys.exit(1)
         tu_path = matches[0]

     events = load_trace(tu_path)

     # Sort Source events by timestamp for correct nesting.
     source_events = sorted(
         [e for e in events if e.get("name") == "Source"],
         key=lambda e: e["ts"],
     )

     in_target = False
     target_depth = 0
     stack = []

     for evt in source_events:
         ph = evt.get("ph")

         if ph == "b":
             detail = evt.get("args", {}).get("detail", "")
             basename = detail.rsplit("/", 1)[-1] if "/" in detail else detail
             stack.append((evt["ts"], basename, detail))

             if header_name in basename and not in_target:
                 in_target = True
                 target_depth = len(stack)
                 indent = "  " * (len(stack) - target_depth)
                 print(f"{indent}BEGIN {basename}  ts={evt['ts']}")
             elif in_target:
                 indent = "  " * (len(stack) - target_depth)
                 print(f"{indent}BEGIN {basename}")

         elif ph == "e" and stack:
             ts_begin, basename, detail = stack.pop()
             dur_ms = (evt["ts"] - ts_begin) / 1000

             if in_target:
                 indent = "  " * (len(stack) + 1 - target_depth)
                 print(f"{indent}END   {basename}  dur={dur_ms:.1f}ms")

             if in_target and len(stack) < target_depth:
                 in_target = False


 def _collapse_template_name(name):
     """Collapse template arguments to '$' for grouping, like ClangBuildAnalyzer."""
     result = []
     depth = 0
     for ch in name:
         if ch == "<":
             if depth == 0:
                 result.append("<$>")
             depth += 1
         elif ch == ">":
             depth -= 1
         elif depth == 0:
             result.append(ch)
     return "".join(result)


 def _truncate(s, maxlen=100):
     return s if len(s) <= maxlen else s[: maxlen - 3] + "..."


 def print_templates(trace_dir, top_n=30):
     """Print templates that took longest to instantiate, individually and grouped."""
     files = sorted(glob.glob(os.path.join(trace_dir, "**", "*.json"), recursive=True))

     # Individual: (detail, total_dur_us, count)
     individual = {}
     # Grouped by collapsed name: (collapsed, total_dur_us, count)
     grouped = {}

     for f in files:
         try:
             events = load_trace(f)
         except Exception:
             continue

         for evt in events:
             name = evt.get("name", "")
             if name not in ("InstantiateClass", "InstantiateFunction"):
                 continue
             dur = evt.get("dur", 0)
             if dur <= 0:
                 continue
             detail = evt.get("args", {}).get("detail", "")
             if not detail:
                 continue

             if detail in individual:
                 t, c = individual[detail]
                 individual[detail] = (t + dur, c + 1)
             else:
                 individual[detail] = (dur, 1)

             collapsed = _collapse_template_name(detail)
             if collapsed in grouped:
                 t, c = grouped[collapsed]
                 grouped[collapsed] = (t + dur, c + 1)
             else:
                 grouped[collapsed] = (dur, 1)

     print("**** Templates that took longest to instantiate:")
     print()
     for detail in sorted(individual.keys(), key=lambda x: -individual[x][0])[:top_n]:
         total_us, count = individual[detail]
         avg_ms = total_us / count / 1000
         print(
             f" {total_us / 1000:>7.0f} ms: {_truncate(detail)} ({count} times, avg {avg_ms:.0f} ms)"
         )

     print()
     print("**** Template sets that took longest to instantiate:")
     print()
     for collapsed in sorted(grouped.keys(), key=lambda x: -grouped[x][0])[:top_n]:
         total_us, count = grouped[collapsed]
         avg_ms = total_us / count / 1000
         print(
             f"{total_us / 1000:>7.0f} ms: {_truncate(collapsed)} ({count} times, avg {avg_ms:.0f} ms)"
         )


 def print_functions(trace_dir, top_n=30):
     """Print functions that took longest to compile (backend codegen)."""
     files = sorted(glob.glob(os.path.join(trace_dir, "**", "*.json"), recursive=True))

     # Individual functions
     individual = {}
     # Grouped by collapsed name
     grouped = {}

     for f in files:
         try:
             events = load_trace(f)
         except Exception:
             continue

         tu_name = os.path.basename(f).replace(".json", "")

         for evt in events:
             name = evt.get("name", "")
             if name not in ("CodeGen Function", "OptFunction"):
                 continue
             dur = evt.get("dur", 0)
             if dur <= 0:
                 continue
             detail = evt.get("args", {}).get("detail", "")
             if not detail:
                 continue

             key = (detail, tu_name)
             if key in individual:
                 individual[key] = individual[key] + dur
             else:
                 individual[key] = dur

             collapsed = _collapse_template_name(detail)
             if collapsed in grouped:
                 t, c = grouped[collapsed]
                 grouped[collapsed] = (t + dur, c + 1)
             else:
                 grouped[collapsed] = (dur, 1)

     print("**** Functions that took longest to compile:")
     print()
     for (detail, tu) in sorted(individual.keys(), key=lambda x: -individual[x])[:top_n]:
         dur_us = individual[(detail, tu)]
         print(f"  {dur_us / 1000:>6.0f} ms: {_truncate(detail, 80)} ({tu})")

     print()
     print("**** Function sets that took longest to compile / optimize:")
     print()
     for collapsed in sorted(grouped.keys(), key=lambda x: -grouped[x][0])[:top_n]:
         total_us, count = grouped[collapsed]
         avg_ms = total_us / count / 1000
         print(
             f"  {total_us / 1000:>6.0f} ms: {_truncate(collapsed, 80)} ({count} times, avg {avg_ms:.0f} ms)"
         )


 def print_slowest_tu(trace_dir, top_n=10):
     """Print TUs that took longest to compile (frontend and backend separately)."""
     files = sorted(glob.glob(os.path.join(trace_dir, "**", "*.json"), recursive=True))

     frontend_times = {}
     backend_times = {}

     for f in files:
         try:
             events = load_trace(f)
         except Exception:
             continue

         tu_name = os.path.basename(f).replace(".json", "")

         for evt in events:
             name = evt.get("name", "")
             dur = evt.get("dur", 0)
             if name == "Frontend":
                 frontend_times[tu_name] = frontend_times.get(tu_name, 0) + dur
             elif name == "Backend":
                 backend_times[tu_name] = backend_times.get(tu_name, 0) + dur

     print("**** Files that took longest to parse (compiler frontend):")
     for tu in sorted(frontend_times.keys(), key=lambda x: -frontend_times[x])[:top_n]:
         print(f" {frontend_times[tu] / 1000:>7.0f} ms: {tu}")

     print()
     print("**** Files that took longest to codegen (compiler backend):")
     for tu in sorted(backend_times.keys(), key=lambda x: -backend_times[x])[:top_n]:
         print(f" {backend_times[tu] / 1000:>7.0f} ms: {tu}")


 def main():
     parser = argparse.ArgumentParser(
         description="Analyze -ftime-trace JSON files from a WebKit build.",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=__doc__,
     )
     parser.add_argument("trace_dir", help="Directory containing .json trace files")
     parser.add_argument("--top", type=int, default=30, help="Number of headers to show (default: 30)")
     parser.add_argument("--filter", type=str, default=None, help="Only show headers matching this substring")
     parser.add_argument("--summary", action="store_true", help="Show overall build time breakdown")
     parser.add_argument("--categories", action="store_true", help="Show top event categories")
     parser.add_argument("--templates", action="store_true", help="Show template instantiation hotspots")
     parser.add_argument("--functions", action="store_true", help="Show functions that took longest to compile")
     parser.add_argument("--slowest-tu", action="store_true", help="Show TUs that took longest to compile")
     parser.add_argument("--trace-header", type=str, default=None, help="Show detailed nesting for this header")
     parser.add_argument("--tu", type=str, default=None, help="TU name for --trace-header (e.g. UnifiedSource500)")

     args = parser.parse_args()

     if not os.path.isdir(args.trace_dir):
         print(f"Error: {args.trace_dir} is not a directory", file=sys.stderr)
         sys.exit(1)

     if args.summary:
         print_summary(args.trace_dir)
         return

     if args.categories:
         print_categories(args.trace_dir, args.top)
         return

     if args.templates:
         print_templates(args.trace_dir, args.top)
         return

     if args.functions:
         print_functions(args.trace_dir, args.top)
         return

     if args.slowest_tu:
         print_slowest_tu(args.trace_dir, args.top)
         return

     if args.trace_header:
         if not args.tu:
             print("Error: --trace-header requires --tu", file=sys.stderr)
             sys.exit(1)
         trace_header_in_tu(args.trace_dir, args.trace_header, args.tu)
         return

     inclusive, exclusive, tu_count = compute_header_times(args.trace_dir, args.filter)
     print_header_table(inclusive, exclusive, tu_count, args.top)


 if __name__ == "__main__":
     main()
	#!/usr/bin/env python3
	#
	# Copyright (C) 2026 Apple Inc. All rights reserved.
	#
	# Redistribution and use in source and binary forms, with or without
	# modification, are permitted provided that the following conditions
	# are met:
	# 1. Redistributions of source code must retain the above copyright
	# notice, this list of conditions and the following disclaimer.
	# 2. Redistributions in binary form must reproduce the above copyright
	# notice, this list of conditions and the following disclaimer in the
	# documentation and/or other materials provided with the distribution.
	#
	# THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
	# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
	# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
	# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
	# BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
	# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
	# THE POSSIBILITY OF SUCH DAMAGE.

	"""Analyze -ftime-trace JSON files from a WebKit build.

	Companion to ClangBuildAnalyzer (CBA). Both tools consume the same -ftime-trace
	JSON files. This script overlaps with CBA in several areas but adds exclusive
	(self) time analysis for headers, which CBA does not provide.

	Comparison with ClangBuildAnalyzer
	----------------------------------
	Matching sections (numbers align closely):
	--slowest-tu <-> CBA "Files that took longest to parse/codegen"
	--templates <-> CBA "Templates that took longest to instantiate"
	--summary <-> CBA "Time summary"

	Differences:
	- Template sets: this script counts all instantiations; CBA filters by a
	minimum duration threshold, so our totals run higher for high-frequency /
	low-cost templates.
	- Functions: this script sums both CodeGen Function and OptFunction events;
	CBA uses CodeGen Function only.

	Unique to this script (not in CBA):
	- Exclusive (self) header parse time: the default mode computes both
	inclusive and exclusive time per header, revealing where parse time is
	actually spent vs. merely transited through an include chain. This is the
	primary reason the script exists.
	- --trace-header: drill into the include nesting of a specific header in a
	single TU.
	- --filter: restrict header output to names matching a substring.

	Unique to CBA (not replicated here):
	- Include-chain visualisation ("included via: ...") showing the N most
	common paths through which an expensive header is pulled in.
	- Binary format capture file (faster repeated analysis).

	Implementation note -- event ordering
	--------------------------------------
	clang's -ftime-trace JSON does NOT guarantee events are sorted by timestamp.
	Source events use begin/end pairs (ph: "b" / "e") that nest as a stack, but
	the pairs can appear in arbitrary order in the array. This script sorts Source
	events by timestamp before processing to reconstruct the correct nesting. An
	earlier version of this script did not sort, which produced incorrect exclusive
	times (every header appeared to have inclusive == exclusive).

	Usage:
	analyze-ftime-trace <trace-dir> [options]

	The trace directory should contain .json files produced by clang's -ftime-trace
	flag (searched recursively), typically found at:
	WebKitBuild/WebCore.build/Release/WebCore.build/Objects-normal/arm64e/
	or for CMake builds:
	WebKitBuild/cmake-mac/Release/Source/WebCore/CMakeFiles/WebCore.dir/

	Examples:
	# Show top 30 headers by exclusive (self) parse time
	analyze-ftime-trace <dir>

	# Show top 50 headers
	analyze-ftime-trace <dir> --top 50

	# Filter to headers matching a pattern
	analyze-ftime-trace <dir> --filter RenderStyle

	# Show template instantiation hotspots
	analyze-ftime-trace <dir> --templates

	# Show functions that took longest to compile
	analyze-ftime-trace <dir> --functions

	# Show TUs that took longest to compile
	analyze-ftime-trace <dir> --slowest-tu

	# Show detailed nesting for a specific header in one TU
	analyze-ftime-trace <dir> --trace-header StyleComputedStyleBase+GettersInlines.h --tu UnifiedSource500

	# Show overall build time breakdown
	analyze-ftime-trace <dir> --summary

	# Show top event categories (ParseClass, InstantiateFunction, etc.)
	analyze-ftime-trace <dir> --categories
	"""

	import argparse
	import json
	import glob
	import os
	import re
	import sys


	def load_trace(path):
	"""Load a -ftime-trace JSON file, returning its event list."""
	with open(path) as f:
	data = json.load(f)
	events = data if isinstance(data, list) else data.get("traceEvents", [])
	# Guard against non-ftime-trace JSON files that happen to be lists.
	if events and not isinstance(events[0], dict):
	return []
	return events


	def compute_header_times(trace_dir, header_filter=None):
	"""Compute inclusive and exclusive (self) time per header across all TUs.

	Returns (inclusive, exclusive, tu_count) dicts keyed by header basename.
	Times are in microseconds.
	"""
	files = sorted(glob.glob(os.path.join(trace_dir, "*", ".json"), recursive=True))

	inclusive = {}
	exclusive = {}
	tu_count = {}

	for f in files:
	try:
	events = load_trace(f)
	except Exception:
	continue

	# Source events use begin/end pairs (ph: b/e) that nest as a stack.
	# IMPORTANT: Events in the JSON are NOT necessarily sorted by timestamp.
	# We must sort Source events by timestamp for correct stack-based nesting.
	source_events = sorted(
	[e for e in events if e.get("name") == "Source"],
	key=lambda e: e["ts"],
	)

	stack = [] # (ts_begin, header_basename, child_time_accum)

	for evt in source_events:
	ph = evt.get("ph")

	if ph == "b":
	detail = evt.get("args", {}).get("detail", "")
	basename = detail.rsplit("/", 1)[-1] if "/" in detail else detail
	stack.append((evt["ts"], basename, 0))
	elif ph == "e" and stack:
	ts_begin, basename, child_time = stack.pop()
	dur = evt["ts"] - ts_begin
	excl = dur - child_time

	if header_filter is None or header_filter in basename:
	inclusive[basename] = inclusive.get(basename, 0) + dur
	exclusive[basename] = exclusive.get(basename, 0) + excl
	tu_count[basename] = tu_count.get(basename, 0) + 1

	if stack:
	p_ts, p_name, p_child = stack[-1]
	stack[-1] = (p_ts, p_name, p_child + dur)

	return inclusive, exclusive, tu_count


	def print_header_table(inclusive, exclusive, tu_count, top_n=30):
	"""Print a formatted table of header parse times."""
	fmt_header = f"{'Header':<65} {'Inclusive':>10} {'Exclusive':>10} {'TUs':>6} {'Excl/TU':>10}"
	fmt_units = f"{'':65s} {'(min)':>10} {'(min)':>10} {'':>6} {'(ms)':>10}"
	sep = "-" * 105

	print(fmt_header)
	print(fmt_units)
	print(sep)

	for h in sorted(exclusive.keys(), key=lambda x: -exclusive[x])[:top_n]:
	inc_min = inclusive.get(h, 0) / 60_000_000
	exc_min = exclusive.get(h, 0) / 60_000_000
	tus = tu_count.get(h, 0)
	per_tu_ms = exclusive.get(h, 0) / tus / 1000 if tus else 0
	print(f"{h:<65} {inc_min:>10.1f} {exc_min:>10.1f} {tus:>6} {per_tu_ms:>10.1f}")

	print(sep)
	total_exc = sum(exclusive.values()) / 60_000_000
	total_inc = sum(inclusive.values()) / 60_000_000
	print(f"{'Total (all matched headers)':<65} {total_inc:>10.1f} {total_exc:>10.1f}")


	def print_summary(trace_dir):
	"""Print overall build time breakdown."""
	files = sorted(glob.glob(os.path.join(trace_dir, "*", ".json"), recursive=True))

	totals = {}
	tu_count = 0

	for f in files:
	try:
	events = load_trace(f)
	except Exception:
	continue
	tu_count += 1
	for evt in events:
	name = evt.get("name", "")
	dur = evt.get("dur", 0)
	if name.startswith("Total ") or name in ("ExecuteCompiler", "Frontend", "Backend", "Optimizer"):
	totals[name] = totals.get(name, 0) + dur

	print(f"Translation units: {tu_count}")
	print()
	print(f"{'Category':<55} {'Cumulative':>12}")
	print(f"{'':55s} {'(min)':>12}")
	print("-" * 70)
	for name in sorted(totals.keys(), key=lambda x: -totals[x])[:30]:
	print(f"{name:<55} {totals[name] / 60_000_000:>12.1f}")


	def print_categories(trace_dir, top_n=30):
	"""Print top event categories by cumulative time."""
	files = sorted(glob.glob(os.path.join(trace_dir, "*", ".json"), recursive=True))

	totals = {}

	for f in files:
	try:
	events = load_trace(f)
	except Exception:
	continue
	for evt in events:
	name = evt.get("name", "")
	dur = evt.get("dur", 0)
	if name.startswith("Total ") and dur > 0:
	totals[name] = totals.get(name, 0) + dur

	print(f"{'Category':<65} {'Cumulative':>12}")
	print(f"{'':65s} {'(min)':>12}")
	print("-" * 80)
	for name in sorted(totals.keys(), key=lambda x: -totals[x])[:top_n]:
	print(f"{name:<65} {totals[name] / 60_000_000:>12.1f}")


	def trace_header_in_tu(trace_dir, header_name, tu_name):
	"""Show detailed nesting for a specific header in a specific TU."""
	# Try flat path first, then search recursively for CMake-style layouts.
	tu_path = os.path.join(trace_dir, tu_name + ".json")
	if not os.path.exists(tu_path):
	matches = glob.glob(os.path.join(trace_dir, "**", tu_name + ".json"), recursive=True)
	if not matches:
	print(f"Error: {tu_name}.json not found under {trace_dir}", file=sys.stderr)
	sys.exit(1)
	tu_path = matches[0]

	events = load_trace(tu_path)

	# Sort Source events by timestamp for correct nesting.
	source_events = sorted(
	[e for e in events if e.get("name") == "Source"],
	key=lambda e: e["ts"],
	)

	in_target = False
	target_depth = 0
	stack = []

	for evt in source_events:
	ph = evt.get("ph")

	if ph == "b":
	detail = evt.get("args", {}).get("detail", "")
	basename = detail.rsplit("/", 1)[-1] if "/" in detail else detail
	stack.append((evt["ts"], basename, detail))

	if header_name in basename and not in_target:
	in_target = True
	target_depth = len(stack)
	indent = " " * (len(stack) - target_depth)
	print(f"{indent}BEGIN {basename} ts={evt['ts']}")
	elif in_target:
	indent = " " * (len(stack) - target_depth)
	print(f"{indent}BEGIN {basename}")

	elif ph == "e" and stack:
	ts_begin, basename, detail = stack.pop()
	dur_ms = (evt["ts"] - ts_begin) / 1000

	if in_target:
	indent = " " * (len(stack) + 1 - target_depth)
	print(f"{indent}END {basename} dur={dur_ms:.1f}ms")

	if in_target and len(stack) < target_depth:
	in_target = False


	def _collapse_template_name(name):
	"""Collapse template arguments to '$' for grouping, like ClangBuildAnalyzer."""
	result = []
	depth = 0
	for ch in name:
	if ch == "<":
	if depth == 0:
	result.append("<$>")
	depth += 1
	elif ch == ">":
	depth -= 1
	elif depth == 0:
	result.append(ch)
	return "".join(result)


	def _truncate(s, maxlen=100):
	return s if len(s) <= maxlen else s[: maxlen - 3] + "..."


	def print_templates(trace_dir, top_n=30):
	"""Print templates that took longest to instantiate, individually and grouped."""
	files = sorted(glob.glob(os.path.join(trace_dir, "*", ".json"), recursive=True))

	# Individual: (detail, total_dur_us, count)
	individual = {}
	# Grouped by collapsed name: (collapsed, total_dur_us, count)
	grouped = {}

	for f in files:
	try:
	events = load_trace(f)
	except Exception:
	continue

	for evt in events:
	name = evt.get("name", "")
	if name not in ("InstantiateClass", "InstantiateFunction"):
	continue
	dur = evt.get("dur", 0)
	if dur <= 0:
	continue
	detail = evt.get("args", {}).get("detail", "")
	if not detail:
	continue

	if detail in individual:
	t, c = individual[detail]
	individual[detail] = (t + dur, c + 1)
	else:
	individual[detail] = (dur, 1)

	collapsed = _collapse_template_name(detail)
	if collapsed in grouped:
	t, c = grouped[collapsed]
	grouped[collapsed] = (t + dur, c + 1)
	else:
	grouped[collapsed] = (dur, 1)

	print("**** Templates that took longest to instantiate:")
	print()
	for detail in sorted(individual.keys(), key=lambda x: -individual[x][0])[:top_n]:
	total_us, count = individual[detail]
	avg_ms = total_us / count / 1000
	print(
	f" {total_us / 1000:>7.0f} ms: {_truncate(detail)} ({count} times, avg {avg_ms:.0f} ms)"
	)

	print()
	print("**** Template sets that took longest to instantiate:")
	print()
	for collapsed in sorted(grouped.keys(), key=lambda x: -grouped[x][0])[:top_n]:
	total_us, count = grouped[collapsed]
	avg_ms = total_us / count / 1000
	print(
	f"{total_us / 1000:>7.0f} ms: {_truncate(collapsed)} ({count} times, avg {avg_ms:.0f} ms)"
	)


	def print_functions(trace_dir, top_n=30):
	"""Print functions that took longest to compile (backend codegen)."""
	files = sorted(glob.glob(os.path.join(trace_dir, "*", ".json"), recursive=True))

	# Individual functions
	individual = {}
	# Grouped by collapsed name
	grouped = {}

	for f in files:
	try:
	events = load_trace(f)
	except Exception:
	continue

	tu_name = os.path.basename(f).replace(".json", "")

	for evt in events:
	name = evt.get("name", "")
	if name not in ("CodeGen Function", "OptFunction"):
	continue
	dur = evt.get("dur", 0)
	if dur <= 0:
	continue
	detail = evt.get("args", {}).get("detail", "")
	if not detail:
	continue

	key = (detail, tu_name)
	if key in individual:
	individual[key] = individual[key] + dur
	else:
	individual[key] = dur

	collapsed = _collapse_template_name(detail)
	if collapsed in grouped:
	t, c = grouped[collapsed]
	grouped[collapsed] = (t + dur, c + 1)
	else:
	grouped[collapsed] = (dur, 1)

	print("**** Functions that took longest to compile:")
	print()
	for (detail, tu) in sorted(individual.keys(), key=lambda x: -individual[x])[:top_n]:
	dur_us = individual[(detail, tu)]
	print(f" {dur_us / 1000:>6.0f} ms: {_truncate(detail, 80)} ({tu})")

	print()
	print("**** Function sets that took longest to compile / optimize:")
	print()
	for collapsed in sorted(grouped.keys(), key=lambda x: -grouped[x][0])[:top_n]:
	total_us, count = grouped[collapsed]
	avg_ms = total_us / count / 1000
	print(
	f" {total_us / 1000:>6.0f} ms: {_truncate(collapsed, 80)} ({count} times, avg {avg_ms:.0f} ms)"
	)


	def print_slowest_tu(trace_dir, top_n=10):
	"""Print TUs that took longest to compile (frontend and backend separately)."""
	files = sorted(glob.glob(os.path.join(trace_dir, "*", ".json"), recursive=True))

	frontend_times = {}
	backend_times = {}

	for f in files:
	try:
	events = load_trace(f)
	except Exception:
	continue

	tu_name = os.path.basename(f).replace(".json", "")

	for evt in events:
	name = evt.get("name", "")
	dur = evt.get("dur", 0)
	if name == "Frontend":
	frontend_times[tu_name] = frontend_times.get(tu_name, 0) + dur
	elif name == "Backend":
	backend_times[tu_name] = backend_times.get(tu_name, 0) + dur

	print("**** Files that took longest to parse (compiler frontend):")
	for tu in sorted(frontend_times.keys(), key=lambda x: -frontend_times[x])[:top_n]:
	print(f" {frontend_times[tu] / 1000:>7.0f} ms: {tu}")

	print()
	print("**** Files that took longest to codegen (compiler backend):")
	for tu in sorted(backend_times.keys(), key=lambda x: -backend_times[x])[:top_n]:
	print(f" {backend_times[tu] / 1000:>7.0f} ms: {tu}")


	def main():
	parser = argparse.ArgumentParser(
	description="Analyze -ftime-trace JSON files from a WebKit build.",
	formatter_class=argparse.RawDescriptionHelpFormatter,
	epilog=__doc__,
	)
	parser.add_argument("trace_dir", help="Directory containing .json trace files")
	parser.add_argument("--top", type=int, default=30, help="Number of headers to show (default: 30)")
	parser.add_argument("--filter", type=str, default=None, help="Only show headers matching this substring")
	parser.add_argument("--summary", action="store_true", help="Show overall build time breakdown")
	parser.add_argument("--categories", action="store_true", help="Show top event categories")
	parser.add_argument("--templates", action="store_true", help="Show template instantiation hotspots")
	parser.add_argument("--functions", action="store_true", help="Show functions that took longest to compile")
	parser.add_argument("--slowest-tu", action="store_true", help="Show TUs that took longest to compile")
	parser.add_argument("--trace-header", type=str, default=None, help="Show detailed nesting for this header")
	parser.add_argument("--tu", type=str, default=None, help="TU name for --trace-header (e.g. UnifiedSource500)")

	args = parser.parse_args()

	if not os.path.isdir(args.trace_dir):
	print(f"Error: {args.trace_dir} is not a directory", file=sys.stderr)
	sys.exit(1)

	if args.summary:
	print_summary(args.trace_dir)
	return

	if args.categories:
	print_categories(args.trace_dir, args.top)
	return

	if args.templates:
	print_templates(args.trace_dir, args.top)
	return

	if args.functions:
	print_functions(args.trace_dir, args.top)
	return

	if args.slowest_tu:
	print_slowest_tu(args.trace_dir, args.top)
	return

	if args.trace_header:
	if not args.tu:
	print("Error: --trace-header requires --tu", file=sys.stderr)
	sys.exit(1)
	trace_header_in_tu(args.trace_dir, args.trace_header, args.tu)
	return

	inclusive, exclusive, tu_count = compute_header_times(args.trace_dir, args.filter)
	print_header_table(inclusive, exclusive, tu_count, args.top)


	if __name__ == "__main__":
	main()