{
    "slug": "flamegraph",
    "term": "Flame Graphs for PHP Profiling",
    "category": "performance",
    "difficulty": "intermediate",
    "short": "A visualisation of sampled call stacks showing where CPU time is spent — the fastest way to identify hot paths in a PHP application.",
    "long": "Flame graphs (Brendan Gregg) visualise profiling data as stacked rectangles: x-axis represents cumulative time (width = % of samples), y-axis is call depth. Wide blocks at the bottom are the largest consumers. For PHP: Xdebug traces processed by flamegraph.pl, Blackfire profiler's built-in interactive UI, Tideways, or the lightweight SPX profiler. Sampling profilers (Blackfire, Pyroscope) have negligible overhead and can run in production. Instrumented profilers (Xdebug full trace) are precise but too slow for production. A 30-second flame graph from a live server will reveal more actionable insight than hours of reading code.",
    "aliases": [
        "flame graph",
        "profiling flame graph",
        "CPU flame graph"
    ],
    "tags": [
        "performance",
        "profiling",
        "debugging",
        "tools"
    ],
    "misconception": "Flame graphs show the slowest function calls at the top. Flame graphs show call stacks — the width of each bar represents time, and the top of the graph is the deepest stack frame. Wide bars near the bottom reveal the actual bottlenecks consuming CPU time.",
    "why_it_matters": "Flame graphs visualise stack trace samples over time — making it immediately obvious which functions consume the most CPU, collapsing complex profiler data into an actionable visual.",
    "common_mistakes": [
        "Not using flame graphs for PHP performance issues — running Xdebug profiler + speedscope/flamegraph.pl is a low-effort high-value analysis.",
        "Profiling in development instead of staging — the workload and data size differ significantly.",
        "Optimising tall thin flames — wide flames (broad base) indicate the real hot paths.",
        "Not sampling long enough — short profiles miss infrequent but expensive operations."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "profiling",
        "xdebug",
        "tail_latency",
        "php_jit"
    ],
    "prerequisites": [
        "profiling",
        "xdebug",
        "php_jit"
    ],
    "refs": [
        "https://www.brendangregg.com/flamegraphs.html",
        "https://blackfire.io/docs/introduction"
    ],
    "bad_code": "# Profiling with xdebug trace — no flame graph:\n; php.ini:\nxdebug.mode=trace\nxdebug.output_dir=/tmp/xdebug\n; Output: massive trace file, hard to analyse manually\n\n; Better — use SPX or Blackfire which generate flame graphs automatically:\n; SPX_ENABLED=1 SPX_FP_LIVE=1 in environment",
    "good_code": "// Generate flamegraph with SPX (easiest for PHP)\n// 1. Install: https://github.com/NoiseByNorthwest/php-spx\n// 2. Add to php.ini: extension=spx.so; spx.http_enabled=1; spx.http_key=dev\n// 3. Append ?SPX_KEY=dev&SPX_ENABLED=1 to any URL\n// 4. View flamegraph at /_spx\n\n// Or with Blackfire:\n// 1. Install Blackfire agent + PHP probe\n// 2. blackfire curl https://yourapp.local/heavy-endpoint\n// 3. Flamegraph available in Blackfire dashboard — click to drill into any frame\n\n// Read a flamegraph:\n// X axis = time (not chronological — alphabetical by call)\n// Y axis = call stack depth\n// Widest boxes = most cumulative time — optimise these first",
    "quick_fix": "Use Blackfire to generate flamegraphs of production PHP requests — the widest bars are your hotspots; Xdebug's profiler generates KCachegrind files you can open locally for the same visual",
    "severity": "info",
    "effort": "medium",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/flamegraph",
        "html_url": "https://codeclaritylab.com/glossary/flamegraph",
        "json_url": "https://codeclaritylab.com/glossary/flamegraph.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Flame Graphs for PHP Profiling](https://codeclaritylab.com/glossary/flamegraph) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/flamegraph"
            }
        }
    }
}