Profiling on Tarragon

案例：效能分析實戰

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/markdown_link_checker.py 的實際程式碼，展示如何用 cProfile 和 line_profiler 進行效能分析。

先備知識

模組四基礎章節
Python 正則表達式基礎

問題背景

現有設計

markdown_link_checker.py 是一個 Markdown 連結檢查工具，核心功能是解析文件中的連結並驗證其有效性。以下是關鍵的解析方法：

 1import re
 2from typing import List, Dict
 3
 4class MarkdownLinkChecker:
 5    """Markdown link checker with precompiled regex patterns"""
 6
 7    # Precompiled regex patterns at class level (good practice!)
 8    INLINE_LINK_PATTERN = re.compile(
 9        r'(?
10    )
11
12    REFERENCE_DEF_PATTERN = re.compile(
13        r'^\s*\[([^\]]+)\]:\s*(.+)$',
14        re.MULTILINE
15    )
16
17    REFERENCE_USE_PATTERN = re.compile(
18        r'\[([^\]]+)\]\[([^\]]+)\]'
19    )
20
21    def parse_markdown_links(self, content: str) -> List[Dict]:
22        """
23        Parse all links in Markdown content
24
25        Args:
26            content: Markdown content string
27
28        Returns:
29            list[dict]: List of links with text, target, line
30        """
31        links = []
32        lines = content.split('\n')
33
34        # First, collect reference-style link definitions
35        reference_defs = {}
36        for match in self.REFERENCE_DEF_PATTERN.finditer(content):
37            ref_name = match.group(1).lower()
38            ref_target = match.group(2).strip()
39            reference_defs[ref_name] = ref_target
40
41        # Track code block state
42        in_code_block = False
43
44        # Parse inline links line by line
45        for line_num, line in enumerate(lines, start=1):
46            # Check for code block boundaries
47            if line.strip().startswith("```"):
48                in_code_block = not in_code_block
49                continue
50
51            # Skip links inside code blocks
52            if in_code_block:
53                continue
54
55            # Inline links: [text](/python-advanced/04-cpython-internals/case-studies/profiling/target)
56            for match in self.INLINE_LINK_PATTERN.finditer(line):
57                links.append({
58                    "text": match.group(1),
59                    "target": match.group(2),
60                    "line": line_num
61                })
62
63            # Reference-style links: [text][ref]
64            for match in self.REFERENCE_USE_PATTERN.finditer(line):
65                ref_name = match.group(2).lower()
66                if ref_name in reference_defs:
67                    links.append({
68                        "text": match.group(1),
69                        "target": reference_defs[ref_name],
70                        "line": line_num
71                    })
72
73        return links

效能問題

處理大型文件時可能出現：

正則表達式效率問題：複雜的 pattern 可能導致回溯
重複編譯正則表達式：若 pattern 在方法內定義，每次呼叫都會重新編譯
不必要的字串操作：split() 會建立新的字串列表
多次遍歷：分別處理引用定義和行內連結

進階解決方案

分析目標

找出效能瓶頸所在
量化各部分的時間消耗
驗證優化效果

實作步驟

步驟 1：使用 cProfile 進行函式級分析

cProfile 是 Python 標準庫的效能分析工具，可以測量每個函式的呼叫次數和執行時間。

 1import cProfile
 2import pstats
 3from io import StringIO
 4from pathlib import Path
 5
 6def profile_link_checker():
 7    """Profile the markdown link checker with cProfile"""
 8
 9    # Create test content with many links
10    test_content = generate_test_content(num_links=1000)
11
12    checker = MarkdownLinkChecker()
13
14    # Create profiler
15    profiler = cProfile.Profile()
16
17    # Run profiling
18    profiler.enable()
19    for _ in range(100):  # Run multiple times for better statistics
20        checker.parse_markdown_links(test_content)
21    profiler.disable()
22
23    # Analyze results
24    stream = StringIO()
25    stats = pstats.Stats(profiler, stream=stream)
26    stats.sort_stats('cumulative')  # Sort by cumulative time
27    stats.print_stats(20)  # Show top 20 functions
28
29    print(stream.getvalue())
30
31    return stats
32
33def generate_test_content(num_links: int) -> str:
34    """Generate test Markdown content with specified number of links"""
35    lines = ["# Test Document\n"]
36
37    for i in range(num_links):
38        if i % 3 == 0:
39            # Inline link
40            lines.append(f"Check out [Link {i}](https://example.com/{i})\n")
41        elif i % 3 == 1:
42            # Reference-style link
43            lines.append(f"See [Reference {i}][ref{i}]\n")
44        else:
45            # Plain text with potential regex traps
46            lines.append(f"This is paragraph {i} with some [text] that looks like links.\n")
47
48    # Add reference definitions at the end
49    for i in range(num_links):
50        if i % 3 == 1:
51            lines.append(f"[ref{i}]: https://example.com/ref/{i}\n")
52
53    return "".join(lines)
54
55if __name__ == "__main__":
56    profile_link_checker()

執行方式：

1# Direct execution
2python profile_link_checker.py
3
4# Using cProfile from command line
5python -m cProfile -s cumulative markdown_link_checker.py --dir ./docs/

步驟 2：使用 pstats 分析結果

pstats 模組提供更細緻的結果分析功能：

 1import cProfile
 2import pstats
 3from pstats import SortKey
 4
 5def detailed_analysis():
 6    """Perform detailed analysis with pstats"""
 7
 8    # Profile the code
 9    profiler = cProfile.Profile()
10    profiler.enable()
11
12    # Run the target function
13    checker = MarkdownLinkChecker()
14    content = generate_test_content(500)
15    for _ in range(50):
16        checker.parse_markdown_links(content)
17
18    profiler.disable()
19
20    # Create Stats object
21    stats = pstats.Stats(profiler)
22
23    # Different sorting options
24    print("=" * 70)
25    print("Top 10 by CUMULATIVE time (including sub-calls)")
26    print("=" * 70)
27    stats.sort_stats(SortKey.CUMULATIVE).print_stats(10)
28
29    print("\n" + "=" * 70)
30    print("Top 10 by TOTAL time (excluding sub-calls)")
31    print("=" * 70)
32    stats.sort_stats(SortKey.TIME).print_stats(10)
33
34    print("\n" + "=" * 70)
35    print("Top 10 by CALL count")
36    print("=" * 70)
37    stats.sort_stats(SortKey.CALLS).print_stats(10)
38
39    # Filter by function name
40    print("\n" + "=" * 70)
41    print("Functions containing 'parse' or 'match'")
42    print("=" * 70)
43    stats.sort_stats(SortKey.TIME).print_stats('parse|match', 10)
44
45    # Show callers of a specific function
46    print("\n" + "=" * 70)
47    print("Who calls 'finditer'?")
48    print("=" * 70)
49    stats.print_callers('finditer')
50
51    # Save stats to file for later analysis
52    stats.dump_stats('link_checker.prof')
53
54    return stats
55
56def load_and_compare_profiles():
57    """Load and compare saved profile data"""
58    try:
59        # Load saved profile
60        stats = pstats.Stats('link_checker.prof')
61
62        # Add another profile for comparison
63        stats.add('link_checker_optimized.prof')
64
65        # Print combined stats
66        stats.sort_stats(SortKey.CUMULATIVE).print_stats(20)
67    except FileNotFoundError:
68        print("Profile files not found. Run detailed_analysis() first.")

步驟 3：使用 line_profiler 進行行級分析

line_profiler 可以分析每一行程式碼的執行時間，適合精確定位瓶頸。

首先安裝 line_profiler：

1pip install line_profiler

使用裝飾器標記要分析的函式：

  1# profile_lines.py
  2from line_profiler import profile
  3
  4@profile
  5def parse_markdown_links_profiled(self, content: str):
  6    """
  7    Line-by-line profiled version of parse_markdown_links
  8    """
  9    links = []
 10    lines = content.split('\n')
 11
 12    # Collect reference definitions
 13    reference_defs = {}
 14    for match in self.REFERENCE_DEF_PATTERN.finditer(content):
 15        ref_name = match.group(1).lower()
 16        ref_target = match.group(2).strip()
 17        reference_defs[ref_name] = ref_target
 18
 19    in_code_block = False
 20
 21    for line_num, line in enumerate(lines, start=1):
 22        if line.strip().startswith("```"):
 23            in_code_block = not in_code_block
 24            continue
 25
 26        if in_code_block:
 27            continue
 28
 29        # These regex operations might be slow
 30        for match in self.INLINE_LINK_PATTERN.finditer(line):
 31            links.append({
 32                "text": match.group(1),
 33                "target": match.group(2),
 34                "line": line_num
 35            })
 36
 37        for match in self.REFERENCE_USE_PATTERN.finditer(line):
 38            ref_name = match.group(2).lower()
 39            if ref_name in reference_defs:
 40                links.append({
 41                    "text": match.group(1),
 42                    "target": reference_defs[ref_name],
 43                    "line": line_num
 44                })
 45
 46    return links
 47
 48# Alternative: Manual timing for specific sections
 49import time
 50
 51def parse_with_timing(self, content: str):
 52    """Manual timing for detailed analysis"""
 53    timings = {}
 54
 55    # Time: split lines
 56    start = time.perf_counter()
 57    lines = content.split('\n')
 58    timings['split_lines'] = time.perf_counter() - start
 59
 60    # Time: parse reference definitions
 61    start = time.perf_counter()
 62    reference_defs = {}
 63    for match in self.REFERENCE_DEF_PATTERN.finditer(content):
 64        ref_name = match.group(1).lower()
 65        ref_target = match.group(2).strip()
 66        reference_defs[ref_name] = ref_target
 67    timings['parse_refs'] = time.perf_counter() - start
 68
 69    # Time: main parsing loop
 70    start = time.perf_counter()
 71    links = []
 72    in_code_block = False
 73
 74    for line_num, line in enumerate(lines, start=1):
 75        if line.strip().startswith("```"):
 76            in_code_block = not in_code_block
 77            continue
 78
 79        if in_code_block:
 80            continue
 81
 82        for match in self.INLINE_LINK_PATTERN.finditer(line):
 83            links.append({
 84                "text": match.group(1),
 85                "target": match.group(2),
 86                "line": line_num
 87            })
 88
 89        for match in self.REFERENCE_USE_PATTERN.finditer(line):
 90            ref_name = match.group(2).lower()
 91            if ref_name in reference_defs:
 92                links.append({
 93                    "text": match.group(1),
 94                    "target": reference_defs[ref_name],
 95                    "line": line_num
 96                })
 97
 98    timings['main_loop'] = time.perf_counter() - start
 99
100    return links, timings

執行 line_profiler：

1# Run with kernprof
2kernprof -l -v profile_lines.py
3
4# Or use the newer approach
5python -m line_profiler profile_lines.py

步驟 4：分析正則表達式效能

