DOCSEARCHbyAlgolia
Submit Docs

pprof

repository·main·Indexed 27 days ago

https://github.com/google/pprof

A tool for the visualization and analysis of profiling data that reads profiles in the profile.proto format. pprof generates text and graphical reports, including callgraphs and flame graphs, to analyze callstacks and symbolization information. It supports three modes of operation: report generation, an interactive terminal, and a web interface for interactive data exploration, source annotation, and disassembly.

Tokens
5.9K
Snippets
9
Records
39
Agent score
81%

What's inside pprof

  1. Understand the profile.proto data format

    main

    profile.proto is a data representation for profiling data, independent of the collection method. On disk, it is stored as a gzip-compressed protocol buffer. A profile consists of a collection of samples, where each sample associates measurement values with a call stack (a list of location IDs).

    Key components of a profile include:

    • Samples: Measurements and associated call stacks. Identical call stacks can be merged by summing their values.
    • Locations: Unique program locations (often instruction addresses) referenced by samples.
    • Functions: Program functions containing human-readable (demangled) and system (mangled) names, and source file information.
    • Mappings: Binary information (similar to Linux /proc/self/maps) used to symbolize instruction addresses.
    • String Table: An index of all strings used in the profile to save space.
    • Labels: Annotations (string or numeric) used to differentiate samples with identical locations (e.g., distinguishing between different allocation sizes).

  2. View disassembly on Windows

    main
    To view disassembly for Go programs compiled as Windows executables, you must build the executable using go build -buildmode=exe. Additionally, LLVM or GCC must be installed so that addr2line and nm are available to pprof for symbolization.

  3. View disassembly in the pprof web interface

    main

    To view the disassembly of functions in instruction order without interleaved source code, select Disassemble from the View menu.

    Note: This operation can be slow and voluminous; it is recommended to focus on only one or a few routines before selecting this view.

  4. Interpret callgraph visual elements

    main

    When viewing graphical reports (SVG, DOT, etc.), use these visual cues to analyze the data:

    Nodes (Locations):

    • Color: Red (large positive cumulative), Green (large negative cumulative), Grey (near zero).
    • Font Size: Larger font indicates larger absolute flat values.

    Edges (Calls):

    • Weight (Thickness): Thicker edges indicate more resources used along that path.
    • Color: Red (large positive), Green (large negative), Grey (near zero).
    • Style:
      • Solid: A direct call between locations.
      • Dashed: Some locations between the two connected locations were removed/trimmed.
      • (inline): The call has been inlined into the caller.

  5. Install pprof

    main

    To build and install pprof, ensure you have a supported version of the Go development kit installed. Graphviz is an optional prerequisite used if you want to generate graphical visualizations.

    Run the following command to install the binary to your $GOPATH/bin (defaulting to $HOME/go/bin):

    go install github.com/google/pprof@latest

  6. Use pprof in different usage modes

    main

    pprof supports three primary modes of operation depending on your goal:

    1. Report Generation: Generate a specific report format and exit immediately. pprof <format> [options] source

    2. Interactive Terminal: Start an interactive shell to run commands manually. Type help for available commands. pprof [options] source

    3. Web Interface: Start an HTTP server to view the profile via a web browser. pprof -http=[host]:[port] [options] source

    pprof <format> [options] source
pprof [options] source
pprof -http=[host]:[port] [options] source

  7. Manage refinement settings with the Config menu

    main

    The Config menu allows you to save and restore your current view refinements (such as focus and hide lists).

    • Save as ...: Saves current refinements under a custom name.
    • Default: Removes all refinements and returns to the default view.
    • Named Configurations: Selecting a saved configuration applies it. Configurations marked with a ✓ are currently active. Use the 🗙 icon next to a configuration to delete it.

  8. Use the Flame graph view in the pprof web interface

    main

    The Flame graph view provides a compact representation of the call stack.

    • Structure: Boxes represent stack frames. Caller boxes are positioned directly above callee boxes. The width of a box is proportional to the sample value (e.g., time) accounted for by that frame.
    • Coloring: Boxes are colored based on the package name (e.g., all std:: functions in C++ share a color).
    • Viewing Callers: Unlike traditional flame graphs, clicking a box in pprof expands the graph to show the call stacks leading to that function.
    • Inlining: Inlined functions are indicated by the absence of a horizontal border between the caller and the callee.
    • Diff Mode: When using the --diff_base option, box width represents the sum of increases and decreases in the sub-tree. Shaded regions indicate net changes: red for a net increase and green for a net decrease.

  9. Use pprof with Linux Perf

    main
    To analyze perf.data files generated by the Linux perf tool, use the perf_to_profile program from the perf_data_converter package to convert the data into a format pprof can read.

  10. Use the Graph view in the pprof web interface

    main

    The Graph view is the default visualization in the local web interface. It displays a directed graph where nodes represent functions and edges represent caller/callee relationships.

    • Interpreting Edges: An edge between two functions (e.g., FormatPack $\rightarrow$ FormatUntyped) indicates a call relationship. The value on the edge (e.g., 5.72s) represents the time spent in the callee (and its descendants) when called from the caller.
    • Navigation: You can drag the display with the mouse and zoom in/out using the scroll wheel or touch gestures.

  11. Analyze top functions in the pprof web interface

    main

    The Top functions table provides a summary of the most significant functions in the profile. It tracks two metrics:

    • flat: The number of profile samples directly in this function.
    • cum (cumulative): The number of profile samples in this function and all its callees.

    The table is sorted by flat by default. You can click the Cum header to sort by cumulative samples.

  12. View annotated source code in the pprof web interface

    main

    To inspect the source code of a specific function with performance data:

    1. Access Source: Right-click a function box in the Flame graph and select Show source in new tab, or select Source from the View menu.
    2. Interpreting Annotations: Each line shows two numbers:
      • The first number: Time spent in that specific line (excluding time in called functions).
      • The second number: Total time including time spent in functions called from that line.
    3. Deep Dive: Clicking a line expands the view to show inlined function calls (displayed in blue and indented) and the corresponding assembly code (displayed in green).