stackcollapse-ghc

Program to fold GHC prof files into flamegraph input

Motivation

The reasons why this package exists despite other packages with similar functionality (not including the NIH syndrome) boil down to:

• it does only one thing (stack collapsing), so it's up to the user to install flamegraph scripts, pass options etc (in my eyes it's not a limitation, on the contrary),
• output control: annotations (color profiles), extending traces from a configured set of modules with the source locations or toggling qualified names,
• precise ticks and/or bytes with -p reports,
• it's fast

Table of Contents

• Basic usage
  • Ticks
  • Allocations
• Cookbook
  • Colors
  • Qualified names
  • Source locations
  • Reverse flamegraphs
• All options
• Installation

Basic usage

(all the following examples assume you have installed flamegraph on your path)

Visualize ticks

If you have a detailed prof file (-P RTS option)

stackcollapse-ghc prof_file | flamegraph.pl --title 'Example' --subtitle 'Time' --countname ticks > path_to_svg

If you have a standard prof file (-p RTS option)

stackcollapse-ghc -p prof_file | flamegraph.pl --title 'Example' --subtitle 'Time' --countname ticks > path_to_svg

Visualize allocations

If you have a detailed prof file (-P RTS option)

stackcollapse-ghc --alloc prof_file | flamegraph.pl --title 'Example' --subtitle 'Bytes allocated' --countname bytes > path_to_svg

If you have a standard prof file (-p RTS option)

stackcollapse-ghc --alloc -p prof_file | flamegraph.pl --title 'Example' --subtitle 'Bytes allocated' --countname bytes > path_to_svg

Cookbook

Using distinct colors for modules

Works out of the box. You just need to tell the program which modules are "yours" (by default it only assumes Main) and pass the desired color scheme to the flamegraph script

stackcollapse-ghc -u Example prof_file | flamegraph.pl --title 'Example with colors' --subtitle 'Time' --countname ticks --color java > path_to_svg

(the traces coming from your modules are green under this palette)

Or you can use the mem pallette to track allocations

stackcollapse-ghc -u Example --alloc -p prof_file | flamegraph.pl --title 'Example with colors' --subtitle 'Bytes allocated' --countname bytes --color mem > path_to_svg

This is achieved by using a thing called annotations. stackcollapse-ghc adds the annotation _[j] to traces from modules in -u, _[i] to CAFs and _[k] to the "kernel" modules, such as GHC or System

Turning off qualified names

You might want to tone down the visual clutter in your flamegraph by turning off the qualified names for some modules. You can use the -u option for this just as in the color pallete examples. Traces from the modules that you have passed in -u will have unqualified names by default

stackcollapse-ghc -u Example -p prof_file | flamegraph.pl --title 'Example' --subtitle 'Time' --countname ticks > path_to_svg

If you want to use visual indications and retain qualified names you can use the following option

stackcollapse-ghc -Q -u Example -p prof_file | flamegraph.pl --title 'Example' --subtitle 'Time' --countname ticks --color java > path_to_svg

Adding source locations

If you want to see the source of the traces on the generated flamegraph, you can do it selectively by combining -u options to mark the modules for which you want to include locations, with -s

stackcollapse-ghc -s -u Example prof_file | flamegraph.pl --title 'Example with sources' --subtitle 'Time' --countname ticks > path_to_svg

Alternatively, you can simply include it for all traces (with or without -u depending on whether you need it for something else, such as colors or qualified names)

stackcollapse-ghc -S prof_file | flamegraph.pl --title 'Example with sources' --subtitle 'Time' --countname ticks > path_to_svg

"Reverse" flamegraphs

Sometimes it makes sense to to have functions at the bottom and their callers above them. This mode is called "reverse" flamegraph. You can make such graphs with stackcollapse-ghc (the real work is done by the flamegraph script)

stackcollapse-ghc prof_file | flamegraph.pl --reverse --title 'Reverse' --countname ticks > path_to_svg

All options

Usage: stackcollapse-ghc [OPTIONS] FILE
OPTIONS:
  -P                                            Process detailed prof file ('-P' or '-pa' options) (default)
  -p                                            Process standard prof file ('-p' option)
  -u module_name  --user-module=module_name     Name of an user module (may be repeated to add more than one). Matches the whole "hierarchy", so `MyModule` matches `MyModule` as well as `MyModule.Internal`
  -t              --time                        Collapse with respect to time (default)
  -a              --alloc                       Collapse with respect to allocations
  -S                                            Append source location to every function name
  -s                                            Append source location to functions defined in user modules
                  --no-source                   Do not append source location (default)
  -Q                                            Always use qualified functon names
                  --no-qualified                Do not use qualified function names
  -q                                            Use qualified names for functions not defined in user modules (default)
  -A              --annotations, --annot        Add annotations to output (j - user modules, k - GHC and System, i - CAFs)
                  --no-annotations, --no-annot  Do not add annotations to output

Installation

You can install it from Hackage or Stackage by using either cabal:

cabal v2-update
cabal v2-install stackcollapse-ghc

or stack

stack install stackcollapse-ghc