正則表達式是常見的效能瓶頸，需要特別分析：

  1import re
  2import time
  3from typing import Callable
  4
  5def benchmark_regex_patterns():
  6    """Compare different regex pattern implementations"""
  7
  8    # Test content with various edge cases
  9    test_lines = [
 10        "Check out [Link](https://example.com)",
 11        "See [Text with [brackets]](/python-advanced/04-cpython-internals/case-studies/profiling/url)",
 12        "Multiple [link1](/python-advanced/04-cpython-internals/case-studies/profiling/url1) and [link2](/python-advanced/04-cpython-internals/case-studies/profiling/url2)",
 13        "No links here, just plain text",
 14        "Tricky [text](/python-advanced/04-cpython-internals/case-studies/profiling/url) with more [text](/python-advanced/04-cpython-internals/case-studies/profiling/url) links",
 15        "![Image](/python-advanced/04-cpython-internals/case-studies/profiling/image.png) should be ignored",
 16        "[Link with spaces]( url with spaces )",
 17    ] * 1000
 18
 19    test_content = "\n".join(test_lines)
 20
 21    # Pattern 1: Original pattern
 22    pattern1 = re.compile(r'(?)
 23
 24    # Pattern 2: Possessive-like (using atomic group simulation)
 25    # Note: Python re doesn't support possessive quantifiers directly
 26    pattern2 = re.compile(r'(?)
 27
 28    # Pattern 3: More specific pattern
 29    pattern3 = re.compile(r'(?)
 30
 31    # Pattern 4: Non-capturing groups where possible
 32    pattern4 = re.compile(r'(?)
 33
 34    patterns = {
 35        "original": pattern1,
 36        "non_greedy": pattern2,
 37        "more_specific": pattern3,
 38        "optimized": pattern4,
 39    }
 40
 41    results = {}
 42
 43    for name, pattern in patterns.items():
 44        # Warmup
 45        for _ in range(10):
 46            list(pattern.finditer(test_content))
 47
 48        # Benchmark
 49        start = time.perf_counter()
 50        for _ in range(100):
 51            matches = list(pattern.finditer(test_content))
 52        elapsed = time.perf_counter() - start
 53
 54        results[name] = {
 55            "time": elapsed,
 56            "matches": len(matches),
 57        }
 58
 59    # Print comparison
 60    print("Regex Pattern Performance Comparison")
 61    print("=" * 60)
 62    print(f"{'Pattern':<20} {'Time (s)':<12} {'Matches':<10}")
 63    print("-" * 60)
 64
 65    baseline = results["original"]["time"]
 66    for name, data in results.items():
 67        speedup = baseline / data["time"]
 68        print(f"{name:<20} {data['time']:<12.4f} {data['matches']:<10} ({speedup:.2f}x)")
 69
 70    return results
 71
 72def analyze_regex_backtracking():
 73    """Analyze potential regex backtracking issues"""
 74    import re
 75
 76    # Patterns that might cause backtracking
 77    problematic_patterns = [
 78        (r'\[(.+)\]\((.+)\)', "Greedy .+ can backtrack"),
 79        (r'\[([^\]]+)\]\(([^)]+)\)', "Negated class - better"),
 80        (r'\[(.*?)\]\((.*?)\)', "Non-greedy - still may backtrack"),
 81    ]
 82
 83    # Pathological input that triggers backtracking
 84    pathological = "[" + "a" * 100 + "]"  # No closing bracket pattern
 85
 86    print("Regex Backtracking Analysis")
 87    print("=" * 60)
 88
 89    for pattern_str, description in problematic_patterns:
 90        pattern = re.compile(pattern_str)
 91
 92        start = time.perf_counter()
 93        try:
 94            # Set a timeout using signal (Unix only)
 95            result = pattern.search(pathological)
 96            elapsed = time.perf_counter() - start
 97            print(f"Pattern: {pattern_str}")
 98            print(f"  Description: {description}")
 99            print(f"  Time: {elapsed:.4f}s")
100            print(f"  Match: {result}")
101            print()
102        except Exception as e:
103            print(f"Pattern: {pattern_str} - Error: {e}")
104
105def compare_compile_vs_inline():
106    """Compare precompiled vs inline regex performance"""
107
108    test_content = generate_test_content(500)
109    iterations = 100
110
111    # Test 1: Precompiled pattern (recommended)
112    compiled_pattern = re.compile(r'(?)
113
114    start = time.perf_counter()
115    for _ in range(iterations):
116        list(compiled_pattern.finditer(test_content))
117    compiled_time = time.perf_counter() - start
118
119    # Test 2: Inline pattern (compiled each time by re module cache)
120    start = time.perf_counter()
121    for _ in range(iterations):
122        list(re.finditer(r'(?, test_content))
123    inline_time = time.perf_counter() - start
124
125    # Test 3: Pattern compiled inside loop (worst case)
126    start = time.perf_counter()
127    for _ in range(iterations):
128        pattern = re.compile(r'(?)
129        list(pattern.finditer(test_content))
130    loop_compile_time = time.perf_counter() - start
131
132    print("Compile Strategy Comparison")
133    print("=" * 60)
134    print(f"{'Strategy':<25} {'Time (s)':<12} {'Relative':<10}")
135    print("-" * 60)
136    print(f"{'Precompiled (class)':<25} {compiled_time:<12.4f} {'1.00x':<10}")
137    print(f"{'Inline (re cache)':<25} {inline_time:<12.4f} {inline_time/compiled_time:.2f}x")
138    print(f"{'Compile in loop':<25} {loop_compile_time:<12.4f} {loop_compile_time/compiled_time:.2f}x")

步驟 5：優化建議與驗證

根據分析結果，實作優化版本並驗證效果：

  1import re
  2from typing import List, Dict, Tuple
  3from dataclasses import dataclass
  4
  5@dataclass(slots=True)  # Python 3.10+ optimization
  6class LinkInfo:
  7    """Link information with memory-efficient storage"""
  8    text: str
  9    target: str
 10    line: int
 11
 12class OptimizedLinkChecker:
 13    """Optimized Markdown link checker based on profiling results"""
 14
 15    # Precompiled patterns at class level
 16    INLINE_LINK_PATTERN = re.compile(r'(?)
 17    REFERENCE_DEF_PATTERN = re.compile(r'^\s*\[([^\]]+)\]:\s*(.+)$', re.MULTILINE)
 18    REFERENCE_USE_PATTERN = re.compile(r'\[([^\]]+)\]\[([^\]]+)\]')
 19    CODE_BLOCK_PATTERN = re.compile(r'^```')
 20
 21    def parse_markdown_links_optimized(self, content: str) -> List[LinkInfo]:
 22        """
 23        Optimized link parsing with reduced memory allocation
 24
 25        Optimizations:
 26        1. Use dataclass with slots for link storage
 27        2. Single pass where possible
 28        3. Avoid repeated string operations
 29        4. Use local variables for frequently accessed attributes
 30        """
 31        links = []
 32
 33        # Cache pattern references for faster access
 34        inline_pattern = self.INLINE_LINK_PATTERN
 35        ref_use_pattern = self.REFERENCE_USE_PATTERN
 36        ref_def_pattern = self.REFERENCE_DEF_PATTERN
 37
 38        # Collect reference definitions first (single pass over content)
 39        reference_defs = {
 40            match.group(1).lower(): match.group(2).strip()
 41            for match in ref_def_pattern.finditer(content)
 42        }
 43
 44        # Process line by line
 45        in_code_block = False
 46        line_start = 0
 47
 48        for line_num, line_end in enumerate(
 49            self._find_line_positions(content), start=1
 50        ):
 51            line = content[line_start:line_end]
 52
 53            # Fast code block check
 54            if line.lstrip().startswith("```"):
 55                in_code_block = not in_code_block
 56                line_start = line_end + 1
 57                continue
 58
 59            if not in_code_block:
 60                # Parse inline links
 61                for match in inline_pattern.finditer(line):
 62                    links.append(LinkInfo(
 63                        text=match.group(1),
 64                        target=match.group(2),
 65                        line=line_num
 66                    ))
 67
 68                # Parse reference links
 69                for match in ref_use_pattern.finditer(line):
 70                    ref_name = match.group(2).lower()
 71                    target = reference_defs.get(ref_name)
 72                    if target:
 73                        links.append(LinkInfo(
 74                            text=match.group(1),
 75                            target=target,
 76                            line=line_num
 77                        ))
 78
 79            line_start = line_end + 1
 80
 81        return links
 82
 83    def _find_line_positions(self, content: str):
 84        """Generator that yields line end positions"""
 85        pos = 0
 86        while True:
 87            newline = content.find('\n', pos)
 88            if newline == -1:
 89                yield len(content)
 90                break
 91            yield newline
 92            pos = newline + 1
 93
 94def verify_optimization():
 95    """Verify that optimizations maintain correctness and improve performance"""
 96    import time
 97
 98    # Generate test content
 99    test_content = generate_test_content(1000)
100
101    # Original implementation
102    original = MarkdownLinkChecker()
103
104    # Optimized implementation
105    optimized = OptimizedLinkChecker()
106
107    # Verify correctness
108    original_links = original.parse_markdown_links(test_content)
109    optimized_links = optimized.parse_markdown_links_optimized(test_content)
110
111    # Compare results
112    assert len(original_links) == len(optimized_links), \
113        f"Link count mismatch: {len(original_links)} vs {len(optimized_links)}"
114
115    for orig, opt in zip(original_links, optimized_links):
116        assert orig["text"] == opt.text, f"Text mismatch: {orig['text']} vs {opt.text}"
117        assert orig["target"] == opt.target, f"Target mismatch"
118        assert orig["line"] == opt.line, f"Line mismatch"
119
120    print("Correctness verified!")
121
122    # Benchmark
123    iterations = 100
124
125    # Original
126    start = time.perf_counter()
127    for _ in range(iterations):
128        original.parse_markdown_links(test_content)
129    original_time = time.perf_counter() - start
130
131    # Optimized
132    start = time.perf_counter()
133    for _ in range(iterations):
134        optimized.parse_markdown_links_optimized(test_content)
135    optimized_time = time.perf_counter() - start
136
137    print(f"\nPerformance Comparison ({iterations} iterations)")
138    print("=" * 50)
139    print(f"Original:  {original_time:.4f}s")
140    print(f"Optimized: {optimized_time:.4f}s")
141    print(f"Speedup:   {original_time / optimized_time:.2f}x")

完整程式碼

以下是整合所有分析功能的完整腳本：

  1#!/usr/bin/env python3
  2"""
  3Performance Profiling Script for Markdown Link Checker
  4
  5This script demonstrates various profiling techniques:
  61. cProfile for function-level analysis
  72. pstats for detailed statistics
  83. line_profiler for line-by-line analysis
  94. Regex pattern benchmarking
 105. Optimization verification
 11
 12Usage:
 13    python profiling_demo.py [--full|--quick|--regex|--verify]
 14"""
 15
 16import argparse
 17import cProfile
 18import pstats
 19import re
 20import sys
 21import time
 22from dataclasses import dataclass
 23from io import StringIO
 24from pathlib import Path
 25from pstats import SortKey
 26from typing import Dict, List, Optional
 27
 28# ===== Original Implementation =====
 29
 30class MarkdownLinkChecker:
 31    """Original Markdown link checker for comparison"""
 32
 33    INLINE_LINK_PATTERN = re.compile(r'(?)
 34    REFERENCE_DEF_PATTERN = re.compile(r'^\s*\[([^\]]+)\]:\s*(.+)$', re.MULTILINE)
 35    REFERENCE_USE_PATTERN = re.compile(r'\[([^\]]+)\]\[([^\]]+)\]')
 36
 37    def parse_markdown_links(self, content: str) -> List[Dict]:
 38        links = []
 39        lines = content.split('\n')
 40
 41        reference_defs = {}
 42        for match in self.REFERENCE_DEF_PATTERN.finditer(content):
 43            ref_name = match.group(1).lower()
 44            ref_target = match.group(2).strip()
 45            reference_defs[ref_name] = ref_target
 46
 47        in_code_block = False
 48
 49        for line_num, line in enumerate(lines, start=1):
 50            if line.strip().startswith("```"):
 51                in_code_block = not in_code_block
 52                continue
 53
 54            if in_code_block:
 55                continue
 56
 57            for match in self.INLINE_LINK_PATTERN.finditer(line):
 58                links.append({
 59                    "text": match.group(1),
 60                    "target": match.group(2),
 61                    "line": line_num
 62                })
 63
 64            for match in self.REFERENCE_USE_PATTERN.finditer(line):
 65                ref_name = match.group(2).lower()
 66                if ref_name in reference_defs:
 67                    links.append({
 68                        "text": match.group(1),
 69                        "target": reference_defs[ref_name],
 70                        "line": line_num
 71                    })
 72
 73        return links
 74
 75# ===== Test Data Generation =====
 76
 77def generate_test_content(num_links: int) -> str:
 78    """Generate test Markdown content"""
 79    lines = ["# Test Document\n\n"]
 80
 81    for i in range(num_links):
 82        if i % 3 == 0:
 83            lines.append(f"Check out [Link {i}](https://example.com/{i})\n")
 84        elif i % 3 == 1:
 85            lines.append(f"See [Reference {i}][ref{i}]\n")
 86        else:
 87            lines.append(f"Paragraph {i} with some text.\n")
 88
 89    lines.append("\n")
 90    for i in range(num_links):
 91        if i % 3 == 1:
 92            lines.append(f"[ref{i}]: https://example.com/ref/{i}\n")
 93
 94    return "".join(lines)
 95
 96# ===== Profiling Functions =====
 97
 98def run_cprofile_analysis(iterations: int = 50, num_links: int = 500):
 99    """Run cProfile analysis"""
100    print("Running cProfile Analysis")
101    print("=" * 70)
102
103    content = generate_test_content(num_links)
104    checker = MarkdownLinkChecker()
105
106    profiler = cProfile.Profile()
107    profiler.enable()
108
109    for _ in range(iterations):
110        checker.parse_markdown_links(content)
111
112    profiler.disable()
113
114    stats = pstats.Stats(profiler)
115    stats.sort_stats(SortKey.CUMULATIVE)
116
117    print(f"\nTop 15 functions by cumulative time:")
118    print("-" * 70)
119    stats.print_stats(15)
120
121    return stats
122
123def run_regex_benchmark():
124    """Benchmark different regex patterns"""
125    print("\nRegex Pattern Benchmark")
126    print("=" * 70)
127
128    content = generate_test_content(500)
129
130    patterns = {
131        "Original": re.compile(r'(?),
132        "Non-greedy inner": re.compile(r'(?),
133        "Anchored": re.compile(r'(?),
134    }
135
136    print(f"{'Pattern':<25} {'Time (ms)':<12} {'Matches':<10}")
137    print("-" * 50)
138
139    for name, pattern in patterns.items():
140        # Warmup
141        list(pattern.finditer(content))
142
143        # Benchmark
144        start = time.perf_counter()
145        for _ in range(100):
146            matches = list(pattern.finditer(content))
147        elapsed = (time.perf_counter() - start) * 1000
148
149        print(f"{name:<25} {elapsed:<12.2f} {len(matches):<10}")
150
151def run_compile_comparison():
152    """Compare precompiled vs inline regex"""
153    print("\nCompile Strategy Comparison")
154    print("=" * 70)
155
156    content = generate_test_content(500)
157    iterations = 100
158    pattern_str = r'(?
159
160    # Precompiled
161    compiled = re.compile(pattern_str)
162    start = time.perf_counter()
163    for _ in range(iterations):
164        list(compiled.finditer(content))
165    compiled_time = time.perf_counter() - start
166
167    # Inline (uses re module cache)
168    start = time.perf_counter()
169    for _ in range(iterations):
170        list(re.finditer(pattern_str, content))
171    inline_time = time.perf_counter() - start
172
173    print(f"{'Strategy':<25} {'Time (ms)':<12} {'Relative':<10}")
174    print("-" * 50)
175    print(f"{'Precompiled':<25} {compiled_time*1000:<12.2f} {'1.00x':<10}")
176    print(f"{'Inline (cached)':<25} {inline_time*1000:<12.2f} {inline_time/compiled_time:.2f}x")
177
178def main():
179    parser = argparse.ArgumentParser(description="Profiling Demo")
180    parser.add_argument('--full', action='store_true', help='Run full analysis')
181    parser.add_argument('--quick', action='store_true', help='Run quick analysis')
182    parser.add_argument('--regex', action='store_true', help='Run regex benchmark')
183    args = parser.parse_args()
184
185    if args.regex:
186        run_regex_benchmark()
187        run_compile_comparison()
188    elif args.quick:
189        run_cprofile_analysis(iterations=10, num_links=100)
190    else:
191        run_cprofile_analysis()
192        run_regex_benchmark()
193        run_compile_comparison()
194
195if __name__ == "__main__":
196    main()

分析結果範例

執行 cProfile 分析後的典型輸出：

 1Running cProfile Analysis
 2======================================================================
 3
 4Top 15 functions by cumulative time:
 5----------------------------------------------------------------------
 6         125003 function calls in 0.892 seconds
 7
 8   Ordered by: cumulative time
 9
10   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
11       50    0.012    0.000    0.892    0.018 checker.py:45(parse_markdown_links)
12    25000    0.234    0.000    0.567    0.000 {method 'finditer' of 're.Pattern'}
13       50    0.089    0.002    0.089    0.002 {method 'split' of 'str' objects}
14    50000    0.156    0.000    0.156    0.000 {method 'append' of 'list' objects}
15    25000    0.098    0.000    0.098    0.000 {method 'group' of 're.Match'}
16    12500    0.045    0.000    0.045    0.000 {method 'lower' of 'str' objects}
17    12500    0.034    0.000    0.034    0.000 {method 'strip' of 'str' objects}
18    25000    0.067    0.000    0.067    0.000 {method 'startswith' of 'str' objects}
19       50    0.023    0.000    0.023    0.000 {built-in method builtins.enumerate}

從上述結果可以觀察到：

finditer 佔用最多時間：正則表達式匹配是主要瓶頸
split 操作耗時明顯：每次解析都建立新的行列表
append 呼叫頻繁：大量的字典建立和列表操作

line_profiler 的典型輸出：

 1Timer unit: 1e-06 s
 2
 3Total time: 0.456 s
 4File: checker.py
 5Function: parse_markdown_links at line 45
 6
 7Line #      Hits         Time  Per Hit   % Time  Line Contents
 8==============================================================
 9    45                                           def parse_markdown_links(self, content):
10    46        50       1234.0     24.7      0.3      links = []
11    47        50      89012.0   1780.2     19.5      lines = content.split('\n')
12    48
13    49        50         56.0      1.1      0.0      reference_defs = {}
14    50      2500      45678.0     18.3     10.0      for match in self.REFERENCE_DEF_PATTERN.finditer(content):
15    51      2450       3456.0      1.4      0.8          ref_name = match.group(1).lower()
16    52      2450       2345.0      1.0      0.5          ref_target = match.group(2).strip()
17    53      2450       1234.0      0.5      0.3          reference_defs[ref_name] = ref_target
18    54
19    55        50         34.0      0.7      0.0      in_code_block = False
20    56
21    57     25050      12345.0      0.5      2.7      for line_num, line in enumerate(lines, start=1):
22    58     25000      34567.0      1.4      7.6          if line.strip().startswith("```"):
23    59                                                       in_code_block = not in_code_block
24    60                                                       continue
25    61
26    62     25000       5678.0      0.2      1.2          if in_code_block:
27    63                                                       continue
28    64
29    65     25000     156789.0      6.3     34.4          for match in self.INLINE_LINK_PATTERN.finditer(line):
30    66      8350      23456.0      2.8      5.1              links.append({...})
31    67
32    68     25000      78901.0      3.2     17.3          for match in self.REFERENCE_USE_PATTERN.finditer(line):
33    69      2450       1234.0      0.5      0.3              ref_name = match.group(2).lower()
34    70      2450        567.0      0.2      0.1              if ref_name in reference_defs:
35    71      2450       1234.0      0.5      0.3                  links.append({...})
36    72
37    73        50         23.0      0.5      0.0      return links

關鍵發現：

第 65 行（行內連結匹配）佔 34.4%：這是最大的瓶頸
第 47 行（split）佔 19.5%：字串分割是第二大消耗
第 68 行（引用連結匹配）佔 17.3%：也是重要的優化目標

設計權衡

面向	不分析	使用 cProfile	使用 line_profiler
開發時間	少	中等	較多
分析粒度	無	函式級	行級
效能開銷	無	低	較高
適用場景	簡單程式	一般優化	精確定位
學習成本	無	低	中等
結果準確度	-	高	非常高

什麼時候該做效能分析？

適合分析：

程式明顯變慢
處理大量資料
發布前的效能驗證
正則表達式複雜時
有迴圈處理大量項目

不建議過早優化：

功能還在開發中
使用頻率很低
效能已經足夠
可讀性更重要時

練習

基礎練習：用 cProfile 分析排序函式

 1"""
 2Exercise 1: Profile different sorting approaches
 3"""
 4import cProfile
 5import pstats
 6import random
 7from pstats import SortKey
 8
 9def bubble_sort(arr):
10    """Bubble sort implementation"""
11    n = len(arr)
12    arr = arr.copy()
13    for i in range(n):
14        for j in range(0, n - i - 1):
15            if arr[j] > arr[j + 1]:
16                arr[j], arr[j + 1] = arr[j + 1], arr[j]
17    return arr
18
19def quick_sort(arr):
20    """Quick sort implementation"""
21    if len(arr) <= 1:
22        return arr
23    pivot = arr[len(arr) // 2]
24    left = [x for x in arr if x < pivot]
25    middle = [x for x in arr if x == pivot]
26    right = [x for x in arr if x > pivot]
27    return quick_sort(left) + middle + quick_sort(right)
28
29def profile_sorting():
30    """Profile and compare sorting algorithms"""
31    data = [random.randint(0, 10000) for _ in range(1000)]
32
33    # Profile bubble sort
34    profiler = cProfile.Profile()
35    profiler.enable()
36    bubble_sort(data)
37    profiler.disable()
38
39    print("Bubble Sort Profile:")
40    stats = pstats.Stats(profiler)
41    stats.sort_stats(SortKey.TIME).print_stats(5)
42
43    # Profile quick sort
44    profiler = cProfile.Profile()
45    profiler.enable()
46    quick_sort(data)
47    profiler.disable()
48
49    print("\nQuick Sort Profile:")
50    stats = pstats.Stats(profiler)
51    stats.sort_stats(SortKey.TIME).print_stats(5)
52
53if __name__ == "__main__":
54    profile_sorting()

進階練習：用 line_profiler 找出熱點程式碼

 1"""
 2Exercise 2: Use line_profiler to find hotspots
 3
 4Instructions:
 51. Install line_profiler: pip install line_profiler
 62. Add @profile decorator to functions you want to analyze
 73. Run: kernprof -l -v exercise2.py
 8"""
 9from line_profiler import profile
10
11@profile
12def find_primes(n):
13    """Find all prime numbers up to n"""
14    primes = []
15    for num in range(2, n + 1):
16        is_prime = True
17        for i in range(2, int(num ** 0.5) + 1):
18            if num % i == 0:
19                is_prime = False
20                break
21        if is_prime:
22            primes.append(num)
23    return primes
24
25@profile
26def find_primes_sieve(n):
27    """Find primes using Sieve of Eratosthenes"""
28    sieve = [True] * (n + 1)
29    sieve[0] = sieve[1] = False
30
31    for i in range(2, int(n ** 0.5) + 1):
32        if sieve[i]:
33            for j in range(i * i, n + 1, i):
34                sieve[j] = False
35
36    return [i for i, is_prime in enumerate(sieve) if is_prime]
37
38if __name__ == "__main__":
39    print("Finding primes up to 10000...")
40    primes1 = find_primes(10000)
41    primes2 = find_primes_sieve(10000)
42    print(f"Found {len(primes1)} primes (basic)")
43    print(f"Found {len(primes2)} primes (sieve)")

挑戰題：比較不同正則表達式寫法的效能差異

 1"""
 2Exercise 3: Compare regex pattern performance
 3
 4Task: Parse email addresses from text using different patterns
 5and measure their performance.
 6"""
 7import re
 8import time
 9
10def benchmark_email_patterns():
11    """Compare different email regex patterns"""
12
13    # Test content with mixed valid and invalid emails
14    test_text = """
15    Contact us at support@example.com or sales@company.org
16    Invalid: not.an.email, @missing.com, missing@
17    Valid: user.name+tag@domain.co.uk, test123@sub.domain.com
18    Edge cases: "quoted"@domain.com, user@[192.168.1.1]
19    """ * 1000
20
21    patterns = {
22        # Simple pattern (may miss some valid emails)
23        "simple": re.compile(r'\b[\w.-]+@[\w.-]+\.\w+\b'),
24
25        # More comprehensive pattern
26        "comprehensive": re.compile(
27            r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'
28        ),
29
30        # RFC 5322 inspired (complex but thorough)
31        "rfc_inspired": re.compile(
32            r'(?:[a-z0-9!#$%&\'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&\'*+/=?^_`{|}~-]+)*'
33            r'|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]'
34            r'|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")'
35            r'@(?:(?:[a-z0-9](/python-advanced/04-cpython-internals/case-studies/profiling/?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](/python-advanced/04-cpython-internals/case-studies/profiling/?:[a-z0-9-]*[a-z0-9])?'
36            r'|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}'
37            r'(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:'
38            r'(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]'
39            r'|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])',
40            re.IGNORECASE
41        ),
42    }
43
44    print("Email Pattern Performance Comparison")
45    print("=" * 60)
46    print(f"{'Pattern':<20} {'Time (ms)':<12} {'Matches':<10}")
47    print("-" * 60)
48
49    for name, pattern in patterns.items():
50        # Warmup
51        list(pattern.findall(test_text))
52
53        # Benchmark
54        start = time.perf_counter()
55        for _ in range(100):
56            matches = pattern.findall(test_text)
57        elapsed = (time.perf_counter() - start) * 1000
58
59        print(f"{name:<20} {elapsed:<12.2f} {len(matches):<10}")
60
61    # Your task: Add more patterns and analyze the results
62    # Consider: What trade-offs exist between accuracy and speed?
63
64if __name__ == "__main__":
65    benchmark_email_patterns()

延伸閱讀

下一章：記憶體優化

3.2 pprof 基礎診斷流程

Wed, 22 Apr 2026 00:00:00 +0000

pprof 的核心用途是用實際執行資料定位效能問題。它能協助觀察 heap、goroutine、CPU、block、mutex 與 trace，讓工程師從「感覺哪裡慢」改成「依 profile 判斷哪裡有壓力」。

本章目標

學完本章後，你將能夠：

安全地條件啟用 pprof endpoint
判斷 heap、goroutine、CPU、block、mutex、trace 各自回答什麼問題
用 go tool pprof 取得 profile 並閱讀 top
區分 inuse_space 與 alloc_space
把 profile 結果連回程式設計邊界

【觀察】效能問題需要先問對問題

pprof 診斷的核心起點是先確認你要回答哪個問題。不同 profile 回答不同問題，拿錯工具會讓分析變成猜測。

問題	優先 profile
記憶體持續上升	heap `inuse_space`
GC 壓力高、配置很多	heap `alloc_space`
goroutine 數量持續增加	goroutine profile
CPU 使用率高	CPU profile
goroutine 常卡在 channel 或 syscall	goroutine / trace
mutex 等待嚴重	mutex profile
channel/send/receive 阻塞多	block profile

Profile 不是一次全抓就會自動給答案。先問清楚問題，再抓對應資料，分析成本會低很多。

【判讀】pprof endpoint 是受控診斷入口

pprof endpoint 的核心安全責任是受控地暴露診斷資訊。它可能包含 goroutine stack、函式名稱、路徑、記憶體配置模式與部分請求脈絡；正式服務應把 /debug/pprof/ 放在明確啟用、內部網路或驗證保護之後。

條件啟用範例：

1import _ "net/http/pprof"
2
3func RegisterDebugEndpoints(mux *http.ServeMux) {
4    if os.Getenv("APP_PPROF") != "1" {
5        return
6    }
7
8    mux.Handle("/debug/pprof/", http.DefaultServeMux)
9}

實務上還可以只綁定 localhost、掛在內部管理 port、加上身份驗證，或只在開發與診斷環境啟用。重點是 pprof 要受控，而不是跟公開 API 一起裸露。

【執行】heap profile 看記憶體保留與配置壓力

Heap profile 的核心問題是「哪些物件佔用或配置了記憶體」。當服務記憶體持續上升時，heap profile 是第一個常用工具。

看目前仍被保留的記憶體：

1go tool pprof http://localhost:8080/debug/pprof/heap

進入 pprof 後：

1(pprof) top

inuse_space 代表目前仍被保留的記憶體，適合分析 leak、cache、map、slice、send buffer、長期持有資料。

看累積配置量：

1go tool pprof -alloc_space http://localhost:8080/debug/pprof/heap

alloc_space 代表累積配置量，適合分析 JSON marshal、slice append、短命 object、熱路徑反覆配置造成的 GC 壓力。

【判讀】heap profile 要連回資料結構

Heap profile 的核心解讀是問「誰持有資料」或「誰反覆配置」。看到某個函式在 top 裡，下一步要回到資料結構與生命週期。

常見對應：

profile 現象	可能設計問題
map 持續佔用	cache 沒有淘汰或 key 無限制成長
slice/history 佔用高	history 無上限或 list 回傳太大
JSON marshal alloc 高	高頻推送每個 client 重複 marshal
bytes.Buffer 配置高	熱路徑重複建立 buffer
websocket message 佔用高	send buffer 滿載或慢 client

Profile 給的是線索，不是最終修正。修正要回到資料模型、copy boundary、buffer policy 或 cache policy。

【執行】goroutine profile 看存活與卡住路徑

Goroutine profile 的核心問題是「哪些 goroutine 還活著，以及它們卡在哪裡」。它常用來診斷 goroutine leak、channel 等待、鎖等待與 network read 阻塞。

互動模式：

1go tool pprof http://localhost:8080/debug/pprof/goroutine

文字 stack：

1curl "http://localhost:8080/debug/pprof/goroutine?debug=2"

若大量 goroutine 卡在同一個 channel receive、send、network read、ticker loop，通常代表某個退出條件、close path、deadline 或 unregister 設計有問題。

Goroutine profile 不只看數量。少量但卡在錯誤位置的 goroutine，也可能代表資源沒有被釋放。

【執行】CPU profile 看熱路徑

CPU profile 的核心問題是「程式把 CPU 時間花在哪裡」。它需要採樣一段時間，適合分析 CPU 使用率高或 request latency 異常。

1go tool pprof "http://localhost:8080/debug/pprof/profile?seconds=30"

常用指令：

1(pprof) top
2(pprof) list Encode

CPU profile 要搭配流量情境解讀。低流量時抓到的 profile 可能沒有代表性；高流量時則要注意診斷本身也會造成額外負擔。

若 top 顯示大量時間花在 JSON encode、sort、lock、regex 或 compression，下一步應回到對應熱路徑，判斷是否可以減少工作、快取結果、改資料結構或降低呼叫頻率。

【策略】block 與 mutex profile 需要先啟用取樣

Block/mutex profile 的核心用途是分析等待，而不是分析 CPU 計算。它們通常需要在程式中設定取樣比例。

1func ConfigureBlockingProfiles() {
2    runtime.SetBlockProfileRate(1)
3    runtime.SetMutexProfileFraction(5)
4}

Block profile 看 goroutine 在同步原語上阻塞的時間，例如 channel send/receive、select、mutex。Mutex profile 看鎖競爭。

啟用取樣有成本，不一定要常駐開最高強度。診斷時可以條件啟用，或在壓測環境中使用。

【執行】trace 看排程與延遲

Trace 的核心用途是觀察 goroutine 排程、network block、syscall、GC pause 與延遲事件。它比單一 profile 更完整，但也更重。

1curl -o trace.out "http://localhost:8080/debug/pprof/trace?seconds=5"
2go tool trace trace.out

Trace 適合用在你已經知道有延遲問題，但 heap、CPU、goroutine profile 都不足以解釋時。它能顯示 goroutine 何時 runnable、何時 blocked、何時被排程。

Trace 檔案可能很大，不適合長時間收集。通常先抓短時間，確認問題窗口後再精準分析。

【策略】診斷流程要先保留現場

pprof 診斷的核心流程是先保留現場，再改程式。若你先重啟服務或調參，可能會清掉最重要的證據。

建議流程：

記錄當下流量、版本、操作、時間區間。
讀 runtime metrics：heap、GC、goroutine、queue 長度。
依問題抓 profile：heap、goroutine、CPU 或 trace。
用 profile 找出函式與 stack pattern。
回到程式碼確認資料結構、goroutine lifecycle 或 hot path。
修改後用相同情境再抓一次 profile 驗證。

這個流程能避免「看到 top 第一名就改」的衝動。Profile 需要和情境一起讀，才不會誤判。

本章不處理

本章先處理單一服務內的 profile 讀法；商用 APM 與分散式 tracing，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 goroutine、allocation 與 runtime metrics；如果你要先回看語言教材，可以讀：

小結

pprof 是診斷工具，不是公開 API。Heap profile 看保留與配置，goroutine profile 看存活與卡住路徑，CPU profile 看熱點，block/mutex profile 看等待，trace 看排程與延遲。好的診斷流程會先問對問題、抓對 profile，再把結果連回資料結構、goroutine lifecycle 與服務行為。

8.2 效能調優實戰

Wed, 21 Jan 2026 00:00:00 +0000

在入門系列中，我們學習了效能優化的原則和工具。本章將這些知識應用於 .claude/lib 的實際程式碼，展示如何從「發現問題」到「驗證效果」的完整流程。

學習目標

完成本章後，你將能夠：

使用 cProfile 分析真實程式碼的效能瓶頸
判斷哪些程式碼值得優化
應用正則表達式預編譯提升效能
使用 functools.lru_cache 實現有效的快取策略
根據查詢模式選擇適當的資料結構

先備知識

本章假設你已經閱讀：

入門系列 3.8 效能迷思與優化策略 - 效能測量工具與優化原則

如果你還不熟悉 cProfile、timeit 或「過早優化是萬惡之源」這句話的含義，請先閱讀入門系列。

效能分析流程

優化的正確流程是：

11. 測量基準效能
2       ↓
32. 找出瓶頸（cProfile）
4       ↓
53. 針對瓶頸優化
6       ↓
74. 驗證優化效果
8       ↓
95. 評估維護成本

最重要的原則：先測量，後優化。沒有測量數據的優化是盲目的。

真實案例：Hook 驗證器

我們以 .claude/lib/hook_validator.py 為例。這個工具用來驗證 Hook 腳本是否符合專案規範，核心功能是透過正則表達式檢查程式碼內容。

 1class HookValidator:
 2    """Hook 合規性驗證器"""
 3
 4    # 共用模組導入模式
 5    HOOK_IO_PATTERNS = [
 6        r"from\s+hook_io\s+import",
 7        r"from\s+lib\.hook_io\s+import",
 8    ]
 9
10    HOOK_LOGGING_PATTERNS = [
11        r"from\s+hook_logging\s+import",
12        r"from\s+lib\.hook_logging\s+import",
13    ]
14
15    # ... 更多模式 ...
16
17    def _has_import(self, content: str, patterns: list[str]) -> bool:
18        """檢查是否有符合任一模式的導入"""
19        return any(
20            re.search(pattern, content)
21            for pattern in patterns
22        )

這段程式碼有什麼效能問題？讓我們用 cProfile 來找出答案。

步驟 1：測量基準效能

首先，建立測試環境並測量原始版本的效能：

 1import cProfile
 2import pstats
 3import re
 4from pstats import SortKey
 5
 6def generate_test_content(num_lines: int = 500) -> str:
 7    """生成測試用的 Hook 腳本內容"""
 8    lines = [
 9        '#!/usr/bin/env python3',
10        '"""Test hook script"""',
11        'import os',
12        'import sys',
13        'from hook_io import read_hook_input, write_hook_output',
14        'from hook_logging import setup_hook_logging',
15        '',
16    ]
17
18    # 加入更多程式碼行
19    for i in range(num_lines):
20        if i % 10 == 0:
21            lines.append(f'def function_{i}():')
22            lines.append(f'    """Function {i}"""')
23        lines.append(f'    x_{i} = {i}')
24
25    return '\n'.join(lines)
26
27def benchmark_original(content: str, iterations: int = 100):
28    """測量原始版本的效能"""
29
30    # 原始實作：每次呼叫都重新編譯正則表達式
31    patterns = [
32        r"from\s+hook_io\s+import",
33        r"from\s+lib\.hook_io\s+import",
34    ]
35
36    def has_import_original(content: str, patterns: list[str]) -> bool:
37        return any(
38            re.search(pattern, content)
39            for pattern in patterns
40        )
41
42    # 執行效能分析
43    profiler = cProfile.Profile()
44    profiler.enable()
45
46    for _ in range(iterations):
47        has_import_original(content, patterns)
48
49    profiler.disable()
50
51    stats = pstats.Stats(profiler)
52    stats.sort_stats(SortKey.CUMULATIVE)
53    stats.print_stats(10)
54
55    return stats
56
57# 執行測試
58content = generate_test_content(1000)
59print("=== 原始版本效能 ===")
60benchmark_original(content)

執行後的輸出類似：

1=== 原始版本效能 ===
2         501 function calls in 0.0234 seconds
3
4   Ordered by: cumulative time
5
6   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
7      100    0.001    0.000    0.023    0.000 test.py:30(has_import_original)
8      200    0.022    0.000    0.022    0.000 {method 'search' of 're.Pattern'}
9      100    0.000    0.000    0.000    0.000 {built-in method builtins.any}

觀察結果：re.search 佔用了大部分時間。

步驟 2：找出瓶頸

從 cProfile 結果可以看到，re.search 被呼叫了 200 次（100 次迭代 x 2 個 pattern）。

問題在於：re.search(pattern, content) 每次呼叫時都會重新編譯正則表達式。

雖然 Python 的 re 模組有內部快取（最近使用的 pattern 會被快取），但：

快取有大小限制（預設 512 個）
查詢快取本身也有開銷
在 Hook 驗證器中有多達 20+ 個不同的 pattern

正則表達式預編譯

問題：重複編譯的開銷

來看 hook_validator.py 中的實際程式碼：

 1class HookValidator:
 2    """Hook 合規性驗證器"""
 3
 4    # 模式定義為字串列表
 5    HOOK_IO_PATTERNS = [
 6        r"from\s+hook_io\s+import",
 7        r"from\s+lib\.hook_io\s+import",
 8    ]
 9
10    HOOK_LOGGING_PATTERNS = [
11        r"from\s+hook_logging\s+import",
12        r"from\s+lib\.hook_logging\s+import",
13    ]
14
15    CONFIG_LOADER_PATTERNS = [
16        r"from\s+config_loader\s+import",
17        r"from\s+lib\.config_loader\s+import",
18    ]
19
20    GIT_UTILS_PATTERNS = [
21        r"from\s+git_utils\s+import",
22        r"from\s+lib\.git_utils\s+import",
23    ]
24
25    # 輸出函式使用模式
26    OUTPUT_PATTERNS = [
27        r"write_hook_output\s*\(",
28        r"create_pretooluse_output\s*\(",
29        r"create_posttooluse_output\s*\(",
30    ]
31
32    # 不推薦的輸出模式
33    BAD_OUTPUT_PATTERNS = [
34        r'print\s*\(\s*json\.dumps\s*\(',
35        r'sys\.stdout\.write\s*\(\s*json\.dumps\s*\(',
36    ]
37
38    def _has_import(self, content: str, patterns: list[str]) -> bool:
39        """檢查是否有符合任一模式的導入"""
40        return any(
41            re.search(pattern, content)  # 每次都要編譯！
42            for pattern in patterns
43        )

每次呼叫 _has_import 時，所有 pattern 都會被重新處理。

解決方案：預編譯

將字串 pattern 改為預編譯的 re.Pattern 物件：

 1import re
 2from typing import Pattern
 3
 4class HookValidatorOptimized:
 5    """優化版 Hook 驗證器"""
 6
 7    # 預編譯的正則表達式模式
 8    HOOK_IO_PATTERNS: list[Pattern] = [
 9        re.compile(r"from\s+hook_io\s+import"),
10        re.compile(r"from\s+lib\.hook_io\s+import"),
11    ]
12
13    HOOK_LOGGING_PATTERNS: list[Pattern] = [
14        re.compile(r"from\s+hook_logging\s+import"),
15        re.compile(r"from\s+lib\.hook_logging\s+import"),
16    ]
17
18    CONFIG_LOADER_PATTERNS: list[Pattern] = [
19        re.compile(r"from\s+config_loader\s+import"),
20        re.compile(r"from\s+lib\.config_loader\s+import"),
21    ]
22
23    GIT_UTILS_PATTERNS: list[Pattern] = [
24        re.compile(r"from\s+git_utils\s+import"),
25        re.compile(r"from\s+lib\.git_utils\s+import"),
26    ]
27
28    OUTPUT_PATTERNS: list[Pattern] = [
29        re.compile(r"write_hook_output\s*\("),
30        re.compile(r"create_pretooluse_output\s*\("),
31        re.compile(r"create_posttooluse_output\s*\("),
32    ]
33
34    BAD_OUTPUT_PATTERNS: list[Pattern] = [
35        re.compile(r'print\s*\(\s*json\.dumps\s*\('),
36        re.compile(r'sys\.stdout\.write\s*\(\s*json\.dumps\s*\('),
37    ]
38
39    def _has_import(self, content: str, patterns: list[Pattern]) -> bool:
40        """檢查是否有符合任一模式的導入"""
41        return any(
42            pattern.search(content)  # 直接使用預編譯的 pattern
43            for pattern in patterns
44        )

效能測量

比較預編譯和非預編譯的效能差異：

 1import re
 2import time
 3
 4def compare_regex_performance():
 5    """比較預編譯 vs 非預編譯的效能"""
 6
 7    content = generate_test_content(1000)
 8    iterations = 1000
 9
10    # 字串 pattern
11    str_patterns = [
12        r"from\s+hook_io\s+import",
13        r"from\s+lib\.hook_io\s+import",
14    ]
15
16    # 預編譯 pattern
17    compiled_patterns = [re.compile(p) for p in str_patterns]
18
19    # 測試 1：使用字串 pattern
20    start = time.perf_counter()
21    for _ in range(iterations):
22        any(re.search(p, content) for p in str_patterns)
23    str_time = time.perf_counter() - start
24
25    # 測試 2：使用預編譯 pattern
26    start = time.perf_counter()
27    for _ in range(iterations):
28        any(p.search(content) for p in compiled_patterns)
29    compiled_time = time.perf_counter() - start
30
31    print(f"字串 pattern:    {str_time:.4f}s")
32    print(f"預編譯 pattern:  {compiled_time:.4f}s")
33    print(f"加速比:          {str_time / compiled_time:.2f}x")
34
35compare_regex_performance()

典型輸出：

1字串 pattern:    0.1234s
2預編譯 pattern:  0.0987s
3加速比:          1.25x

在這個例子中，預編譯帶來約 20-30% 的效能提升。雖然不是「快 10 倍」的驚人結果，但：

改動成本極低：只需要加上 re.compile()
無風險：行為完全相同
累積效果：當有更多 pattern 時，效果更明顯

快取策略：lru_cache

適用場景

functools.lru_cache 適合用於：

純函式：相同輸入總是產生相同輸出
計算昂貴：函式執行需要較長時間
重複呼叫：同樣的參數會被多次呼叫

實作範例：分支保護檢查

來看 .claude/lib/git_utils.py 中的 is_protected_branch() 函式：

 1import fnmatch
 2
 3# 保護分支列表（支援 glob 模式）
 4PROTECTED_BRANCHES = [
 5    "main",
 6    "master",
 7    "develop",
 8    "release/*",
 9    "production",
10]
11
12def is_protected_branch(branch: str) -> bool:
13    """
14    檢查是否為保護分支
15
16    Args:
17        branch: 分支名稱
18
19    Returns:
20        bool: 如果是保護分支返回 True
21    """
22    for pattern in PROTECTED_BRANCHES:
23        if fnmatch.fnmatch(branch, pattern):
24            return True
25    return False

這個函式：

是純函式：相同的 branch 總是返回相同結果
會被重複呼叫：在 Hook 執行期間可能檢查同一個分支多次

加入 lru_cache

 1from functools import lru_cache
 2import fnmatch
 3
 4PROTECTED_BRANCHES = [
 5    "main",
 6    "master",
 7    "develop",
 8    "release/*",
 9    "production",
10]
11
12@lru_cache(maxsize=128)
13def is_protected_branch(branch: str) -> bool:
14    """
15    檢查是否為保護分支（帶快取）
16
17    Args:
18        branch: 分支名稱
19
20    Returns:
21        bool: 如果是保護分支返回 True
22    """
23    for pattern in PROTECTED_BRANCHES:
24        if fnmatch.fnmatch(branch, pattern):
25            return True
26    return False

快取命中率分析

 1from functools import lru_cache
 2import fnmatch
 3
 4@lru_cache(maxsize=128)
 5def is_protected_branch(branch: str) -> bool:
 6    for pattern in PROTECTED_BRANCHES:
 7        if fnmatch.fnmatch(branch, pattern):
 8            return True
 9    return False
10
11def analyze_cache_performance():
12    """分析快取命中率"""
13
14    # 模擬真實的呼叫模式
15    branches = [
16        "main", "main", "main",  # 重複檢查 main
17        "feat/new-feature",
18        "main",
19        "fix/bug-123",
20        "main",
21        "release/1.0",
22        "feat/new-feature",  # 重複
23    ]
24
25    # 清除快取統計
26    is_protected_branch.cache_clear()
27
28    for branch in branches:
29        result = is_protected_branch(branch)
30        print(f"檢查 {branch}: {result}")
31
32    # 查看快取統計
33    info = is_protected_branch.cache_info()
34    print(f"\n快取統計:")
35    print(f"  命中: {info.hits}")
36    print(f"  未命中: {info.misses}")
37    print(f"  命中率: {info.hits / (info.hits + info.misses) * 100:.1f}%")
38    print(f"  快取大小: {info.currsize}/{info.maxsize}")
39
40analyze_cache_performance()

輸出：

 1檢查 main: True
 2檢查 main: True
 3檢查 main: True
 4檢查 feat/new-feature: False
 5檢查 main: True
 6檢查 fix/bug-123: False
 7檢查 main: True
 8檢查 release/1.0: True
 9檢查 feat/new-feature: False
10
11快取統計:
12  命中: 5
13  未命中: 4
14  命中率: 55.6%
15  快取大小: 4/128

lru_cache 的注意事項

 1# 1. 參數必須是可雜湊的（hashable）
 2@lru_cache
 3def process(data: list):  # 錯誤！list 不可雜湊
 4    pass
 5
 6@lru_cache
 7def process(data: tuple):  # 正確，tuple 可雜湊
 8    pass
 9
10# 2. 注意快取大小
11@lru_cache(maxsize=None)  # 無限制，可能耗盡記憶體
12def expensive_function(x):
13    pass
14
15@lru_cache(maxsize=128)  # 建議設定合理上限
16def expensive_function(x):
17    pass
18
19# 3. 可以手動清除快取
20expensive_function.cache_clear()
21
22# 4. 查看快取統計
23info = expensive_function.cache_info()
24# CacheInfo(hits=10, misses=5, maxsize=128, currsize=5)

資料結構選擇

O(n) vs O(1) 的差異

在 hook_validator.py 中，檢查測試檔案是否存在：

 1def check_test_exists(self, hook_path: Path) -> list[ValidationIssue]:
 2    """檢查對應的測試檔案是否存在"""
 3    issues = []
 4
 5    hook_name = hook_path.stem
 6    test_name = f"test_{hook_name.replace('-', '_')}.py"
 7
 8    # 測試檔案可能在這些位置
 9    possible_test_paths = [
10        self.project_root / ".claude" / "lib" / "tests" / test_name,
11        self.project_root / ".claude" / "hooks" / "tests" / test_name,
12    ]
13
14    test_exists = any(p.exists() for p in possible_test_paths)
15    # ...

如果需要檢查多個檔案是否在某個集合中：

 1# 不好的做法：用 list，O(n) 查詢
 2existing_tests = [
 3    "test_branch_verify.py",
 4    "test_hook_io.py",
 5    "test_config_loader.py",
 6    # ... 可能有幾十個
 7]
 8
 9def has_test_slow(test_name: str) -> bool:
10    return test_name in existing_tests  # O(n)
11
12# 好的做法：用 set，O(1) 查詢
13existing_tests_set = {
14    "test_branch_verify.py",
15    "test_hook_io.py",
16    "test_config_loader.py",
17    # ...
18}
19
20def has_test_fast(test_name: str) -> bool:
21    return test_name in existing_tests_set  # O(1)

真實案例：測試檔案存在性檢查

 1import time
 2from pathlib import Path
 3
 4def compare_data_structures():
 5    """比較 list vs set 的查詢效能"""
 6
 7    # 模擬測試檔案列表
 8    test_files_list = [f"test_hook_{i}.py" for i in range(100)]
 9    test_files_set = set(test_files_list)
10
11    # 要查詢的檔案
12    queries = [f"test_hook_{i}.py" for i in range(50, 150)]  # 50 個存在，50 個不存在
13
14    iterations = 10000
15
16    # 測試 list
17    start = time.perf_counter()
18    for _ in range(iterations):
19        for q in queries:
20            _ = q in test_files_list
21    list_time = time.perf_counter() - start
22
23    # 測試 set
24    start = time.perf_counter()
25    for _ in range(iterations):
26        for q in queries:
27            _ = q in test_files_set
28    set_time = time.perf_counter() - start
29
30    print(f"List 查詢: {list_time:.4f}s")
31    print(f"Set 查詢:  {set_time:.4f}s")
32    print(f"加速比:    {list_time / set_time:.1f}x")
33
34compare_data_structures()

輸出：

1List 查詢: 0.8234s
2Set 查詢:  0.0123s
3加速比:    66.9x

當資料量為 100 個元素時，set 比 list 快約 60-70 倍。隨著資料量增加，差距會更大。

何時使用哪種資料結構

操作	list	set	dict
查詢元素是否存在	O(n)	O(1)	O(1)
依索引存取	O(1)	N/A	N/A
依鍵存取	N/A	N/A	O(1)
保持順序	Yes	No*	Yes**
允許重複	Yes	No	Keys: No

* Python 3.7+ 的 set 實際上保持插入順序，但這是實作細節，不是語言保證。 ** Python 3.7+ 的 dict 保證保持插入順序。

選擇指南：

需要頻繁查詢「是否存在」→ 用 set
需要依索引存取 → 用 list
需要鍵值對應 → 用 dict
需要去重 → 用 set

優化的代價

每個優化都有代價，需要評估是否值得。

維護成本

優化技術	效能提升	程式碼複雜度	維護成本
正則表達式預編譯	20-30%	低	低
lru_cache	視命中率而定	低	中（需注意快取失效）
list → set	數十倍	低	低
自訂資料結構	視情況	高	高

何時不該優化

 1# 不值得優化的情況
 2
 3# 1. 執行次數很少
 4def setup_once():
 5    """只在程式啟動時執行一次"""
 6    config = load_all_configs()  # 即使慢也只執行一次
 7    return config
 8
 9# 2. 已經夠快了
10def check_single_file(path: str) -> bool:
11    """檢查單一檔案是否存在"""
12    return Path(path).exists()  # 0.0001s，不需要優化
13
14# 3. I/O 才是真正的瓶頸
15def process_files(paths: list[str]):
16    for path in paths:
17        content = Path(path).read_text()  # 瓶頸在這裡
18        result = process(content)  # 這裡快 10 倍也沒用

優化前檢查清單

在優化之前，問自己：

這段程式碼是瓶頸嗎？ - 用 cProfile 確認
執行頻率高嗎？ - 每秒執行一次 vs 每天執行一次
優化後維護成本增加多少？ - 複雜度 vs 效能
有更簡單的解決方案嗎？ - 演算法改進 vs 微優化

思考題

在什麼情況下，預編譯正則表達式反而可能降低效能？
lru_cache 不適合用在什麼樣的函式上？
如果一個函式既需要快取，又需要在某些條件下強制重新計算，你會如何設計？
為什麼說「先測量，後優化」很重要？能舉一個反例嗎？

實作練習

練習 1：分析現有程式碼

用 cProfile 分析你自己專案中的一段程式碼，找出效能瓶頸。

 1import cProfile
 2import pstats
 3from pstats import SortKey
 4
 5# 替換為你要分析的函式
 6def your_function():
 7    pass
 8
 9profiler = cProfile.Profile()
10profiler.enable()
11
12# 執行多次以獲得可靠數據
13for _ in range(100):
14    your_function()
15
16profiler.disable()
17stats = pstats.Stats(profiler)
18stats.sort_stats(SortKey.CUMULATIVE)
19stats.print_stats(10)

練習 2：實作帶統計的快取

擴展 lru_cache，加入更詳細的統計資訊：

 1from functools import wraps
 2from typing import Callable, TypeVar
 3from collections import defaultdict
 4import time
 5
 6T = TypeVar('T')
 7
 8def cached_with_stats(maxsize: int = 128):
 9    """
10    帶統計資訊的快取裝飾器
11
12    統計項目：
13    - 命中/未命中次數
14    - 平均執行時間
15    - 各參數的呼叫次數
16    """
17    def decorator(func: Callable[..., T]) -> Callable[..., T]:
18        # 你的實作
19        pass
20    return decorator

練習 3：效能比較

比較以下三種檢查字串是否包含多個關鍵字的方法：

 1keywords = ["error", "warning", "critical", "fatal"]
 2
 3# 方法 1：多個 in 檢查
 4def method1(text: str) -> bool:
 5    return any(kw in text for kw in keywords)
 6
 7# 方法 2：正則表達式
 8import re
 9pattern = re.compile("|".join(keywords))
10def method2(text: str) -> bool:
11    return bool(pattern.search(text))
12
13# 方法 3：set 交集
14keywords_set = set(keywords)
15def method3(text: str) -> bool:
16    words = set(text.lower().split())
17    return bool(words & keywords_set)
18
19# 測試並比較效能
20# ...

3.3 goroutine leak 偵測

Wed, 22 Apr 2026 00:00:00 +0000

Goroutine leak 偵測的核心目標是確認已經沒有存在價值的 goroutine 能被停止。它通常是生命週期問題：誰取消、誰 close、誰解除 I/O 阻塞、誰停止 ticker。

本章目標

學完本章後，你將能夠：

分辨合理長期 goroutine 與 goroutine leak
用 context、done channel、connection close 設計退出路徑
用 pprof goroutine profile 判讀卡住 stack
測試 worker、ticker、WebSocket pump 是否能退出
從 leak pattern 回到 ownership 修正

【觀察】goroutine leak 是生命週期沒有結束

Goroutine leak 的核心定義是某個 goroutine 已經沒有存在價值，卻仍然活著。它可能卡在 channel receive、channel send、network read、ticker、mutex 或永遠不會觸發的 select case。

反模式：

1func StartWorker(jobs <-chan Job) {
2    go func() {
3        for job := range jobs {
4            process(job)
5        }
6    }()
7}

這個 worker 只有在 jobs 被關閉時才會退出。若呼叫端永遠不關閉 jobs，而 worker 也沒有 context，這個 goroutine 可能永久存在。

長期存在不一定是 leak。HTTP server accept loop、metrics exporter、background scheduler 都可能合理存在；問題是它們是否有明確停止條件，且 shutdown 時是否真的會走到。

【判讀】每個 goroutine 都要有退出原因

Goroutine lifecycle 的核心檢查是每個 goroutine 都能回答三個問題：

誰要求它停止？
它如果卡在 channel 或 I/O，如何被喚醒？
它停止後如何讓測試或上層知道？

若三題任一題答不出來，就有 leak 風險。

例如 worker 應該有 context：

 1func RunWorker(ctx context.Context, jobs <-chan Job) {
 2    for {
 3        select {
 4        case <-ctx.Done():
 5            return
 6        case job, ok := <-jobs:
 7            if !ok {
 8                return
 9            }
10            process(job)
11        }
12    }
13}

這個 worker 有兩條退出路徑：上層取消 context，或 jobs channel 被關閉。這比只依賴 channel close 更容易整合到服務 shutdown。

【策略】I/O 阻塞需要 deadline 或 close

I/O goroutine 的核心風險是 context 本身不一定能打斷底層阻塞呼叫。WebSocket read、TCP read、file watcher、外部 API call 都要確認是否支援 context、deadline 或 close。

WebSocket read pump 常見退出方式：

 1func (c *Client) readPump(ctx context.Context, hub *Hub, router MessageRouter) {
 2    defer func() {
 3        hub.unregister <- c
 4    }()
 5
 6    for {
 7        var message ClientMessage
 8        if err := c.conn.ReadJSON(&message); err != nil {
 9            return
10        }
11        _ = router.Route(ctx, c, message)
12    }
13}

若 ReadJSON 卡住，context 取消不一定直接讓它返回。實務上需要 read deadline、connection close 或 heartbeat 讓 read pump 有機會退出。

【執行】done channel 讓測試能觀察退出

測試 goroutine 是否退出的核心問題是需要可觀察訊號。done channel 可以在 goroutine 結束時 close。

 1func RunWorker(ctx context.Context, jobs <-chan Job, done chan<- struct{}) {
 2    defer close(done)
 3
 4    for {
 5        select {
 6        case <-ctx.Done():
 7            return
 8        case job, ok := <-jobs:
 9            if !ok {
10                return
11            }
12            process(job)
13        }
14    }
15}

測試：

 1func TestRunWorkerStops(t *testing.T) {
 2    ctx, cancel := context.WithCancel(context.Background())
 3    jobs := make(chan Job)
 4    done := make(chan struct{})
 5
 6    go RunWorker(ctx, jobs, done)
 7    cancel()
 8
 9    select {
10    case <-done:
11    case <-time.After(time.Second):
12        t.Fatalf("worker did not stop")
13    }
14}

Timeout 是測試保護，不是功能本身。真正的退出訊號是 done 被關閉。

【執行】ticker 必須停止

Ticker leak 的核心原因是建立 ticker 後沒有呼叫 Stop。Ticker 會持有 runtime 資源；長時間服務若反覆建立不停止，會累積不必要成本。

 1func RunCleanup(ctx context.Context) {
 2    ticker := time.NewTicker(time.Minute)
 3    defer ticker.Stop()
 4
 5    for {
 6        select {
 7        case <-ctx.Done():
 8            return
 9        case <-ticker.C:
10            cleanup()
11        }
12    }
13}

defer ticker.Stop() 應緊跟在成功建立 ticker 後。這樣不管函式因 context、錯誤或 channel 關閉退出，ticker 都會被停止。

time.After 在一次性 timeout 很方便，但在高頻迴圈裡反覆建立 timer 可能造成額外配置。需要重複觸發時，優先使用 Ticker 或可重設的 Timer 並明確停止。

【判讀】pprof goroutine profile 看 stack pattern

Goroutine profile 的核心價值是顯示 goroutine stack。當 goroutine 數量持續上升時，先看它們卡在哪裡。

1curl "http://localhost:8080/debug/pprof/goroutine?debug=2"

常見 pattern：

stack 類型	可能原因	回到哪個邊界
channel receive	上游不會再送，也沒 close/context	channel ownership
channel send	下游不再接收或 buffer 滿	backpressure / unregister
network read	沒有 deadline 或 connection 未 close	heartbeat / I/O lifecycle
ticker loop	context 沒接上或 ticker 未 stop	select loop lifecycle
mutex lock	鎖競爭或死鎖	shared state owner

看到 stack 後，下一步是回到對應 lifecycle 設計：誰負責停止，誰負責釋放阻塞點。

【策略】WebSocket pump leak 要看 read/write/unregister 三方

WebSocket goroutine leak 的核心常見原因是 read pump、write pump、hub unregister 沒有形成閉環。

目標流程：

 1read pump error 或 connection close
 2        │
 3        ▼
 4hub unregister
 5        │
 6        ├── close client.send
 7        └── close conn
 8        │
 9        ▼
10write pump exits

若 hub 沒有 close send，write pump 可能一直等。若 connection 沒有 close，read pump 可能卡在 read。若 unregister 不是 idempotent，重複 close 可能 panic。

Goroutine profile 若顯示大量 goroutine 卡在 writePump 的 send receive，通常要檢查 client.send 是否會被 close。若卡在 ReadJSON，要檢查 read deadline、heartbeat 與 connection close。

【測試】用 goroutine 數量做粗略回歸檢查

Goroutine 數量測試的核心用途是粗略檢查是否有明顯 leak。它不是精準證明，因為 Go runtime 與測試環境本身也會有 goroutine。

 1func TestNoObviousGoroutineLeak(t *testing.T) {
 2    before := runtime.NumGoroutine()
 3
 4    ctx, cancel := context.WithCancel(context.Background())
 5    done := make(chan struct{})
 6    go func() {
 7        defer close(done)
 8        RunWorker(ctx, make(chan Job))
 9    }()
10
11    cancel()
12    select {
13    case <-done:
14    case <-time.After(time.Second):
15        t.Fatalf("worker did not stop")
16    }
17
18    eventually(t, time.Second, func() bool {
19        return runtime.NumGoroutine() <= before+2
20    })
21}

這類測試要留緩衝，避免因 runtime 或其他測試 goroutine 造成假失敗。更可靠的測試仍是等待明確 done 訊號。

【判讀】goroutine leak 修正要改停止路徑

Goroutine leak 的核心修正是補上停止路徑。

常見修正：

加入 ctx.Done() case。
關閉由自己擁有的 output channel。
由 coordinator 等 sender 完成再 close。
對 network read/write 設定 deadline。
shutdown 時 close connection。
ticker 建立後 defer Stop()。
hub unregister 時 close send channel。

修正後要用測試證明退出路徑真的會發生，再用 pprof 或 goroutine count 驗證趨勢。

本章不處理

本章先處理 goroutine 的啟動、停止與阻塞邊界；更完整的 worker 全域治理，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 goroutine lifecycle、channel 與 shutdown；如果你要先回看語言教材，可以讀：

小結

Goroutine leak 是生命週期問題。每個長期 goroutine 都應知道誰能停止它、如何解除阻塞、如何讓測試觀察退出。Context、done channel、deadline、connection close、ticker stop 與 hub unregister 是主要工具。pprof goroutine profile 則用來確認還活著的 goroutine 卡在哪個邊界。

模組三：Runtime 與效能診斷

Wed, 22 Apr 2026 00:00:00 +0000

Runtime 診斷的核心目標是用資料判斷服務壓力來源。Go 服務長時間運行後，問題常出現在 heap 成長、GC 壓力、goroutine 數量、WebSocket buffer 堆積、JSON 配置與共享狀態保留；診斷流程應先看趨勢，再用 profile 定位來源。

本模組承接前面的並發、WebSocket 與測試可靠性：如果 goroutine lifecycle、send buffer、repository copy boundary 沒設計好，runtime 訊號會在 heap profile、goroutine profile、CPU profile 或 allocation profile 中反映出來。

章節列表

章節	主題	關鍵收穫
3.1	GC 與 memory limit	理解 heap、GOGC、memory limit 與 runtime metrics 的關係
3.2	pprof 基礎診斷流程	用 heap、goroutine、CPU、trace profile 定位壓力來源
3.3	goroutine leak 偵測	從 stack pattern 回到 context、close、deadline 與 ticker lifecycle
3.4	資料結構與 allocation 壓力	區分必要 copy、安全邊界與可優化熱路徑配置

本模組使用的範例主題

本模組使用虛構的即時通知服務作為範例。範例包含 WebSocket client lifecycle、background worker、repository list、JSON push payload 與 cache。

範例只用來展示 Go runtime 診斷方法，不假設讀者正在維護任何特定專案。

本模組的 Go 核心概念

用 runtime.ReadMemStats 或 runtime/metrics 觀察 heap、GC 與 goroutine 趨勢。
用 debug.SetMemoryLimit 給 runtime 軟性記憶體目標。
用 pprof 分析 heap、goroutine、CPU、block、mutex 與 trace。
用 goroutine profile 找出卡在 channel、network read、ticker、mutex 的路徑。
用 alloc_space 與 inuse_space 區分配置壓力與保留記憶體。
用資料結構設計降低不必要 allocation，但保留必要 copy boundary。

學習重點

學完本模組後，你應該能判斷：

記憶體問題是 GC 壓力、長期保留，還是短暫尖峰
什麼情境適合調整 memory limit，什麼情境應該找 leak
heap、goroutine、CPU、trace 各自回答什麼問題
goroutine leak 應回到哪個 lifecycle 邊界修
allocation 優化何時值得做，何時會破壞安全邊界

本模組不處理

本模組不討論分散式 tracing 平台、完整監控系統或雲端特定 profiler。這些工具可以接在本模組之後；本模組先建立 Go runtime 原生訊號與 pprof 的診斷思路。後續可接 Observability pipeline、metrics 與 tracing。

3.4 資料結構與 allocation 壓力

Wed, 22 Apr 2026 00:00:00 +0000

Allocation 分析的核心目標是區分必要的安全複製與可優化的重複配置。Go 服務中很多配置來自 slice 成長、map/list 複製、JSON marshal、buffer 建立與 WebSocket payload；優化前要先確認配置是否位於熱路徑，且不能破壞狀態邊界。

本章目標

學完本章後，你將能夠：

理解 allocation 如何增加 GC 壓力
分辨必要 copy boundary 與不必要重複配置
用預配置降低 slice 成長成本
判斷 JSON marshal 與 WebSocket payload 的重用邊界
用 pprof 的 alloc_space 與 inuse_space 決定優化方向

【觀察】allocation 壓力會放大 GC 成本

Allocation 的核心影響是增加 heap 成長速度，進而增加 GC 工作量。即使物件很快被回收，大量短命配置仍可能造成 CPU 與 latency 壓力。

常見熱路徑：

每次 WebSocket broadcast 都對每個 client 重新 marshal。
每次 API list 都建立大型 slice。
每次 repository 查詢都 copy 大型 map。
每次 log 都組大量臨時欄位。
每次 encode 都建立新的 bytes.Buffer。

不是所有 allocation 都要消除。診斷重點是找出高頻、可避免、且不破壞邊界的配置。

【判讀】預配置解決的是成長成本

Slice 預配置的核心用途是讓底層 array 成長符合預期。若結果長度可預估，應用 make 設定容量。

未預配置：

1func BuildNames(users []User) []string {
2    var names []string
3    for _, user := range users {
4        names = append(names, user.Name)
5    }
6    return names
7}

預配置：

1func BuildNames(users []User) []string {
2    names := make([]string, 0, len(users))
3    for _, user := range users {
4        names = append(names, user.Name)
5    }
6    return names
7}

這不是微優化。若這段程式在高頻 list API、background projection 或 broadcast path 中執行，預配置可以減少反覆擴容與 copy。

【判讀】copy boundary 是必要成本

安全複製的核心目的是保護內部可變狀態。Repository 回傳資料時 copy slice 或 map，會增加 allocation，但能避免外部突變與 data race。

 1func (r *UserRepository) ListUsers(ctx context.Context) ([]User, error) {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    users := make([]User, 0, len(r.users))
 6    for _, user := range r.users {
 7        users = append(users, user)
 8    }
 9    return users, nil
10}

這個 allocation 是狀態邊界的成本。優化前要先確認它是否真的是瓶頸，不能只因為 profile 看到配置就移除 copy。

若列表很大且讀取頻繁，應考慮分頁、projection、snapshot cache 或只回傳必要欄位。不要為了省配置而直接暴露內部 map。

【策略】大型 list 優先改資料形狀

大型 list allocation 的核心問題常常是 API 一次回太多資料。若每次請求都複製整個 repository，配置與延遲都會隨資料量線性成長。

可選策略：

策略	適用情境	代價
分頁	使用者只需要部分資料	API 需要 cursor 或 offset
projection	只需要摘要欄位	要維護讀取模型
snapshot cache	讀多寫少	要處理快取失效
incremental update	WebSocket 推送最新變化	client 要能合併狀態

優化資料形狀通常比取消 copy 更安全。Copy boundary 保護正確性，資料形狀決定每次 copy 的成本。

【執行】JSON marshal 是 WebSocket 常見配置來源

JSON 序列化的核心成本是把 Go 資料結構轉成 bytes。高頻 WebSocket 推送若對每個 client 反覆 marshal 同一份 message，會造成大量短命配置。

反模式：

1for _, client := range clients {
2    payload, err := json.Marshal(message)
3    if err != nil {
4        return err
5    }
6    client.SendBytes(payload)
7}

同一份 message 可以先 marshal 一次：

1payload, err := json.Marshal(message)
2if err != nil {
3    return err
4}
5
6for _, client := range clients {
7    client.SendBytes(payload)
8}

這個優化的前提是 payload 被視為只讀。Send path 不應修改傳入的 bytes；若某個 client 需要修改，就應在該 client 邊界 copy，而不是讓共享 payload 被改動。

【判讀】bytes 重用要先定義所有權

Bytes 重用的核心風險是共享 slice 被修改。[]byte 是可變資料，傳給多個 client 時要明確規定它只讀。

可以用型別或註解表達語意：

1type EncodedMessage []byte
2
3func (c *Client) SendEncoded(message EncodedMessage) bool {
4    return c.TrySend(ServerMessage{
5        Encoded: message,
6    })
7}

這不能從型別上完全禁止修改，但能讓 API 語意更清楚。真正保護仍靠 ownership 規則、測試與 code review。

若無法保證下游不修改，就必須 copy：

1func CloneBytes(input []byte) []byte {
2    output := make([]byte, len(input))
3    copy(output, input)
4    return output
5}

效能優化不能建立在模糊的可變資料共享上。

【策略】sync.Pool 只適合已證明的熱路徑

sync.Pool 的核心用途是複用高頻、短命、可重建的暫存物件。它可以降低配置，但會增加所有權複雜度。

 1var bufferPool = sync.Pool{
 2    New: func() any {
 3        return new(bytes.Buffer)
 4    },
 5}
 6
 7func Encode(value any) ([]byte, error) {
 8    buf := bufferPool.Get().(*bytes.Buffer)
 9    defer bufferPool.Put(buf)
10    buf.Reset()
11
12    if err := json.NewEncoder(buf).Encode(value); err != nil {
13        return nil, err
14    }
15
16    output := append([]byte(nil), buf.Bytes()...)
17    return output, nil
18}

這裡仍然 copy 出 output，因為 buf 會被放回 pool。若直接回傳 buf.Bytes()，呼叫端拿到的 slice 可能在 pool 重用後被覆寫。

不要一開始就使用 sync.Pool。先用 pprof 證明配置是瓶頸，再評估 pool 是否值得承擔額外複雜度。

【判讀】inuse 與 alloc 回答不同問題

Heap profile 的核心判讀是分清 inuse_space 與 alloc_space。

1go tool pprof http://localhost:8080/debug/pprof/heap
2go tool pprof -alloc_space http://localhost:8080/debug/pprof/heap

指標	問題	常見修正
`inuse_space` 高	現在誰保留記憶體	cache 淘汰、釋放引用、限制 buffer
`alloc_space` 高	誰累積配置最多	預配置、重用、減少 marshal、改資料形狀

若 alloc_space 高但 inuse_space 不高，代表配置很多但大多被回收，問題可能是 GC 壓力。若 inuse_space 持續上升，代表資料被長期保留，應檢查 cache、map、slice、goroutine reference 或 send buffer。

【策略】allocation 優化要保留正確性邊界

Allocation 優化的核心底線是不能破壞狀態安全。以下做法通常不可接受：

為了省 copy，直接回傳 repository 內部 map。
為了省 bytes，讓多個 client 共享可修改 payload。
為了省 allocation，把 buffer 放回 pool 後仍回傳其底層 slice。
為了少建立 struct，把 request DTO 和 domain state 混用。

較安全的優化順序：

用 pprof 確認熱點。
預配置已知大小的 slice/map。
減少重複 marshal。
改 API 資料形狀，例如分頁或 projection。
最後才考慮 sync.Pool。

這個順序先處理低風險、高可讀性的改動，再處理高複雜度工具。

【測試】優化後要補邊界測試

Allocation 優化的測試核心是確保共享資料沒有被外部修改。若你重用 bytes、snapshot 或 pooled buffer，要補測試保護 ownership。

例如 repository list 仍要回傳 copy：

 1func TestListUsersReturnsCopy(t *testing.T) {
 2    repo := NewUserRepository()
 3    ctx := context.Background()
 4    _ = repo.Save(ctx, User{ID: "user_1"})
 5
 6    users, err := repo.ListUsers(ctx)
 7    if err != nil {
 8        t.Fatalf("list users: %v", err)
 9    }
10    users[0].ID = "changed"
11
12    again, err := repo.ListUsers(ctx)
13    if err != nil {
14        t.Fatalf("list users again: %v", err)
15    }
16    if again[0].ID != "user_1" {
17        t.Fatalf("repository data was modified through returned slice")
18    }
19}

這種測試能防止未來為了省 allocation 而移除必要 copy。

本章不處理

本章先處理熱路徑上的配置與資料形狀；更大範圍的序列化與 payload 策略，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 copy boundary、JSON 與 runtime profile；如果你要先回看語言教材，可以讀：

小結

Allocation 優化要先判斷配置是否必要。保護狀態的 copy 是合理成本，高頻熱路徑的重複配置才是優先目標。JSON marshal、slice 成長、map/list 複製與 buffer 建立都是常見來源；用 pprof 區分 inuse_space 與 alloc_space 後，再決定預配置、分頁、projection、payload 重用或 sync.Pool。

7.4 Observability pipeline、metrics 與 tracing

Wed, 22 Apr 2026 00:00:00 +0000

Observability pipeline 的核心責任是把服務訊號整理成可查詢、可聚合、可關聯的診斷資料。Log schema 描述單次事件，metrics 描述趨勢，trace context 描述跨元件路徑，profile 描述 runtime 成本；它們的責任不同，但應使用一致的識別欄位串起來。

本章目標

學完本章後，你將能夠：

分辨 log、metric、trace 與 profile 各自回答什麼問題
設計穩定的 correlation 欄位
讓 Go 服務輸出適合聚合的診斷訊號
在產生端控制敏感資料進入觀測管線
了解 dashboard 與 alert 為什麼需要依賴穩定欄位

前置章節

後續撰寫方向

Log、metric、trace、profile 分別回答哪些問題。
request_id、event_id、trace_id、span_id 與 correlation_id 如何分工。
OpenTelemetry 導入時，Go 程式碼應保留哪些清楚邊界。
Sensitive data policy 如何套用到 log、trace attribute 與 error event。
Dashboard 與 alert 應依賴穩定欄位，讓查詢與告警規則可以被重複執行。

【觀察】診斷資料要先可關聯，再談漂亮

Observability pipeline 的第一個要求是關聯能力。Log、metric、trace 的格式可以各自精緻，但欄位需要對齊，才能把同一筆請求、同一個事件、同一條 goroutine 路徑串起來。

通常會先建立幾個穩定欄位：

request_id
event_id
trace_id
span_id
user_id 或 tenant_id

【判讀】不同訊號回答不同問題

log：這次發生了什麼。
metric：這類事件發生得多不多、快不快、慢不慢。
trace：它在多個元件之間怎麼走。
profile：CPU、記憶體、goroutine 與等待成本落在哪裡。

如果某個問題要靠自由文字 log 去猜，通常代表欄位設計還不夠穩。

【策略】敏感資料要在產生端就攔住

敏感資料政策應在產生端執行。Go 服務應該在輸出 log 或 trace attribute 前就決定哪些資訊可以外送。

常見要注意的資料有：

token
email
身分證號
raw payload
內部路徑與配置

【執行】結構化 log 是 pipeline 的起點

當 Go 服務使用結構化 log 時，最重要的是欄位穩定與語意清楚。這些 log 後面可能會被：

集中式 log system 搜尋
metric extraction 轉成趨勢指標
alert rule 用來偵測異常

所以 log 欄位要維持穩定命名，分類資訊要放在結構化欄位裡。

【延伸】診斷和容量規劃要串在一起

觀測資料不只是事後排障，也會反過來影響容量規劃與 release 判斷。當你看到 goroutine 數、queue lag、DB latency 或 retry rate 持續變高，就代表系統邊界已經開始吃緊。

本章不處理

本章不會綁定特定 observability SaaS。教材重點會放在 Go 服務如何輸出穩定訊號，讓不同收集平台都能使用。

和 Go 教材的關係

這一章承接的是 Go 的結構化日誌與 runtime 診斷；如果你要先回看語言教材，可以讀：

Datadog Continuous Profiler

Fri, 15 May 2026 00:00:00 +0000

Datadog Continuous Profiler 的核心責任是把 production profile 接到 SaaS APM、deployment marker、service tag 與 release regression workflow。它適合已經使用 Datadog APM / metrics / logs 的團隊，重點在讓 slow request、resource saturation、deploy version 與 profile diff 能在同一個操作介面中對齊。

定位

Datadog Continuous Profiler 是 Datadog APM 的 production profiling add-on、跟 Datadog Logs / Metrics / Traces 同 plane、共用 service tag、env tag、version tag 與 query bar。它的核心責任是把 production profile 接到 SaaS APM、deployment marker、service tag 與 release regression workflow，讓 slow request、resource saturation、deploy version 與 profile diff 能在同一個操作介面中對齊。

跟 Pyroscope / Parca 這類 OSS profiler 比、Datadog Continuous Profiler 走 ecosystem-bundled 路線 — profiler 本身不獨立計費、跟 APM host 一起進 business unit 預算、profile data 直接跟 trace_id、deploy marker、log query 在同一介面 cross-link。OSS profiler 走 standalone deployment、profile store 自管（ClickHouse / object storage）、跟 observability 其他 plane 要自己 wire（grafana correlation、自寫 trace_id mapping）。差異在 跨 signal 的 query continuity 跟組織計費歸屬、flame graph 本身的視覺呈現相近。

這個定位讓 Datadog Continuous Profiler 接到 9.9 Performance Improvement Loop 與 4.9 Continuous Profiling。它的價值在於降低 profile diff 的交接成本；它的代價在於 SaaS 成本、agent 設定、資料保留與 vendor 約束。

最短判讀路徑

判斷 Datadog Continuous Profiler deployment 是否健康、最少看四件事：

Agent / SDK profiling 是否真的 enabled：Datadog Agent 跑著不等於 profiler 開了 — 各語言要在 SDK init 加 profiling_enabled=true 或環境變數 DD_PROFILING_ENABLED=true、Go / Java / Python / Node / Ruby / .NET 的開啟方式跟覆蓋的 profile type（CPU / heap / goroutine / lock / wall time）各不同
Service / version / env tag 紀律：profile 沒有 service + env + version tag 就無法 diff、release marker 也對不上 — CI 要把 git SHA 或 release tag 注入 DD_VERSION、deploy pipeline 要打 deployment marker API
Sampling rate 跟 production coverage：profiler 預設 60s 採一次、低流量服務或 short-lived 任務可能 sample 不到 hot path — 對 ultra-low latency / burst workload 要評估 sampling 是否還抓得到 regression signal
Profile ingestion cost / retention：profile 是按 APM host 計費、但 profile event 量隨 service 數量 + sampling rate 漲、retention 預設 7 天（custom retention 另計）— 大型 deployment 要做 service-level enable/disable governance

適用場景

Release regression 定位適合 Datadog Continuous Profiler。當 canary 或 release candidate 的 p99、CPU、memory 或 cost per request 退化，團隊可以用 deployment marker 對比 release 前後 profile，找出變寬的 call stack。

APM-to-profile drilldown 適合 Datadog Continuous Profiler。慢 request 可以從 service、endpoint、trace 或 span 往下切到 profile，讓工程師知道 latency 是 DB、network、runtime、serialization、lock 還是 CPU hot path。

多語言 SaaS 團隊適合 Datadog Continuous Profiler。團隊如果同時維護 Go、Java、Python、Ruby、Node.js 或 .NET 服務，SaaS profiler 可以用統一 tag、dashboard 與權限模型管理。

選型判準

判準	Datadog 的價值	需要補的能力
APM 整合	trace、service、endpoint、profile 可串接	service tag 與 deploy label 紀律
Deployment marker	release 前後 profile diff 容易建立	release pipeline 與版本標記整合
SaaS 操作	低自管成本、跨團隊易查詢	成本治理、資料保留與 vendor 約束
多語言支援	多 runtime 用同一套操作介面	各語言 agent overhead 與覆蓋差異

APM 整合價值來自上下文連續。Metrics 告訴你 CPU 上升，trace 告訴你 endpoint 變慢，profile 告訴你哪段 code path 變貴；Datadog 的優勢是把這些訊號放進同一個查詢與 dashboard 流程。

Deployment marker 價值來自 release gate。Profile diff 如果能對齊 commit、version、environment 與 canary cohort，就能成為 6.13 Performance Regression Gate 的 evidence。

核心取捨表

取捨維度	Datadog Continuous Profiler	Pyroscope	Parca
部署模型	SaaS only、跟 Datadog Agent / APM 綁	OSS self-host / Grafana Cloud SaaS	OSS self-host（Polar Signals SaaS 選）
計費模型	跟 APM host 計費（profile 不獨立 metering）	OSS 免費 / Grafana Cloud 按 ingestion	OSS 免費 / SaaS 按 host
Profile 採集方式	Language SDK（pull 採樣）	SDK + eBPF agent	eBPF-first、language-agnostic
Trace correlation	強 — trace_id 自動 link 到 flame graph	中 — 要自己 wire OTel trace_id	弱 — 偏 eBPF profile、trace 整合較淺
視覺 / Workflow	APM service view + Profile diff + Code Hotspot in IDE	Grafana flame graph + diff、跟 Loki / Tempo 同 UI	Parca UI 簡潔、偏單純 profile 探索
多語言支援	Go / Java / Python / Node / Ruby / .NET / PHP 官方 SDK	同 + 社群 SDK；eBPF 補 native binary	eBPF-only、不挑語言但 symbol 解析較吃力
Vendor lock-in	高 — profile 跟 APM workflow 綁、退場要重建 dashboard	低 — OSS、profile 格式相對開放	低 — OSS、pprof 格式相容
適合場景	Datadog-heavy org、APM / log / metric 已用	Grafana stack 已用、要省 license	eBPF-first、low-overhead always-on

選 Datadog Continuous Profiler 的核心訴求：Datadog 已是 observability backbone + 要 APM trace ↔ profile drilldown 是 first-class workflow + 接受 SaaS 計費 + 接受 SDK overhead trade-off。如果 Datadog 不是既有平台、單純為了 profiling 引入 Datadog 通常成本不划算、改走 Pyroscope / Parca。

跟一次性 runtime profiler（pprof、async-profiler 手動跑）的差異是時間維度。一次性 profiler 適合本機或 incident 當下調查；continuous profiler 適合 baseline、release diff 與長期退化治理 — 兩者互補、不互斥。

進階主題

APM trace ↔ profile correlation：Datadog SDK 把 trace_id 注入 profile sample 的 label、APM trace view 上每個 span 可以直接點到「執行這段 span 時的 flame graph」。意義是 p99 latency 異常 trace 不只看 span 等待時間、能直接看到該 span 期間 CPU / lock / allocation 真正花在哪段 code。需要 SDK 版本支援 + trace context propagation 正確接上、舊版 SDK 或自寫 instrumentation 容易斷鏈。

Endpoint profiling：profile 按 HTTP endpoint / RPC method 切片、不只看 service 整體 hot path。意義是 新加的 endpoint 即便 traffic 小、也能單獨看它的 CPU / allocation cost、不會被 service 主流量稀釋。對 multi-tenant API、A/B test endpoint、internal admin endpoint 的退化偵測特別有用。

Code Hotspot in IDE：Datadog IDE plugin（IntelliJ / VS Code）把 production profile 的 hot line 直接 overlay 到 source code、工程師 review PR 時能看到「這個 function 在 production 佔 service CPU 12%」。降低 看 flame graph → 找 source 對應行 的 cognitive cost。對應 9.9 Performance Improvement Loop 中「production signal → code change」的 feedback loop 縮短。

Profile diff（baseline vs candidate）：Datadog 內建 diff view、選兩個 time window 或兩個 version tag、直接看 flame graph 哪些 frame 變寬 / 變窄。是 6.13 Performance Regression Gate 的核心 evidence — canary 跑完 30min、自動拉 baseline vs candidate diff 報告、超過 threshold 阻擋 promote。

Notebooks correlation：Datadog Notebooks 可以把 profile flame graph、APM trace、metric chart、log query 排在同一份文件。incident post-mortem 跟 release review 寫一份 notebook 比散落多個 dashboard tab 更可追溯、也接 evidence package 規範。

排錯與失敗快速判讀

SDK overhead 在 production 過高：profiler 預設 overhead < 2% CPU、但 wall-time profiling / allocation profiling 全開可能到 5%+ — canary 一台量測、按 profile type 分別 enable、不要全部一次開
Sampling rate 太低 / false negative：short-lived job（< 60s）或 low-traffic service 可能整個生命週期沒被 sample 到、看不到 hot path — 改成事件觸發 profile（on-demand profiling API）或拉高該 service 的 sampling rate
Profile 沒有 version tag / 無法 diff：deploy pipeline 沒注入 DD_VERSION、release marker 對不上 — 補 CI 環境變數、用 dd-trace SDK 自動讀 git commit SHA、跑 staging 驗證 diff view 能顯示 version
Trace ↔ profile drilldown 斷鏈：SDK 版本太舊、或 trace context 在非同步 / queue handler 沒 propagate — 升 SDK + 補 trace context propagation、用一條已知慢 trace 驗證能不能跳到 flame graph
Profiling cost spike：新 service 開啟 profiling、或某 service profile event 暴增（exception 路徑反覆採樣）— 看 Datadog usage dashboard 的 profile host hour、對嫌疑 service 暫關 profiling 觀察 cost 曲線、再 tune sampling rate
Flame graph symbol 解析失敗 / 顯示 ? frame：缺 debug symbol、stripped binary、或語言 runtime 版本不支援 — 補 build 時保留 symbol、確認 SDK 版本 vs runtime 版本對應表
Lock profile 看不出 contention：某些語言（Go / Java）的 lock profiling 需要額外 flag（DD_PROFILING_BLOCK_ENABLED / DD_PROFILING_LOCK_ENABLED）— 預設沒開、要明確 enable 才看得到 lock contention flame graph

操作成本

Datadog Continuous Profiler 的主要成本是資料量與保留。Profile sample、tag cardinality、service 數量、environment 數量與 retention 都會影響費用與查詢體驗。

Agent 成本來自 runtime 差異。不同語言的 profiler 支援、overhead、可觀測維度與限制不同，導入時要用 canary service 量測 CPU、memory、latency 與 profile completeness。

Vendor 成本來自資料與 workflow 綁定。當 profile diff、release marker、APM drilldown 與 incident workflow 都在 Datadog 中，後續切換平台需要重新建立 tag schema、dashboard、retention 與 gate integration。

Evidence Package

Datadog Continuous Profiler 結果應回寫到 evidence package。最小欄位包括 service、version、environment、deploy marker、profile type、time range、comparison baseline、profile diff link、overhead estimate、known gap 與 owner。

欄位	Datadog 證據來源
Source	profiler view、profile diff、APM link
Time range	baseline / candidate profile window
Query link	Datadog profile、trace、dashboard link
Data quality	service tag、version tag、sampling status
Confidence	production coverage、agent overhead
Known gap	runtime coverage、tag drift、retention limit

Evidence package 的核心用途是讓 release regression 可追溯。Reviewer 要能從 failed gate 直接打開 profile diff，看出哪個 service、version、endpoint 或 call stack 造成資源成本變化。

案例回寫

Datadog Continuous Profiler 適合回寫 release regression 與 APM 整合案例。它可接 9.C23 Netflix Aurora consolidation 的 profile noise 降低、9.C25 Tubi feature store 的 low-latency hot path 定位、9.C3 Coinbase ultra-low latency exchange 的 z1d 單執行緒 hot path 分析、9.C7 Lyft 100+ 微服務的 per-service profile diff，以及 Datadog OTel migration practice 的 observability pipeline 整合。

這些案例的重點是上下文對齊。Datadog Profiler 頁引用案例時，要把 case 轉成 service tag、deploy marker、profile diff、trace drilldown 與 release gate evidence — 例如 Coinbase sub-ms 目標下、profile 必須對齊 RAFT consensus 跟 placement group 拓樸、才能解釋 hot path 為何在某些 epoch 才出現。

下一步路由

上游：9.9 Performance Improvement Loop
上游：9.8 效能可觀測性
跨模組：4.9 Continuous Profiling
平行：Pyroscope
平行：Parca
官方：Datadog Continuous Profiler documentation

Pyroscope

Fri, 15 May 2026 00:00:00 +0000

Pyroscope 的核心責任是提供開源 continuous profiling backend，讓團隊用 Grafana 生態保存、查詢、比較與視覺化 production profile。它適合偏 OSS-first、已使用 Grafana / Prometheus / Tempo / Loki 的團隊，重點在把 CPU、memory、allocation 與 profile diff 放進可自管 observability stack。Pyroscope 原為獨立 OSS 專案、2023 年被 Grafana Labs 收購、現分兩條產品線：Grafana Pyroscope（OSS、Apache 2.0、self-host）與 Grafana Cloud Profiles（商業 SaaS、走 Grafana Cloud 計費）。

服務定位

Pyroscope 在 continuous profiling 賽道上的差異點是 Grafana Labs 整合 + 多語言 SDK 覆蓋、而不是 profiling 演算法本身。跟 Parca 比、Parca 走 pprof + Prometheus-style label 的 CNCF / eBPF infrastructure profiling 路線、focus 在 system-wide 一次抓全機；Pyroscope 走 per-language SDK + Grafana stack 整合 的 developer-facing 路線、focus 在 application-level flame graph 與 release diff。跟 Datadog Continuous Profiler 比、Datadog 走 SaaS all-in-one + APM 同 trace context、profiling 自動跟 trace span 關聯；Pyroscope 走 self-host 可選 + Grafana 跨 signal、整合靠 Grafana dashboard 跟 explore link 而非 product-level deep linking。

這個定位讓 Pyroscope 接到 4.9 Continuous Profiling 與 9.9 Performance Improvement Loop。它的價值在於 OSS / Grafana 整合與可自管；它的代價在於 storage、retention、agent rollout 與營運責任要由團隊承擔。

最短判讀路徑

判斷 Pyroscope deployment 是否健康、最少看四件事：

Agent / SDK setup：是用 language SDK（in-process profiler、跟 application code 一起部署）還是 Grafana Alloy / Pyroscope agent（out-of-process、適合 binary-only 或無法改 code 的 workload）— 兩條路 overhead、覆蓋率、tag 注入方式都不同
Push or pull model：SDK 預設 push（application 主動把 profile sample 推到 Pyroscope server）、Alloy / agent 可走 pull（scrape pprof endpoint、跟 Prometheus 同模型）— push 適合 short-lived job / serverless、pull 適合 long-running service + Kubernetes service discovery
Grafana integration：是否在 Grafana datasource 設好 Pyroscope、explore 是否能跨 trace / log / profile 跳轉（Tempo trace → Pyroscope profile by service+span）、dashboard 是否內嵌 flame graph panel
Tag schema discipline：service / version / region / environment / pod 是否一致命名、deploy event 是否打 label 讓 baseline / candidate 比較可成立

四件事任一缺失、profile 就只是「能看 flame graph」而非「release gate evidence」、無法支撐 9.9 Performance Improvement Loop 的 diff workflow。

適用場景

自管 profiling backend 適合 Pyroscope。團隊若有資料主權、成本控制、內網部署或 OSS-first 要求，可以用 Pyroscope 保存 profile，降低 profile sample 外送帶來的治理成本。

Profile diff workflow 適合 Pyroscope。Release candidate、canary、baseline review 或 incident after-action 都可以用時間區間比較，找出 CPU、memory 或 allocation 的相對變化。

Grafana stack 整合適合 Pyroscope。若服務已經有 Grafana dashboard，profile link 可以放進 latency、CPU、memory、cost 或 release dashboard，讓 SRE 從聚合訊號跳到 callstack。

選型判準

判準	Pyroscope 的價值	需要補的能力
OSS / self-host	profile 資料可自管	backend storage、retention、upgrade
Grafana 整合	dashboard、explore、profile link 容易串接	tag schema 與 dashboard discipline
Profile diff	時間區間與版本對比直觀	deploy label 與 baseline 管理
多語言 agent	常見 runtime 可導入	agent overhead 與覆蓋差異量測

OSS / self-host 價值來自控制權。Profile 可能包含 function name、package path、tenant-specific code path 或敏感 business logic，自管能讓資料保存與存取控制更貼近內部規範。

Grafana 整合價值來自操作連續性。當 CPU dashboard、latency dashboard 與 deploy annotation 都在 Grafana 中，Pyroscope 能讓工程師從圖表直接切到 flame graph。

跟其他工具的取捨

Pyroscope 和 Datadog Continuous Profiler 的主要差異是平台責任。Pyroscope 偏 OSS / self-host / Grafana stack；Datadog 偏 SaaS all-in-one 與 APM product workflow。

Pyroscope 和 Parca 的主要差異是生態定位。Pyroscope 偏 Grafana profiling backend 與 developer-facing flame graph；Parca 偏 eBPF / infrastructure-wide profiling 與 CNCF 生態。

Pyroscope 和一次性 profiler 的主要差異是可比較性。一次性 profiler 擅長局部調查；Pyroscope 擅長讓 profile 成為 release baseline 與 incident evidence。

核心取捨表

取捨維度	Pyroscope（Grafana）	Parca	Datadog Continuous Profiler
部署模型	OSS self-host / Grafana Cloud Profiles SaaS	OSS self-host（CNCF Sandbox）	SaaS only
Profile 來源	language SDK + Alloy / agent（push 為主）	pprof scrape（pull）+ Parca Agent（eBPF）	Datadog Agent + language tracer 整合
語言覆蓋	Go / Python / Java / Ruby / .NET / Rust / Node	任何能輸出 pprof 的 runtime + eBPF system-wide	Go / Python / Java / Ruby / .NET / Node
Tag / label	Prometheus-style label + 自訂 tag	Prometheus-style label	Datadog tag（跟 APM 共用）
Diff workflow	時間區間 + label 對比 + flame graph diff UI	時間區間 + label 對比	自動跟 deploy event + trace span 關聯
整合方向	Grafana（Tempo / Loki / Mimir 互跳）	Prometheus / Grafana（弱整合）	Datadog APM / Logs / Metrics 同 plane
適合場景	Grafana-first、OSS-friendly、release diff 主流程	infrastructure-wide eBPF profiling、CNCF 生態	Datadog 已是主 observability、要 APM 連動

選 Pyroscope 的核心訴求：已用 Grafana stack + 多語言服務組合 + 要 OSS self-host 選項或預算敏感、profile 主要用途是 release diff / incident hot-path 定位、不需要 APM-level 自動 trace 關聯。

操作成本

Pyroscope 的主要成本是自管 backend。Profile ingest、storage、retention、compaction、backup、upgrade 與 dashboard ownership 都需要團隊負責。

Tag 成本來自查詢維度。service、version、region、environment、runtime、pod、tenant 這些 label 能提高定位能力，也會增加 cardinality、儲存與查詢成本。

Agent 成本來自 rollout 與 overhead。導入時要先選代表性服務，量測 profiler 對 CPU、memory、latency 的影響，再逐步擴大到 critical path。

Evidence Package

Pyroscope 結果應回寫到 evidence package。最小欄位包括 service、version、environment、profile type、baseline window、candidate window、profile diff link、tag set、retention policy、overhead estimate、known gap 與 owner。

欄位	Pyroscope 證據來源
Source	profile query、flame graph、diff link
Time range	baseline / candidate profile window
Query link	Grafana / Pyroscope explore link
Data quality	tag completeness、sampling status
Confidence	production coverage、agent overhead
Known gap	未覆蓋 runtime、tag drift、retention gap

Evidence package 的核心用途是讓 profile diff 成為 release artifact。Reviewer 要能從 release gate 打開 Pyroscope diff，確認變化來自 code path、runtime 行為、負載變化或 baseline drift。

進階主題

Grafana Cloud Profiles：商業 SaaS 版本、走 Grafana Cloud 計費（per-series 或 per-profile bytes）、適合不想自管 storage / retention / compaction 的團隊。跟 OSS Pyroscope 共用 SDK 跟 query API、可在 OSS 起步、規模到一定程度再遷移到 Cloud、避免廠商一開始就鎖死。

Flame graph diff：Pyroscope 的核心 release workflow — 選 baseline window（release 前 24hr）跟 candidate window（release 後 24hr）、UI 把兩張 flame graph 差異標紅綠、可直接看到哪個 function 變慢 / 變快。判讀要點是 baseline window 要排除部署當下的 warm-up / cache miss spike、否則 diff 噪音蓋過真實 regression。

多語言 SDK 覆蓋：Pyroscope 官方 SDK 覆蓋 Go / Python / Java / Ruby / .NET / Rust / Node.js — Go SDK 用 runtime/pprof 包裝、Java 走 async-profiler、Python 走 py-spy 風格 sampling profiler、Node.js 走 V8 sampling。各 SDK overhead 不一致（Java async-profiler ~1%、Python py-spy ~3-5%）、選型時要看代表性服務量測再 rollout、不能假設「都很低」。

Adhoc profiling：當 production SDK 沒裝、或想對 batch job / CLI tool 做一次性 profile、可用 Pyroscope CLI 上傳 standalone pprof file（pyroscope adhoc 或 profilecli）— 補位「標準 pprof endpoint 不夠用、但又不想長期 instrument」的情境。對 ad-hoc incident investigation 跟 batch job postmortem 特別有用。

Grafana Alloy 整合：Grafana Alloy（前 Grafana Agent）內建 Pyroscope receiver、可同時 scrape Prometheus metrics + tail Loki log + push Tempo trace + scrape Pyroscope profile、單一 agent 跨 four signal、降低 sidecar 數量跟維運成本。

排錯與失敗快速判讀

SDK overhead 過高 / latency p99 上升：profile sample rate 太高、或 Java async-profiler 在低 CPU host 競爭 schedule — 降 sample rate、staging 量測 CPU / latency delta 確認 < 3% 再 promote
Push agent 跟 pull agent 取捨錯：short-lived job 用 pull 結果還沒被 scrape 就 exit、long-running service 用 push 結果 Pyroscope server 過載 — short-lived / serverless 走 SDK push、long-running + Kubernetes service discovery 走 Alloy pull
Label cardinality 爆 / storage 跟查詢都慢：tag 加了 pod name / request ID / user ID 等高 cardinality 維度 — 限制 tag 為 service / version / region / environment / cluster 等低 cardinality、高基數維度走 trace / log 別放 profile
Baseline / candidate diff 全是噪音：baseline window 沒對齊流量模式（off-peak vs peak）、或 deploy label 沒打 — 要求 release pipeline 自動寫 version / deploy_id label、diff window 跨完整流量週期（24hr or 7day）
Grafana datasource 連不到 / explore 跳轉失敗：datasource URL 設錯、或 service / span tag 不一致 — Tempo trace 用的 service.name 要跟 Pyroscope service label 對齊、否則 cross-signal 跳轉斷裂
Storage / retention 失控：profile 保留太久、SmartStore-like 冷儲存沒設 — Pyroscope OSS 支援 object storage（S3 / GCS）backend、長 retention 必開、不然 PV 會爆

何時改走其他服務

需求形狀	改走
已用 Datadog APM、要 trace ↔ profile 自動關聯	Datadog Continuous Profiler
要 eBPF system-wide / infrastructure profiling	Parca
不想自管 backend、但要 Grafana stack	Grafana Cloud Profiles（商業 SaaS、同 SDK）

案例回寫

Pyroscope 適合回寫 OSS observability 與 release diff 案例。它可接 9.C23 Netflix Aurora consolidation 的 profile noise 降低、9.C25 Tubi feature store 的 hot path 定位、9.C12 Riot Games EKS multi-cluster 的 single-tenant per game profile 隔離、9.C19 Capcom 遊戲後端的 30% 成本下降 hot path 分析，以及 9.9 Improvement Loop 的 baseline / candidate profile diff。

這些案例的重點是可比較 profile。Pyroscope 頁引用案例時，要把 case 轉成 tag schema、baseline window、candidate window、flame graph diff 與 release gate evidence — 例如 Riot Games 246 cluster 的 tag schema 必須涵蓋 game / region / cluster 三維、才能避免「跨遊戲混合 profile」的歸因錯誤。

下一步路由

Parca

Fri, 15 May 2026 00:00:00 +0000

Parca 的核心責任是用開源 continuous profiling 與 eBPF 路線建立 infrastructure-wide profile evidence。它適合需要低侵入、跨 process、跨 service、偏平台層的 profiling 團隊，重點在用 always-on profile 找出 CPU、memory、runtime 與 kernel / user space 的資源熱點。

服務定位

Parca 是 Polar Signals 主導的 OSS continuous profiling、特色是 eBPF-based 採集 + pprof 標準格式 + Prometheus-style 拉取與 label 模型。它跟 Pyroscope 是 OSS 同類、跟 Datadog Continuous Profiler 則是 OSS / 自管 vs SaaS / APM 整合的差異。eBPF agent 直接從 kernel 採 stack trace、不需要 application 改 code 或注入 runtime agent；pprof 格式讓既有 Go / Java / Python 工具鏈可以直接讀；Prometheus-style scrape 讓 Parca server 跟 metrics 用同一套 service discovery 與 label。

最短判讀路徑

判斷 Parca 部署是否能撐起 platform-wide profiling、最少看四件事：

eBPF agent deploy：Parca Agent 走 DaemonSet 跑在每個 node、需要 kernel ≥ 4.18（CO-RE / BTF）、SYS_ADMIN 或 PERF_EVENT capability、host PID namespace。受管 Kubernetes（GKE / EKS / AKS）的 worker node 是否允許這個權限是第一個判讀點
Parca server scrape：server 跟 agent 走 pull-based、Prometheus-style ServiceMonitor / scrape config、label 跟 metrics 同模型（namespace / pod / container / node）。scrape interval、retention、storage backend（FrostDB 內建 / object storage）要明確
pprof query：profile 以 pprof format 存、Parca UI 提供 flame graph 與 compare view、也可 export pprof file 給 go tool pprof 或其他既有工具離線分析
Grafana integration：Parca 提供 datasource plugin、profile 可以跟 metrics / log / trace 在 Grafana 同一頁 correlate、配 Pyroscope 或 Tempo 形成 observability 對齊

四件事任一缺失、就是 profiling control plane 還沒上線的待補項目。

定位

Parca 適合平台團隊建立 profiling control plane。當問題橫跨 Kubernetes cluster、node pool、multi-service path 或 shared runtime 成本，Parca 能從更接近 infrastructure 的角度收集 profile。

這個定位讓 Parca 接到 9.5 瓶頸定位流程與 4.9 Continuous Profiling。它的價值在於低侵入與平台廣度；它的代價在於 eBPF 支援、symbolization、storage、權限與平台維運責任。

適用場景

Infrastructure-wide profiling 適合 Parca。平台團隊可以觀察 cluster、node、namespace、service 與 process 的 CPU 熱點，找出共同 library、runtime、sidecar、agent 或 kernel path 的成本。

Kubernetes 平台適合 Parca。當服務在多 namespace、多 workload、多 node pool 上運作，Parca 可以把 profile 維度接到 pod、container、node、namespace 與 label。

低侵入 profiling 適合 Parca。eBPF-based profiling 可以降低 application instrumentation 成本，讓團隊先取得廣域視角，再對特定服務加更細的 runtime profiler 或 APM 整合。

選型判準

判準	Parca 的價值	需要補的能力
eBPF / low overhead	低侵入取得廣域 profile	kernel / runtime 支援與權限治理
Platform-wide	node、namespace、service 維度可對照	Kubernetes label 與 ownership discipline
Open source	profiling platform 可自管	storage、retention、upgrade
Compare / diff	profile compare 支援退化定位	deploy label、baseline 與 symbolization

eBPF / low overhead 價值來自平台廣度。團隊可以先觀察整個基礎設施的 CPU 熱點，再決定哪些服務需要更深入的 application-level profiling。

Platform-wide 價值來自共同成本治理。Sidecar、agent、logging library、serialization library 或 runtime upgrade 的成本可能散在多個服務中，Parca 這類工具能把分散成本聚合回平台決策。

跟其他工具的取捨

Parca 和 Datadog Continuous Profiler 的主要差異是平台模型。Parca 偏開源、自管、eBPF 與 infra-wide profiling；Datadog 偏 SaaS、APM drilldown、deployment marker 與產品化 workflow。

Parca 和 Pyroscope 的主要差異是視角。Pyroscope 偏 Grafana / application profiling backend；Parca 偏 eBPF、Kubernetes / infrastructure-level profiling 與平台團隊治理。

Parca 和 language runtime profiler 的主要差異是導入方式。Runtime profiler 能提供語言特定維度；Parca 能先提供低侵入廣域 profile，但 symbolization 與語言細節需要額外治理。

核心取捨表

取捨維度	Parca	Pyroscope	Datadog Continuous Profiler
採集方式	eBPF agent（kernel-level、unwound）	eBPF + SDK 雙路、語言 SDK 較豐富	APM agent 內建、語言 SDK 整合
Profile format	pprof（Google 標準）	自家 + pprof export	Datadog proprietary、可 export pprof
採集模型	Pull-based、Prometheus-style scrape	Push or pull（Grafana Agent）	Push to Datadog backend
Label 模型	Prometheus label（namespace / pod）	Grafana label	Datadog tag
部署模型	Self-hosted OSS + Polar Signals SaaS	Self-hosted OSS + Grafana Cloud SaaS	SaaS only
Storage	FrostDB 內建 / object storage	自家 storage / Grafana backend	Datadog managed
APM 整合	弱 — 走 Grafana correlation	中 — Grafana stack 整合	強 — trace ↔ profile drilldown 內建
適合場景	Platform team 自管、Prometheus stack	Grafana stack 已用、應用層 profiling	已用 Datadog、APM-first、SaaS-only 可

進階主題

Polar Signals Cloud：Parca 上游公司 Polar Signals 提供 managed SaaS — agent 一樣走 OSS、server / storage / UI 託管。適合不想養 Parca server 又要 OSS agent 路線的團隊。差異點是 ingestion cost 跟 retention 由 SaaS 計費、license / data residency 要看合約。

Prometheus 同 label model：Parca 的 service discovery、scrape config 跟 label 跟 Prometheus 幾乎同形 — 既有 ServiceMonitor、relabel rule、Kubernetes SD 可以直接複用。意義是 profile 維度跟 metric 維度天然對齊、namespace=foo, service=bar 在兩邊都成立、cross-signal correlation 不需要再 mapping。

Compare profiles（diff before/after deploy）：Parca UI 支援選 baseline window 跟 candidate window 做 flame graph diff、顏色標示哪個 stack frame 變胖變瘦。配 9.9 Performance Improvement Loop 的 deploy marker、可以把「這次發版讓 CPU +15%」直接歸因到具體 frame。

Continuous profiling vs sampling-only：傳統 profiler 是「出問題時手動跑 30 秒」、Parca 是「always-on、低頻率持續採」。差異是 事後回溯能力 — incident 發生時直接拉時間區間的 profile、不用重現問題；sampling-only 工具在偶發 spike 時抓不到現場。代價是 storage 跟 agent overhead 要長期治理。

操作成本

Parca 的主要成本是平台維運。Agent / scraper、server、storage、retention、symbolization、upgrade 與 Kubernetes 權限都需要平台團隊負責。

Symbolization 成本來自可讀性。Profile 如果缺 symbol、debug info、build ID 或 source mapping，flame graph 會變成難以行動的 address / binary offset，因此 build pipeline 要保留符號資訊策略。

權限成本來自 eBPF 與 node visibility。低層 profiling 需要足夠 host / kernel 權限，受管 Kubernetes、security policy、multi-tenant cluster 與 compliance 要先評估。

Evidence Package

Parca 結果應回寫到 evidence package。最小欄位包括 cluster、namespace、service、node pool、profile type、baseline window、candidate window、compare link、symbolization status、agent overhead、known gap 與 owner。

欄位	Parca 證據來源
Source	Parca query、compare view、flame graph
Time range	baseline / candidate profile window
Query link	Parca UI / dashboard / metrics link
Data quality	label completeness、symbolization status
Confidence	cluster coverage、agent overhead
Known gap	未覆蓋 node、symbol 缺失、kernel 限制

Evidence package 的核心用途是把平台層 profile 變成容量決策。Reviewer 要能看到成本來自 application code、runtime、sidecar、kernel path 還是 shared library，並把結果回寫到 owner。

排錯與失敗快速判讀

eBPF agent 起不來 / kernel 不支援：舊 kernel（< 4.18）或缺 BTF / CO-RE 支援、受管 Kubernetes 不開 SYS_ADMIN — 先確認 node OS image、必要時換 distribution 或升級 worker node pool
Profile storage 暴增：scrape interval 太密 + retention 沒設 + label cardinality 爆炸（把 request-id 放進 label）— 降頻、限 retention window、把高 cardinality 維度移出 profile label
Symbol resolution 失敗 / flame graph 全是 address：build pipeline 沒保留 debug info、stripped binary、容器 image 不含符號 — 在 build 階段保留 debug symbol、用 separate debuginfo 上傳 Parca debuginfod、或在 image 保留 unstripped binary
JIT 語言（Java / Node.js）stack 不完整：eBPF 看到的是 native frame、JIT-compiled frame 需要額外 perf map / JVMTI agent — 補語言層 profiler 或開 JIT symbol dump
Agent overhead 影響 production：sample rate 預設 19 Hz、特定 workload 可能仍敏感 — 在 noisy neighbor 敏感的 node pool 降頻或排除特定 namespace
多 cluster scrape 中心化太重：單一 Parca server 拉 N 個 cluster 變瓶頸 — 改 federation 模型、每 cluster 一個 Parca server、上層做 query aggregation

案例回寫

Parca 適合回寫平台層與 multi-service 成本案例。它可接 9.C34 GCP 130K node GKE cluster 的 cluster-scale profiling 需求、9.C12 Riot Games EKS multi-cluster 的 246 cluster 平台成本治理、9.C23 Netflix Aurora consolidation 的 shared platform noise 降低、9.C33 Maersk + Bosch Azure AKS 的傳統產業多 BU 平台層歸因，以及 9.C19 Capcom DynamoDB + EKS 跨遊戲共用後端的 profile 切分。

這些案例的重點是平台視角。Parca 頁引用案例時，要把 case 轉成 cluster / namespace / service label、compare window、symbolization、shared library cost 與 owner routing — 例如 GCP 130K-node 規模下，Parca 自身的 storage / scrape capacity 也成為 profile target、不只是觀測 application。

兩個典型用途值得單獨點名：

Performance regression detection：發版前後拉 compare profile、把「這次 release 讓 P99 CPU +18%」歸因到具體 stack frame。配 9.C12 Riot Games EKS multi-cluster 的 246 cluster 規模、單一 service rollout 在 always-on profile 下可秒級看出 hot path 變化、不需要等 SRE 跑手動 pprof
Cost engineering：把 CPU profile 折算成 node 成本、找出 shared library / runtime / sidecar 的 hidden cost。配 9.C23 Netflix Aurora consolidation 的 platform consolidation 思路、profile 證據可以決定要不要重寫熱點、換 library、還是接受成本

Profiling on Tarragon

案例：效能分析實戰

先備知識

問題背景

現有設計

效能問題

進階解決方案

分析目標

實作步驟

步驟 1：使用 cProfile 進行函式級分析

步驟 2：使用 pstats 分析結果

步驟 3：使用 line_profiler 進行行級分析

步驟 4：分析正則表達式效能

步驟 5：優化建議與驗證

完整程式碼

分析結果範例

設計權衡

什麼時候該做效能分析？

練習

基礎練習：用 cProfile 分析排序函式

進階練習：用 line_profiler 找出熱點程式碼

挑戰題：比較不同正則表達式寫法的效能差異

延伸閱讀

3.2 pprof 基礎診斷流程

本章目標

【觀察】效能問題需要先問對問題

【判讀】pprof endpoint 是受控診斷入口

【執行】heap profile 看記憶體保留與配置壓力

【判讀】heap profile 要連回資料結構

【執行】goroutine profile 看存活與卡住路徑

【執行】CPU profile 看熱路徑

【策略】block 與 mutex profile 需要先啟用取樣

【執行】trace 看排程與延遲

【策略】診斷流程要先保留現場

本章不處理

和 Go 教材的關係

小結

8.2 效能調優實戰

學習目標

先備知識

效能分析流程

真實案例：Hook 驗證器

步驟 1：測量基準效能

步驟 2：找出瓶頸

正則表達式預編譯

問題：重複編譯的開銷

解決方案：預編譯

效能測量

快取策略：lru_cache

適用場景

實作範例：分支保護檢查

加入 lru_cache

快取命中率分析

lru_cache 的注意事項

資料結構選擇

O(n) vs O(1) 的差異

真實案例：測試檔案存在性檢查

何時使用哪種資料結構

優化的代價

維護成本

何時不該優化

優化前檢查清單

思考題

實作練習

練習 1：分析現有程式碼

練習 2：實作帶統計的快取

練習 3：效能比較

延伸閱讀

入門系列

進階系列

官方文件

外部資源

3.3 goroutine leak 偵測

本章目標

【觀察】goroutine leak 是生命週期沒有結束

【判讀】每個 goroutine 都要有退出原因

【策略】I/O 阻塞需要 deadline 或 close

【執行】done channel 讓測試能觀察退出

【執行】ticker 必須停止

【判讀】pprof goroutine profile 看 stack pattern